charness 3.2.0 → 3.3.1

package/.env.example

@@ -52,9 +52,9 @@ ALLOWED_GROUP_ID=
 # state.json). See plan §10.7.
 # DATA_DIR=/home/user/.charness-mybot
 
-# Voice transcription. Recommended: without GROQ_API_KEY, voice messages are
-# not transcribed unless you intentionally configure the OpenAI fallback below.
-# GROQ_API_KEY=
+# Voice transcription is NOT configured here: engines and their API keys live in
+# ~/.config/charness/stt.json (in the directory of this file's real location — beside the target when this
+# file is a symlink) — see SETUP.md "Voice input".
 
 # ── Advanced / only when your setup needs it ────────────────────────────────
 
@@ -62,9 +62,6 @@ ALLOWED_GROUP_ID=
 # cwd (for example, a custom systemd service). Normal launch uses $PWD instead.
 # WORK_ROOT=/home/user/src
 
-# OpenAI Whisper fallback for voice. Usually unnecessary when GROQ_API_KEY is set.
-# OPENAI_API_KEY=
-
 # Not needed for normal agent auth. Claude/OpenCode credentials are configured
 # through those CLIs themselves; set provider env vars only if a custom MCP,
 # OpenCode plugin, or auth resolver explicitly requires them.

package/DEVELOPMENT.md

@@ -74,6 +74,21 @@ Each adapter implements `AgentAdapter` from `src/types.ts`:
   `toolResult`, `subagentStatus`, `apiError`, `started`, `stopped`, `closed`,
   `error` (all emit `SessionKey` first)
 
+### Voice recognition (the engine chain and the local sidecar)
+
+A voice note walks an ordered chain of speech engines read from `stt.json` (`src/stt/`). The local GigaAM engine is
+the one engine that is a PROCESS of ours, owned by the bot like OpenCode's server but started on demand and stopped
+with its owner:
+
+```
+voice note ──> transcribeWithEngines ──> engine 1 (local) ──ensure──> sttSidecarOwner ──> gigaam_sidecar.py
+                  │   fall back on any      engine 2 (Groq)               │  adopt the record, or spawn;     (ONE process, 127.0.0.1:0,
+                  │   failure, no retry     engine 3 (your URL)           │  hosted outside the bot's tree    token, idle exit)
+                  └── last engine retries                                 └── DATA_DIR/stt/sidecar.json
+owner = the `charness hot` supervisor (a worker reload keeps the sidecar) or the plain bot process;
+the sidecar polls its owner and exits within ~2 s of its death, even after a SIGKILL.
+```
+
 ## Local development
 
 ```bash

package/README.md

@@ -25,8 +25,8 @@ These hold whichever surface you drive it from — the same core serves all of t
 
 - **Agent backends** — OpenCode (native server API over HTTP+SSE) and Claude Code (three backends — json-stream, per-turn and tmux)
 - **Sleeping agents** — a Claude json-stream topic's process is stopped when idle (or after every turn in per-turn mode) and the next message resumes the same conversation by itself, prompt cache still warm
-- **Several Claude accounts** — keep more than one Claude subscription signed in side by side and choose per topic which one a session runs on (`/accounts`); every account's usage windows are shown next to it. See [Several accounts](#several-accounts-accounts)
-- **Waits out usage limits** — when the agent hits a usage / session limit the bot reads the reset time out of the error (honouring the timezone the provider quotes), waits, then tells the agent to continue by itself and pins the "work resumed" message so a muted topic still notifies you; `/limits` turns waiting off per topic or skips a single resume. With a **fallback chain** (`/limits`: other Claude accounts, OpenCode providers and models, in your order of preference) the limit notice offers «🔁 Switch to …» buttons to move the topic to the next entry with room and continue at once — or the bot does it by itself when you turn switching on; across backends the new agent gets a context bridge with the previous one's last turns
+- **Several Claude accounts** — keep more than one Claude subscription signed in side by side and choose per topic which one a session runs on (`/accounts`); every account's usage windows are shown next to it, and `/limits` is a one-tap switch board over all of them and over the OpenCode providers. See [Several accounts](#several-accounts-accounts)
+- **Waits out usage limits** — when the agent hits a usage / session limit the bot reads the reset time out of the error (honouring the timezone the provider quotes; a mere warning such as `Approaching session limit · resets …` or the switch onto extra usage is not a limit), waits, then tells the agent to continue by itself and pins the "work resumed" message so a muted topic still notifies you; `/limits_autoswitch` turns waiting off per topic and `/limits` skips a single resume. With a **fallback chain** (`/limits_autoswitch`: other Claude accounts, OpenCode providers and models, in your order of preference) the limit notice offers «🔁 Switch to …» buttons to move the topic to the next entry with room and continue at once — or the bot does it by itself when you turn switching on; across backends the new agent gets a context bridge with the previous one's last turns
 - **Restart-safe** — agents run as external processes (tmux, `opencode serve`) that the bot re-adopts after a restart instead of killing them; a prompt sent while a session boots is buffered and replayed. See [Restart behaviour](#restart-behaviour)
 
 ### Telegram
@@ -48,7 +48,7 @@ setup, no extra dashboards — direct access to your own **OpenCode** /
 - **Reminders** — `/reminders` sets a plain reminder with inline buttons (how often, which day, what time, then the text by typing or voice); at the due time the bot posts and pins it itself, so even a muted topic notifies you. No agent, no bound folder, no date parsing — works in any topic, General included
 - **Inbound files** — photos / documents / video / audio sent to a topic are saved and announced to the agent; albums arrive as one prompt
 - **Outbound files** — the agent sends files back to you — a generated chart, a screenshot, a log, a rendered PDF — single files or albums, straight into the topic
-- **Voice input** — Whisper transcription via Groq (preferred) or OpenAI
+- **Voice input** — voice notes are transcribed by an ordered chain of engines — Groq, OpenAI or your own OpenAI-compatible server — set up in `/stt` (or `stt.json`); a local GigaAM engine is optional; if one fails, the next takes over
 - **Display verbosity and view** — `/verbosity` (plus `/thinking`, `/tool_results`, `/subagent`) per topic: detail `minimal|short|full`, and what the topic shows — `stream` (default), `stream_answers` or `answers` (only the agent's pinned answers, no stream)
 - **Time-aware prompts** — `/timestamps on` prepends each forwarded prompt's send time (local-offset ISO), so a days-long session knows what "yesterday" or "2 days ago" means; agent-facing only, per topic
 - **Reply context** — reply to a message in a topic and the quoted text is folded into the prompt the agent receives, so it sees what you point at without re-pasting; works for text, voice and files (a photo, a document, an album…), both agents; a reply TO a photo, file or voice note names it, with the path of the bot's saved copy when it has one
@@ -94,8 +94,8 @@ actually start an agent or terminal in the folder.
 | `/terminal` | Open a raw `$SHELL` in the bound folder — see [Raw terminal](#raw-terminal-terminal-telegram) |
 | `/claude_mode` | Switch this topic's Claude backend (json-stream ⇄ per-turn ⇄ tmux-scrape); bare shows a picker — see [Claude Code backends](#claude-code-backends-claude_mode) |
 | `/model` | Switch model through a two-level picker: providers, then that provider's models (10 per page). On OpenCode the first row is 🕘 Recently used — a flat list of the models picked before, across providers (bot-wide, most recent first, up to 10), one tap to switch; it appears once something has been picked. Each provider row has a 🙈 to hide it from the picker (bot-wide, persisted; 👁 brings it back) — `/model <provider/model>` still reaches a hidden provider. If OpenCode is waiting on an old provider's retry, the next prompt interrupts that wait and starts with the selected model instead of sitting queued behind it |
-| `/accounts` | Every account the bot works with, on one screen. **Claude accounts** (when you keep several subscriptions signed in): each profile with its email, plan (personal Pro/Max or corporate Team/Enterprise), how many topics use it and its usage windows, ✓ on the active one; tap a profile to switch this topic (a running session is restarted under it, same conversation — at the end of its turn if it is working); in **General** the pick becomes the default for all topics. Per profile: 🔑 signs it in again, 🗑 removes it (after a confirmation; for `default`, which IS `~/.claude`, «remove» signs it out — see below). The usage lines give each window's percentage USED and when it resets as a time from now (`5h 5% 🔄 in 4h · week 20% 🔄 in 5d 8h · Fable 4% 🔄 in 5d 8h`; «🔄 in 2h», «🔄 in 2d 1h», «🔄 in 30m»; Fable only on a plan that has its own weekly window); when the 5h window's reset is unknown the weekly one is shown in its place, and with no reset at all only the percentage. The hint paragraph under the account list says the percentages are used. «➕ Claude account» asks for a name and runs the sign-in. **OpenCode providers**: the connected ones are listed with a «🔌 Disconnect <provider>» button and a 🔑 (connect again) each (the disconnect asks, then removes the stored credentials; a provider OpenCode enables from an environment variable, e.g. `OPENROUTER_API_KEY`, stays active — the reply says so and points at hiding it in `/model`); «➕ OpenCode provider» asks for the provider id and continues with the connect flow (OAuth methods when available, otherwise an API key whose message is deleted from Telegram). What happens when an account hits a usage limit is set in `/limits`. Text forms: `/accounts add <name>`, `/accounts use <name>`, `/accounts login <name>`, `/accounts remove <name>`, `/accounts autoswitch on\|off`. `/account`, `/connect [provider [key]]` and `/disconnect [provider]` still work as hidden aliases (the menu lists only `/accounts`). See [Several accounts](#several-accounts-accounts) |
-| `/effort` | Set reasoning effort (per-thread) via inline buttons. Claude: native `/effort` levels (`low…ultracode`). OpenCode: the current model's variants, applied per-prompt. No env configuration |
+| `/accounts` | Every account the bot works with, on one screen. **Claude accounts** (when you keep several subscriptions signed in): each profile with its email, plan (personal Pro/Max or corporate Team/Enterprise), how many topics use it and its usage windows, ✓ on the active one; tap a profile to switch this topic (a running session is restarted under it, same conversation — at the end of its turn if it is working; on a topic that runs OpenCode the tap switches the topic to Claude on that account, after a confirmation when there is a conversation to hand over); in **General** the pick becomes the default for all topics. The title says where the topic really runs (`Claude «work»`, `OpenCode openai/gpt-5`) and the ✓ sits on that row — on no account while OpenCode runs. Per profile: 🔑 signs it in again, 🗑 removes it (after a confirmation; for `default`, which IS `~/.claude`, «remove» signs it out — see below). The usage lines give each window's percentage USED and when it resets as a time from now (`5h 5% 🔄 in 4h · week 20% 🔄 in 5d 8h · Fable 4% 🔄 in 5d 8h`; «🔄 in 2h», «🔄 in 2d 1h», «🔄 in 30m»; Fable only on a plan that has its own weekly window); when the 5h window's reset is unknown the weekly one is shown in its place, and with no reset at all only the percentage. The hint paragraph under the account list says the percentages are used. «➕ Claude account» asks for a name and runs the sign-in. **OpenCode providers**: the connected ones are listed with how each is signed in (`ChatGPT subscription` with its ~5 h / ~7 d usage windows like an account's, `API key`). In a topic a provider row is `[provider] [🔑] [🔌]`: a tap switches the topic to the provider through its model page (✓ on the model it runs, ⛔ on a limited one; a provider with one model is picked at once), 🔑 connects it again, 🔌 disconnects it (it asks, then removes the stored credentials; a provider OpenCode enables from an environment variable, e.g. `OPENROUTER_API_KEY`, stays active — the reply says so and points at hiding it in `/model`); in **General** a provider row is «🔌 Disconnect <provider>» and 🔑 only; «➕ OpenCode provider» asks for the provider id and continues with the connect flow (OAuth methods when available, otherwise an API key whose message is deleted from Telegram). What happens when an account hits a usage limit is set in `/limits_autoswitch`. Text forms: `/accounts add <name>`, `/accounts use <name>`, `/accounts use <provider>/<model>` (an OpenCode model, in a topic), `/accounts login <name>`, `/accounts remove <name>`, `/accounts autoswitch on\|off`. `/account`, `/connect [provider [key]]` and `/disconnect [provider]` still work as hidden aliases (the menu lists only `/accounts`). See [Several accounts](#several-accounts-accounts) |
+| `/effort` | Reasoning effort. **In a topic:** shows the level its session runs and where the next start's level comes from («medium — as in General» / «high — set for this topic»; a running session keeps the level it started with when General moves on: «xhigh (medium from the next start) — as in General») with a button per level — Claude: the native `/effort` levels (`low…ultracode`); OpenCode: the current model's variants, applied per-prompt; General's `ultracode` is the model's highest variant and `auto` sends no variant — and «As in General (medium)», named with the level the topic will really get (OpenCode: rounded to the model's variants), which drops the topic's own pick (a live session is brought to the default at once). **In General:** the default effort for every topic that has no effort of its own (✓ on the current one; `medium` until you pick), saved to `settings.json` and applied from each topic's next session start or wake-up — running sessions are not restarted. No env configuration — see [Instance settings](SETUP.md#instance-settings-settingsjson) |
 | `/verbosity` | Output-verbosity macro (`minimal\|short\|full`): sets the thinking, tool-results and sub-agent display prefs at once; `/thinking`, `/tool_results`, `/subagent` point-override afterwards. Mixed prefs show as "custom" in the picker. The picker's second row (or `/verbosity stream\|stream_answers\|answers`) sets what the topic SHOWS — "Stream only" (default), "Stream + answers" (the stream plus the agent's pinned answers) or "Answers only" (the pinned answers, no stream; an agent that keeps writing after its final answer is reminded once to send what matters); the answers are written like for a manager or QA — brief and to the point; a switch applies from the next message, and `/status` names the view |
 | `/thinking` | Chain-of-thought display: `full` keeps the reasoning, `short` collapses to "💭 thought for Ns", `minimal` keeps only the live working cue |
 | `/tool_results` | Completed tool-call output: `full` whole body, `short` capped (15 lines / 1200 chars), `minimal` transient 🔧 status only |
@@ -104,19 +104,21 @@ actually start an agent or terminal in the folder.
 | `/rename_session` | Rename the current live session (OpenCode; Claude transcripts have no title) |
 | `/quit`, `/q` | End the session — Claude: graceful double Ctrl+C; OpenCode/terminal: `stopSession`. Releases the persisted session id, so a bot restart won't auto-reattach it (resume later via `/sessions`). A topic whose agent process is gone but whose session is kept (it "sleeps": the next message, file, voice note, `/compact`, `/model` or `/effort` resumes it by itself) is released the same way |
 | `/new`, `/clear_session` | End the current session and start a fresh one (same adapter) |
-| `/status` | This thread's status: agent, bound folder, the Claude account it runs on and the resolved workdir; a live session also shows the model it is actually running, effort, start time, runtime version and context use (anything the backend cannot report renders as unknown). On a Claude topic the account is its profile (name · email as in `/accounts`, marked ⛔ while it is at its limit, with a second row for a switch still pending); an OpenCode topic's model already names its provider |
+| `/status` | This thread's status: agent, bound folder, the Claude account it runs on and the resolved workdir; a live session also shows the model it is actually running, the effort it runs (when the default moved on under it: «xhigh (medium from the next start)»), start time, runtime version and context use (anything the backend cannot report renders as unknown). On a Claude topic the account is its profile (name · email as in `/accounts`, marked ⛔ while it is at its limit, with a second row for a switch still pending); an OpenCode topic's model already names its provider |
 | `/output` | Last 500 lines of agent output (sent as at most 5 chunks; the overflow is reported as omitted) |
 | `/c`, `/y`, `/n` | Ctrl+C / "y" / "n" |
 | `/enter`, `/up`, `/down`, `/tab` | tmux key passthrough |
 | `/esc`, `/escape` | Send a raw Escape — interrupt the current turn / dismiss a selector |
 | `/schedule` | Schedule a prompt in free text — the agent parses the time and owns the job; see [Scheduler](#scheduler-schedule-telegram) |
+| `/stt` | Voice recognition, from any topic (General included); instance-wide, applied to the next voice note — no restart. The main screen holds only what applies to recognition as a whole: the ordered list of **engines** (the first that works answers; when one fails the next takes over) — one full-width button each (`1. GigaAM (local) · running · 10s+25% · ✓` — name, the local engine's short state, timeout `base s + % of the voice`, ✓ usable / ✗ disabled or skipped) — then «➕ Add engine», «🌐 Language» (auto or `ru en uk de fr es`) and «✖️ Close». A tap on an engine opens its **card**: ⬆️ Up / ⬇️ Down, ✅ Use / 🚫 Don't use, ⏱ Timeout (presets), then what the kind adds — 🔑 key for **Groq**, **OpenAI** or a **custom** OpenAI-compatible server (its address, a base like `http://host:8000` is completed; then «does it need a key?»), and 🗑 Remove. A pasted key is deleted from the topic the moment it is accepted, never shown again and kept out of the logs; an address with a login in it is refused. **GigaAM (local)** (Russian only, runs on this machine) is added through «➕ Add engine» like the others: installed, it joins the list at once; not installed, a confirmation (≈ 400 MB on disk; ≈ 0.5 GB RAM while it runs, up to ≈ 0.9 GB on a long voice, nothing while stopped) leads to the install with a live progress message, and the message becomes its card. Its card holds everything local: the status line (ready · running / stopped / paused after failed starts / installing / not installed), «⏱ Exit after idle» (5 / 15 / 30 / 60 min or never), «⚙️ Workers» (1 / 2 / 4 / 8), «🔄 Try again now» (while paused), «Remove from list» (the files stay) and «🗑 Remove model files». Everything lives in one file, `stt.json` — see [Voice input](SETUP.md#voice-input). `/voice` and `/speech` are hidden aliases |
 | `/reminders` | Reminders set with buttons only — the bot posts and pins them itself, with no agent involved; works in any topic, bound or not. See [Reminders](#reminders-reminders-telegram) |
 | `/clear_messages` | Delete bot messages in this topic (up to 48h, Telegram limit) |
 | `/clear` | Forwarded to the agent (Claude wipes context; OpenCode plain text) — not a bot command anymore. Also purges the topic's file-intake dir |
 | `/compact` | Compact the agent's context — a real, confirmed compaction on OpenCode and on the default (stream) Claude backend; the tmux Claude backend has the literal command forwarded (its TUI compacts); terminal: not supported |
 | `/compact_on_idle` | Toggle auto-compaction after ~55 min idle (Enable/Disable picker; `AGENT_IDLE_MINUTES` sets the window). Per topic; run it in **General** to set the default for all topics. On by default. Each idle compaction posts one short notice; the picker's «Show summary» / «Hide summary» row (the `/compact_summary` switch) adds the agent's full summary after it. Fires at most once per active period (until you write again); if a question was pending it is re-asked with tappable buttons after the compaction. On the json-stream backends the idle mark also STOPS the agent process, compaction or not — the topic sleeps and your next message resumes it (`/status` says so) |
 | `/compact_summary` | Toggle posting the agent's full summary after a compaction — `/compact`, the idle compaction and the agent's own `compact_conversation` (Enable/Disable picker). Per topic; run it in **General** to set the default for all topics. Off by default: a compaction ends in a short line. On OpenCode it also hides the summary OpenCode streams itself |
-| `/limits` | Everything about a usage limit on one screen, with a short text: at the top each Claude account's **usage windows** exactly as `/accounts` shows them, under a «Usage (% used)» heading (`default — ⏱ 5h 5% 🔄 in 4h · week 20% 🔄 in 5d 8h · Fable 4% 🔄 in 5d 8h`; a signed-out account is named, one never polled is left out), then what the topic runs on and where its two settings come from. **Fallback models** — an ordered list of Claude accounts (with an optional model) and OpenCode providers with a model, top = preferred, where a topic continues when its agent hits a limit. One full-width button per entry (`1. Claude · work · opus ⛔ 14:00` — limited until, 🔒 not signed in, ❓ no longer offered, 🚫 left out of automatic switching, ✓ where the topic runs); a tap opens that entry in the same message with ⬆️ Up / ⬇️ Down, 🚫 Don't use / ✅ Use (a left-out entry stays usable by hand through `/model` and `/accounts`), 🗑 Remove and ⬅️ Back. Below the list: «➕ Add» (account or provider, then the model), «🔄 Fill from connected» (a draft from what is connected; entries you left out stay left out; asks first when a list exists), «🗑 Clear». The list is ONE instance-wide list and is editable from every topic. **Two settings** decide what a limit does: «🔁 Auto switch» — auto switch to a fallback model (OFF by default: the limit notice carries «🔁 Switch to …» buttons instead) and «⏳ Wait for reset» — wait for the reset and continue (ON by default; while a wait is armed the topic screen also offers «⏭ Skip once»). In General they are the defaults for all topics and each is one button that flips the value. In a regular topic each is one short full-width button showing the effective value (`🔁 Auto switch: ON`; one line of text above the list says where each value comes from — `🔁 as in General · ⏳ set for this topic`); a tap opens the setting in the same message with ON / OFF / «As in General (<the General value>)» — the topic's own choice marked ✓ — and ⬅️ Back, and a choice applies and returns to the screen. Switch ON: the topic moves to the first available entry at once. OFF: buttons on the notice, and if none is pressed the bot waits for the reset (waiting ON); both OFF: it only reports the limit. When every enabled entry, the current one included, is limited, the wait ends at the EARLIEST reset and the topic continues on that entry (the notice names it and the time). Text forms: `/limits rebuild`, `/limits clear`, `/limits switch on\|off\|same`, `/limits wait on\|off\|same`. `/fallback` and `/auto_continue_limits [on\|off]` still work as hidden aliases. See [Usage limits and the fallback models](#usage-limits-and-the-fallback-models-limits) |
+| `/limits` | The **switch board**: every signed-in Claude account and every connected OpenCode provider on one screen. The **message** carries the figures — `Usage (% used)` and a line per account in the same wording `/accounts` uses (`default — ⏱ 5h 14% 🔄 in 3h · week 3% 🔄 in 6d`; `⛔ at its limit until …` while the account is limited; `(stale)` when the last poll could not refresh), a provider signed in through a ChatGPT subscription after them (`openai (ChatGPT) — ⏱ 5h 12% 🔄 in 3h · week 40% 🔄 in 4d`), the two automatic-switching settings' state with a link to `/limits_autoswitch`, and the caption «Choose the active model:». The **buttons** are one full-width name each — `✓ Claude · work`, `Claude · default`, `OpenCode · openai` — with no figure on them (the figures do not fit a phone's button); ✓ marks where the topic runs; a signed-out account is not listed. **A tap switches this topic**: another Claude account (the running session restarts under it, same conversation — at the end of its turn when it is working), an OpenCode provider (opens its model page, 10 models per page with ⛔ on a limited one; a provider with one model switches at once), the ✓ row (the model page of where the topic runs: change the model). Across backends with a conversation to hand over the bot asks first (✅ Continue / ✖️ Cancel); while a usage-limit wait is armed the tap is the limit move — the wait ends and the work continues, no question — and «⏭ Skip once» is offered. An unbound topic is told to bind a folder first. In **General** a Claude row sets the default account for all topics (the caption reads «Choose the default Claude account:»), and an OpenCode row only says that a model is picked inside a topic. The limit notice names this command. The old text forms `/limits rebuild`, `/limits clear`, `/limits switch …`, `/limits wait …` still work (they are `/limits_autoswitch`'s verbs). See [Usage limits and the fallback models](#usage-limits-and-the-fallback-models-limits-and-limits_autoswitch) |
+| `/limits_autoswitch` | The setup of automatic switching on a usage limit, with a short text: a title, what the topic runs on and where its two settings come from. **Fallback models** — an ordered list of Claude accounts (with an optional model) and OpenCode providers with a model, top = preferred, where a topic continues when its agent hits a limit. One full-width button per entry (`✓ 1. Claude · work · opus`, `2. Claude · default ⛔ 14:00`, `3. OpenCode · openai · gpt-5 🚫` — ✓ where the topic runs, ⛔ limited until, 🔒 not signed in, ❓ no longer offered, 🚫 left out of automatic switching); a tap opens that entry in the same message with ⬆️ Up / ⬇️ Down, 🚫 Don't use / ✅ Use (a left-out entry stays usable by hand through `/model` and `/accounts`), 🗑 Remove and ⬅️ Back. Below the list: «➕ Add» (account or provider, then the model; an entry of a backend the list does not use yet — an OpenCode model next to Claude accounts, or the reverse — asks first, because a limit then hands a conversation over in compacted form; including a 🚫 entry that does that asks the same way), «🔄 Fill from connected» (a draft from what is connected; entries you left out stay left out; asks first when a list exists), «🗑 Clear». The list is ONE instance-wide list and is editable from every topic. **Two settings** decide what a limit does: «🔁 Auto switch» — auto switch to a fallback model (OFF by default: the limit notice carries «🔁 Switch to …» buttons instead) and «⏳ Wait for reset» — wait for the reset and continue (ON by default; while a wait is armed the topic screen also offers «⏭ Skip once»). In General they are the defaults for all topics and each is one button that flips the value. In a regular topic each is one short full-width button showing the effective value (`🔁 Auto switch: ON`; one line of text above the list says where each value comes from — `🔁 as in General · ⏳ set for this topic`); a tap opens the setting in the same message with ON / OFF / «As in General (<the General value>)» — the topic's own choice marked ✓ — and ⬅️ Back, and a choice applies and returns to the screen. Switch ON: the topic moves to the first available entry at once. OFF: buttons on the notice, and if none is pressed the bot waits for the reset (waiting ON); both OFF: it only reports the limit. When every enabled entry, the current one included, is limited, the wait ends at the EARLIEST reset and the topic continues on that entry (the notice names it and the time). Text forms: `/limits_autoswitch rebuild`, `/limits_autoswitch clear`, `/limits_autoswitch switch on\|off\|same`, `/limits_autoswitch wait on\|off\|same` (the same verbs work after `/limits`). `/fallback` and `/auto_continue_limits [on\|off]` still work as hidden aliases. See [Usage limits and the fallback models](#usage-limits-and-the-fallback-models-limits-and-limits_autoswitch) |
 | `/bind` | Bare: current binding + folder picker, with «leave current dir» (the old `/unbind`) and «create new folder» buttons |
 | `/mcp` | List MCP servers active for this thread |
 
@@ -150,10 +152,11 @@ In a bound topic you can also type:
 - `claude fix the bug` / `opencode add tests`
 - A plain message after `/claude` is already running → routed as input.
 
-Voice messages are transcribed via Groq Whisper (free) or OpenAI Whisper
-(fallback) and follow the same routing. If the provider times out or fails
-temporarily, the bot says so in the topic and retries automatically (after 5 s,
-then 15 s) — no need to re-record the voice note.
+Voice messages are transcribed by the speech engines you set up with `/stt` (Groq,
+OpenAI, any OpenAI-compatible server, or the local GigaAM engine — see [Voice input](SETUP.md#voice-input)) and follow
+the same routing. The engines form an ordered chain: when one fails, the next one answers within the
+same voice note. The last one retries a temporary failure automatically (after 5 s, then 15 s) and
+says so in the topic — no need to re-record the voice note.
 
 `/terminal` is never started from a natural-language phrase — only the
 explicit command opens a shell.
@@ -219,14 +222,18 @@ so one account's usage limit does not stop every topic.
   profile keeps your current login out of the way), finish the sign-in and paste
   the code back into the topic. The code message is deleted; the bot confirms
   with the account's email and plan.
-- **Switching:** tap a profile in `/accounts` (or `/accounts use <name>`). A
+- **Switching:** tap a profile in `/accounts` or an account on the `/limits`
+  board (or `/accounts use <name>`). A
   running session on the default (stream) backend is restarted under the new
   account with the same conversation — right away when idle, at the end of its
   turn when it is working; a sleeping topic simply resumes under it. The
   tmux-scrape backend is reopened the same way when idle and waits for the next
   start when busy. In the **General** topic the pick is the default for all
   topics; a topic with its own pick keeps it («↩ Follow the default» drops it).
-  A profile that is not signed in cannot be picked.
+  A profile that is not signed in cannot be picked. On a topic that runs OpenCode the
+  pick is a switch to Claude on that account (see *A manual switch between Claude and
+  OpenCode asks first* under the fallback models). While a usage-limit wait is armed a
+  pick is the limit move: the wait ends and the work continues on the account you tapped.
 - **Removing:** «🗑 Remove» deletes the profile's login directory. The profile
   that is currently the instance default cannot be removed (pick another one in
   General first); topics that had picked the removed profile return to the
@@ -250,33 +257,42 @@ so one account's usage limit does not stop every topic.
   percentage is shown. `charness claude-profiles` prints
   the same relative form; its `--json` and the MCP tool keep ISO instants. The bot reads the figures with
   each profile's own login every 10 minutes, when `/accounts` or `/limits` opens and when an
-  agent asks; a json-stream session's own rate-limit events keep them current
+  agent asks (the ChatGPT subscription of an OpenCode provider is read the same way, see below); a json-stream session's own rate-limit events keep them current
   between polls. A token the CLI has not renewed yet shows the last figures as
   `(stale)`; a profile whose session was refused on a window is marked
   `⛔ at its limit until …` and is skipped by the recommendation below.
 - **Another account takes over on a limit.** When a topic's account hits a
-  usage limit the bot looks at the [fallback chain](#usage-limits-and-the-fallback-models-limits);
+  usage limit the bot looks at the [fallback chain](#usage-limits-and-the-fallback-models-limits-and-limits_autoswitch);
   without one it ranks the other signed-in profiles by headroom on the windows
   the topic's model drains (fresh figures, not marked limited). The limit
   notice carries «🔁 Switch to <entry>» buttons, best first: a tap moves the
   topic there (the running session is restarted under the new account with the
   same conversation), drops the wait for the reset and tells the agent to
   continue right away. With **switching** on («🔁 Auto switch to a
-  fallback model» in `/limits`, or `/limits switch on`; in General the default for all
-  topics) the bot does the same by itself and posts one line — «Usage
-  limit on a — this topic switched to b and continues», naming when the
-  exhausted account resets. It is OFF by default: moving work between
-  subscriptions is your call. The exhausted profile is marked limited until its
-  window resets, so it is not picked again before then; the topic is never
-  moved back by itself — switch it back by hand when the window resets. When
-  nothing can take over the bot waits for the reset as before. An agent that is
-  still working switches at the end of its turn (the wait stays armed).
+  fallback model» in `/limits_autoswitch`, or `/limits_autoswitch switch on`; in General the default for all
+  topics) the bot does the same by itself and posts one short line — «Account
+  «a» hit its usage limit — this topic continues on «b». The limit resets
+  <time>. Switch: /limits». The target is named by its account alone
+  and gets its model only when the switch changes it («b» (sonnet)); an
+  OpenCode rung is written without quotes on either side — the target as
+  «OpenCode provider/model», the side that hit its limit as «Model
+  provider/model». It is OFF by default: moving
+  work between subscriptions is your call. The exhausted profile is marked
+  limited until its window resets, so it is not picked again before then. The
+  reset itself does not move the topic back: `/limits`, which the notice names,
+  lists every account and provider with its usage and one tap moves the topic
+  (see below). Only a wait that ends on another entry
+  moves a topic by itself (see below). When nothing can take over the bot waits
+  for the reset as before. A Claude session that works when a limit hits is
+  moved at once (the turn is dead; background tasks it started are stopped and
+  the notice says so); only a tmux Claude session with nothing to resume yet is
+  left to the end of its turn.
 - **Which account for a child process.** An agent that launches a detached
   `claude` (a worker, a reviewer) asks the bot's `telegramBot` MCP tool
   `claude_profiles` — optionally with the model it will run — and gets every
   profile with its windows plus `recommended`: the signed-in, unlimited profile
-  with the most headroom (Fable → Fable's weekly window and the session window;
-  any other model → the shared weekly window and the session window). It then
+  with the most headroom (the session window and the shared weekly window bound
+  every model; Fable additionally drains its own weekly window). It then
   starts the child with `CLAUDE_CONFIG_DIR=<configDir>` (`null` = the default
   profile: set nothing). The same answer from a shell, for a worker without
   MCP: `charness claude-profiles [--best] [--model <name>] [--json]` —
@@ -284,12 +300,39 @@ so one account's usage limit does not stop every topic.
   `CLAUDE_CONFIG_DIR="$(charness claude-profiles --best --model fable)"`
   works as is; it reads the bot's cache off `DATA_DIR/state.json`.
 
-### Usage limits and the fallback models (`/limits`)
+### Usage limits and the fallback models (`/limits` and `/limits_autoswitch`)
 
 When a topic's agent stops on a usage limit — a Claude account window, an
-OpenAI quota through OpenCode, a Google `RESOURCE_EXHAUSTED` — the bot can keep
-the work going somewhere else instead of waiting. `/limits` holds ONE
-instance-wide, ordered list of **fallback models** (where to go), top = preferred:
+OpenAI quota through OpenCode, a Google quota spent for the day or the plan — the
+bot can keep the work going somewhere else instead of waiting (a per-minute
+throttle, or a reset a few minutes away, is simply retried). Two screens split
+the job:
+**`/limits` is the switch board** — every signed-in Claude account and every connected
+OpenCode provider with its usage, one tap to move the topic there by hand — and
+**`/limits_autoswitch` is the setup of the automatic switching**: ONE
+instance-wide, ordered list of **fallback models** (where to go), top = preferred,
+and the two settings (auto switch, wait for the reset):
+
+- **The board.** `/limits` (see the command table) is where the notice sends you
+  («The limit resets <time>. Switch: /limits»): a Claude account row changes the
+  account (model and conversation kept), an OpenCode provider row opens its model page
+  and a pick changes the model (the same session), the ✓ row changes the model of where
+  the topic runs, and across backends with a conversation the bot asks first. Every
+  entry point — a board row, an `/accounts` row, a model page, `/accounts use` — takes the
+  one switch path, so a pick behaves the same wherever it is made. While a limit wait is
+  armed a tap is the limit move: another account, another provider or model, and — on the
+  limited Claude account itself — a model the limit does not cover (a Fable-only weekly limit
+  does not stop `opus` or `sonnet`; the usage windows say what is exhausted) continue the work
+  at once; a pick still inside the limit's scope (Fable again, or any model while the session or
+  the shared weekly window is exhausted — Fable drains both too — or when the windows are unknown)
+  only changes the model and the wait stays. A tap that switched answers with a short «✅ This topic runs on …».
+- **OpenCode usage.** A provider signed in through a **ChatGPT subscription** (the `openai`
+  provider with an `oauth` record in OpenCode's `auth.json`) shows its ~5 h and ~7 d
+  windows in the `/limits` message and in `/accounts`, read the way a Claude account's are: the stored
+  token as it is (never refreshed by the bot; an expired one marks the figures out of date),
+  every 10 minutes and when a screen opens, cached in `state.json`. API-key providers and
+  other subscriptions show only how they are signed in (`/accounts`); a model that hit a limit carries `⛔ <reset>` on its model page.
+  A failed read just leaves the provider without a usage line.
 
 - **Left out of switching.** ✅ / 🚫 on a row includes or excludes that entry from
   automatic switching and from the notice's switch buttons. A connected
@@ -303,7 +346,7 @@ instance-wide, ordered list of **fallback models** (where to go), top = preferre
   an OpenCode provider with a model (`openai/gpt-5`, `google/gemini-2.5-pro`,
   …). Only what is actually connected is offered: the signed-in profiles, and
   the providers the OpenCode server is authenticated for (its live catalog).
-- **Drafting.** «🔄 Fill from connected» (or `/limits rebuild`) writes a draft from what
+- **Drafting.** «🔄 Fill from connected» (or `/limits_autoswitch rebuild`) writes a draft from what
   is signed in: the Claude accounts in their `/accounts` order (keeping the
   topic's model), then the OpenCode models topics picked recently, then every
   other provider's strongest model; an account or provider you had left out of
@@ -339,9 +382,21 @@ instance-wide, ordered list of **fallback models** (where to go), top = preferre
   report in one short message what the task is, what is done and what remains.
   A later `/claude` or `/opencode` returns to the parked conversation; `/new`
   and `/quit` release it as usual.
-- The topic is **never moved back by itself** when the exhausted entry resets
-  — the switch notice names the reset time; switch back by hand (`/accounts`,
-  `/model`, `/claude`, `/opencode`).
+- **A manual switch between Claude and OpenCode asks first.** `/claude` or `/opencode` (also the agent
+  buttons and the natural-language «start …» phrases) on a topic that runs the other backend, and a Claude
+  account tapped in `/accounts` or on the `/limits` board (or `/accounts use <name>`) — and an OpenCode provider's model picked on a topic that runs Claude — move the topic the same
+  way as a limit does — parked conversation of the target resumed, the context bridge as its first prompt (text typed
+  with the command, `/opencode do X`, rides in it). When the topic holds a conversation to hand over (an agent with at
+  least one turn, running or asleep) the bot first asks «🔁 Switch this topic from OpenCode to Claude «work»? The
+  conversation context will be handed over in compacted form.» with ✅ Continue / ✖️ Cancel: Continue switches and
+  turns the question into one line saying so, Cancel changes nothing; either consumes the keyboard, and an old
+  question only says it is out of date. A topic with nothing to hand over (no agent, or one just started and not yet
+  spoken to) switches at once, and a Claude account tapped on a Claude topic applies at once, as before. `/model`
+  lists only the current backend's models, so it never switches backend.
+- The reset of the exhausted entry does **not** move the topic back by itself —
+  the switch notice names the reset time. The one thing that can is the wait: when
+  every enabled entry is limited, the wait is re-aimed at the entry that resets
+  first, and that may be the one the topic left (see above).
 
 ### Scheduler (`/schedule`) (Telegram)
 
@@ -485,9 +540,12 @@ agent even when two clients use the same JSON-RPC request id. It exposes:
 - `send_file_to_user` — lets the agent push files from the bound folder into the
   topic. A single MP4 uses Bot API `sendVideo`; eligible all-video and mixed
   photo/video albums use `sendMediaGroup`, with each MP4 represented by an
-  `InputMediaVideo` entry. `as_file:true` explicitly forces documents. Secure
-  outbound file traversal currently requires Linux; on macOS this tool
-  fails closed until a native descriptor-relative bridge is available. Existing
+  `InputMediaVideo` entry. `as_file:true` explicitly forces documents. A file is
+  opened so that a path swapped after validation cannot reach outside the bound
+  folder: on Linux component by component beneath a pinned folder descriptor
+  (`/proc/self/fd`); on Windows and macOS by its canonical path, held to the
+  validated file's device/inode identity and resolved again inside the folder
+  after the open. Existing
   path, count, caption, and size caps apply; canonical upload basenames have
   control characters and quoted-string metacharacters replaced before they enter multipart headers. Cancelling
   the MCP call removes queued work. While any upload stream is still being
@@ -544,6 +602,21 @@ or adopted ownership is revalidated against the exact hostname and port before
 a signal is sent, without trusting a reused PID or assuming an adopted listener
 owns its process group.
 A source rebuild therefore does not terminate an in-flight OpenCode turn.
+When `opencode serve` itself dies, the bot brings it back the same way a session
+start does — installing the binary first if it is missing, retrying a failed
+start for about a minute — and restores the sessions silently: only a topic whose
+reply was in progress is told it was lost, and a message sent meanwhile is held
+and delivered once the server is back. Only if every attempt fails does a topic
+get one short line saying the next message will try again (the error itself goes
+to the bot log).
+A turn's failure is posted once, although OpenCode reports most failures twice
+(the session error and the failed message); a provider plugin's `[Debug Info]`
+block (opencode-antigravity-auth appends one with your Google project id) is kept
+out of the topic and stays in the bot log. Gemini's "Requests ending with a model
+turn are not supported" — OpenCode v1's agent loop sends a history that ends on
+the model's own turn, fixed upstream only in v2 — gets one short line and the
+bot's "continue" at once, which is a user turn; the same refusal right after it
+ends with the usual give-up line.
 The supervisor reads the same checkout `.env` as the worker before the initial
 start. Hot mode supports Linux and macOS; it refuses to start on Windows because
 nodemon cannot gracefully drain its worker tree there.
@@ -668,7 +741,7 @@ Yes, both a bot restart and an agent-server restart. State is persisted to disk;
 Yes. Each topic picks its backend independently: OpenCode over its native HTTP+SSE server, or Claude Code (tmux or json-stream). One topic is one project with its own isolated session, like terminal tabs, and two topics can point at the same folder for parallel work.
 
 **Can I talk to the agent by voice?**
-Yes. Send a voice message to a topic and it is transcribed with Whisper (via Groq or OpenAI) and forwarded to the agent as a normal prompt, so you can vibe code hands-free from your phone.
+Yes. Send a voice message to a topic and it is transcribed (by Groq, OpenAI or your own Whisper-compatible server) and forwarded to the agent as a normal prompt, so you can vibe code hands-free from your phone.
 
 ### Documentation
 

package/SETUP.md

@@ -172,17 +172,16 @@ $EDITOR ~/.config/charness/.env
 ```
 
 ```dotenv
-# ~/.config/charness/.env — the one place your keys live
+# ~/.config/charness/.env — the bot token and the instance settings
 TELEGRAM_BOT_TOKEN=123456789:ABCdef...
-# GROQ_API_KEY=...     # optional: free voice transcription
 # OWNER_USER_ID=...    # set to drive the bot from its DM (step 2)
 ```
 
-All keys the bot needs live in this one file — the bot token and the optional
-`GROQ_API_KEY` for voice sit side by side, no separate stores. (Agent
-provider auth is the exception, and lives inside the agents themselves:
-`claude login` for Claude, `/connect` or OpenCode's own config for OpenCode —
-see [Environment Variables](#environment-variables).) The wrapper loads env
+The bot token lives in this file; the voice-recognition keys live next to it, in
+[`stt.json`](#voice-input). (Agent provider auth is the exception, and lives
+inside the agents themselves: `claude login` for Claude, `/connect` or
+OpenCode's own config for OpenCode — see
+[Environment Variables](#environment-variables).) The wrapper loads env
 from two locations, in order — a global base and an optional per-project
 override:
 
@@ -277,6 +276,107 @@ Then: `/quit` ends the session; bare `/bind` inspects/reconfigures the binding;
 > uses, so a thread started in Telegram can be picked up with `claude --resume`
 > and vice versa.
 
+### Voice input
+
+Open **`/stt`** in any topic (General included) to set voice recognition up with buttons: add Groq, OpenAI or your own
+OpenAI-compatible server (the key is pasted into the chat and deleted at once), reorder or switch off engines, set each
+engine's timeout and the language, and enable the [local engine](#local-speech-recognition-gigaam). Every tap is saved to
+the file below and applies to the next voice note. The rest of this section is for hand editing.
+
+Voice notes are transcribed by an **ordered chain of speech engines**: the first available one is tried,
+and when it fails (refused connection, timeout, an error answer) the next one answers the same voice note
+at once. Only the last engine retries a temporary failure (after 5 s, then 15 s). An empty transcript is
+final — silence is never "fixed" by asking another engine.
+
+Everything lives in one file, **`stt.json`**, in the same directory as your real `.env`
+(`~/.config/charness/stt.json`; for an isolated instance, beside its `ENV_FILE`). If that `.env` is a symlink — the
+keys kept on an encrypted volume, say — `stt.json` goes beside the symlink's **target**, so the API keys stay where
+the rest of your secrets are and never land in the directory that only holds the link. **That directory must be
+writable and survive a restart** — under Docker, mount the config directory, not only the env file
+([Run with Docker](#run-with-docker)); when the file cannot be written, `/stt` says so and names the path, and the boot
+log says it once (`[STT] … cannot be written`). It holds the settings and the API keys, is written with mode
+`0600`, and is re-read when it changes — an edit applies to the next voice note, no restart. If the file is
+invalid, the bot keeps the last good settings, logs a `[STT]` line naming the field (never a value), and
+refuses voice with a notice when nothing valid was ever loaded. A voice note that no engine can take gets a notice
+that names the cause: nothing set up (or all switched off), the local engine still installing, or engines listed but not
+usable right now.
+
+```json
+{
+  "engines": [
+    { "id": "q1", "kind": "groq", "apiKey": "gsk_..." },
+    { "id": "o1", "kind": "openai", "apiKey": "sk-...", "timeout": { "baseSeconds": 10, "percentOfDuration": 25 } },
+    { "id": "u1", "kind": "url", "url": "http://127.0.0.1:8000/v1/audio/transcriptions", "model": "whisper-1" }
+  ],
+  "language": "ru"
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `engines` | Ordered, at most 6. `kind`: `groq`, `openai`, `url` (any OpenAI-compatible `/audio/transcriptions` endpoint — give the full URL; `apiKey` is optional there) or `gigaam` (the local engine). `id` is 1–8 lowercase letters or digits, unique. `isDisabled: true` keeps an engine listed but unused |
+| `timeout` | Per engine: `baseSeconds` + `percentOfDuration` % of the voice's length (default 10 s + 25 %), so a 30 s voice gets 17.5 s and a 5 min voice 85 s |
+| `language` | Two-letter code (`ru`, `en`, …) sent to the engines as a hint; leave it out to let the engine detect the language |
+| `gigaam` | `idleMinutes` (default 15, `0` = never) and `workers` (1, 2, 4 or 8; default 4) of the local engine |
+
+An engine without what it needs (no key, no URL) is skipped and logged once. With no usable engine, a voice
+note is answered with a pointer to this setup.
+
+**Coming from `GROQ_API_KEY` / `OPENAI_API_KEY` in `.env`?** On the first start without a `stt.json`, the bot
+writes one from those keys (Groq first, then OpenAI) and logs
+`[deprecated] GROQ_API_KEY/OPENAI_API_KEY in .env is deprecated, voice settings now live in stt.json`. From then
+on the env keys are ignored — edit `stt.json` instead.
+
+#### Local speech recognition (GigaAM)
+
+Besides the hosted engines, the bot can recognise Russian voice notes **on your own machine** with GigaAM v3 (an
+`onnx-asr` model, int8). It is a `gigaam` engine in `stt.json`, added from `/stt` («➕ Add engine → GigaAM (local)»; when the model is not installed yet, with a confirmation and a live progress message) or
+by adding `{ "id": "g", "kind": "gigaam" }` to `stt.json` by hand — in that case the bot installs it by itself at the
+next start and shows the progress in General (or in its log).
+
+- **Needs** `uv` (on `PATH` or in `~/.local/bin`), or `python3` ≥ 3.10 with the venv module (`apt install python3-venv`
+  on Debian/Ubuntu). The install builds a private venv — your Python is left alone.
+- **Disk:** about 400 MB under `<DATA_DIR>/stt` (the model is 216 MB; the rest is the Python packages and their cache).
+- **RAM:** nothing while it is not running. The recogniser process starts with the first voice note that needs it (about
+  +2–3 s once), uses about 0.5 GB for short voices and up to about 0.9 GB while a 5-minute voice is recognised with the
+  default 4 workers, and exits by itself after 15 idle minutes (`gigaam.idleMinutes`, `0` = never). Idle time, workers,
+  «Try again now» and removing the model files are on the engine's card in `/stt`, not on the main screen.
+- **Speed** (4 cores, loaded): a short voice in 1–2 s, a 5-minute voice in about 20 s — long voices are cut at pauses and
+  recognised in parallel. A hot reload of the bot keeps a running recogniser; stopping or killing the bot takes it down.
+- **Russian only.** English words come out in Cyrillic or garbled; with a `language` other than `ru` set, the engine is
+  skipped and the next one in the chain answers.
+- It listens on `127.0.0.1` only, on a port the OS picks, and answers only a per-start secret token.
+- **Docker is not supported yet** (the image has no `python3-venv`).
+
+### Instance settings (`settings.json`)
+
+Settings that belong to the whole instance, not to a topic, live in one file, **`settings.json`**, in the same
+directory as your real `.env` and `stt.json` (`~/.config/charness/settings.json`; for an isolated instance, beside its
+`ENV_FILE`; a symlinked `.env` is resolved exactly as for `stt.json`). The directory must be writable and survive
+restarts — under Docker the mounted config directory covers it ([Run with Docker](#run-with-docker)); when it cannot
+be written, the tap that needed it says so and names the path. The file is optional and is re-read when it changes:
+a hand edit applies to the next session start, no restart.
+
+```json
+{ "defaultEffort": "medium" }
+```
+
+| Field | Meaning |
+|---|---|
+| `defaultEffort` | The reasoning effort of every topic that has no `/effort` pick of its own: `low`, `medium`, `high`, `xhigh`, `max`, `auto` or `ultracode`. Set it from **`/effort` in the General topic** (a tap writes the file), or by hand. Leave it out and the built-in default, `medium`, applies |
+
+What a new Claude session starts with, first that exists: the topic's own `/effort` pick, the platform's default
+(a Jira conversation: `effort` in `jira.json`, `high` when absent — Jira never reads `defaultEffort`), `defaultEffort`,
+then `medium`. A change applies from each topic's next session start
+or wake-up — running sessions are not restarted, and `/status`, the pinned banner and `/effort` show the level a running
+session really uses, with the next start's beside it («xhigh (medium from the next start)»). OpenCode takes the same
+level and runs the nearest variant its model offers (`ultracode` is the model's highest variant, `auto` sends no variant). In a topic, `/effort` shows the level and whether it is the topic's own or «as in General», and «As in
+General» drops the topic's pick (a live session is brought to the default at once).
+
+The file is checked strictly: an unknown level or a mistyped key is logged once as `[Settings] settings.json
+defaultEffort: …` (naming the field, never echoing a value) and the built-in defaults apply until it is fixed — a
+stale copy of an earlier valid file is not used. A `/effort` tap in General over a broken file replaces it.
+
 ### Required files structure
 
 Launch `charness` from the parent folder that holds your project repos —
@@ -341,7 +441,6 @@ talk to the bot there.
 | `ALLOWED_GROUP_ID` | (auto-pair) | Numeric forum supergroup id (`-100…`). Leave empty to auto-pair with the first forum group a group **admin/creator** contacts the bot from (id is saved to `state.json`; re-point with `/pair`). A **name** is not accepted. A numeric value disables auto-pairing |
 | `CHAT_MODE` | `both` | Which surface(s) this instance serves: `group`, `dm`, or `both` — see [Two surfaces](README.md#two-surfaces-group-topics-bot-dm-or-both) |
 | `OWNER_USER_ID` | — | **Optional.** Numeric Telegram user id of the owner — leave it unset to run group-only (the DM surface stays inert; a group works fully without it). Set it only to enable the owner-DM surface; **required** solely for `CHAT_MODE=dm` |
-| `GROQ_API_KEY` | — | Recommended for voice transcription. Without it, voice messages are not transcribed unless you intentionally configure the OpenAI fallback |
 
 **Localized in 12 languages** — the bot UI (commands, buttons, notices) speaks
 中文, English, Français, ქართული, Deutsch, हिन्दी, 日本語, Português, Русский,
@@ -360,7 +459,6 @@ disappears and a short confirmation stays in the chosen language;
 
 | Variable | Default | Set only when |
 |---|---|---|
-| `OPENAI_API_KEY` | — | You intentionally use OpenAI Whisper as the voice fallback instead of Groq |
 | `SHELL` | `/bin/bash` | You want `/terminal` to open a different shell than your login shell (host env var, not set by the bot) |
 
 ## Jira setup
@@ -474,7 +572,8 @@ lends the container the folders it mounts, so the bot and its agents see nothing
 
 ```
 host                                        container charness-<instance>
-your instance env file (tokens)   ── ro ──▶  the bot (hot mode) + a restart loop
+your config directory             ──────▶    the bot (hot mode) + a restart loop;
+  (instance.env and stt.json)                the env file is read, stt.json is written
 DATA_DIR, WORK_ROOT               ──────▶    tmux, the agents, OpenCode, the bot MCP
 a clone of this repository        ──────▶    /opt/charness
 the agents' home folder           ──────▶    /home/charness: their Claude / OpenCode
@@ -493,10 +592,12 @@ the agents' home folder           ──────▶    /home/charness: their
    names (build from the checkout's root, which is how the build reads it; rebuild after a yarn bump so no
    container has to download it). On first start the container installs the checkout's dependencies for the
    image and builds it; the bot installs Claude Code and OpenCode into the agents' home.
-2. **Instance env file**, as for a host install (`TELEGRAM_BOT_TOKEN`, `DATA_DIR`, `WORK_ROOT`, …). It stays on
-   the host and is mounted read-only. Every host path it names (`DATA_DIR`, `WORK_ROOT`, `TMUX_TMPDIR`, …) is
-   mounted at the SAME path, so `state.json`, sessions and file paths stay valid inside and an instance can move
-   between host and container unchanged.
+2. **Instance config directory**, with the env file as for a host install inside it (`TELEGRAM_BOT_TOKEN`,
+   `DATA_DIR`, `WORK_ROOT`, …): `/srv/charness/config/instance.env`. It stays on the host and the **directory** is
+   mounted writable, not just the file: the voice settings (`stt.json`, with the speech-engine API keys) and the instance settings (`settings.json`) are saved
+   beside the env file, and a container's own disk is gone when the container is re-created. Every host path the
+   env file names (`DATA_DIR`, `WORK_ROOT`, `TMUX_TMPDIR`, …) is mounted at the SAME path, so `state.json`,
+   sessions and file paths stay valid inside and an instance can move between host and container unchanged.
 3. **Run** (or use `examples/docker-compose.yml`):
 
    ```bash
@@ -506,8 +607,8 @@ the agents' home folder           ──────▶    /home/charness: their
      -v /srv/charness/home:/home/charness \
      -v /srv/charness/data:/srv/charness/data \
      -v /srv/projects:/srv/projects \
-     -v /srv/charness/instance.env:/srv/charness/instance.env:ro \
-     -e ENV_FILE=/srv/charness/instance.env \
+     -v /srv/charness/config:/srv/charness/config \
+     -e ENV_FILE=/srv/charness/config/instance.env \
      charness
    ```
 
@@ -531,6 +632,10 @@ Running it:
 - **A container restart is a reboot**: every agent process ends; each conversation resumes with its next message.
 - **Rootless Docker** (recommended): the container's root is your user, so everything written on the mounts is
   yours. **Rootful Docker**: add `--user "$(id -u):$(id -g)"` and give that user the agents' home.
+- **Upgrading a container made with the single-file mount** (`INSTANCE_ENV_FILE`, the env file mounted `:ro`): move the
+  env file into a directory of its own, mount the directory as in step 3 and set `ENV_FILE` to the file inside it. Until
+  then `stt.json` sits on the container's own disk and is lost when the container is re-created; the bot says so at boot
+  (`[STT] … is on this container's own disk`).
 - **Moving a host instance in**: stop it first (the lock refuses a lock written on another host), mount its
   folders at their paths, and copy its conversations' folders from `~/.claude/projects/` into the agents' home
   `.claude/projects/` — without them each conversation starts a fresh session on its next message.

package/dist/adapters/adapterEventRouting.d.ts

@@ -9,7 +9,7 @@ import type { SessionKey } from '../sessionKey';
  * usage-limit handling, and the teardown of request-side state.
  */
 /** Every event an agent adapter emits (`createAdapter.ts` wires each). */
-export declare const adapterEventNames: readonly ["output", "status", "question", "thinking", "toolResult", "subagentStatus", "apiError", "noResponse", "questionGone", "closed", "started", "stopped", "suspended", "turnEnded", "contextCompacted", "error"];
+export declare const adapterEventNames: readonly ["output", "status", "question", "thinking", "toolResult", "subagentStatus", "apiError", "noResponse", "questionGone", "closed", "started", "stopped", "suspended", "turnEnded", "contextCompacted", "conversationLost", "error"];
 export type AdapterEventName = (typeof adapterEventNames)[number];
 /**
  * @name ForeignKeyEventRoute
@@ -35,6 +35,7 @@ export declare const foreignKeyEventRoutes: {
     readonly suspended: "none";
     readonly turnEnded: "all";
     readonly contextCompacted: "all";
+    readonly conversationLost: "requestSide";
     readonly started: "none";
     readonly error: "requestSide";
 };

package/dist/adapters/adapterEventRouting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapterEventRouting.d.ts","sourceRoot":"","sources":["../../src/adapters/adapterEventRouting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD;;;;;;;;GAQG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,wNAiBpB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,aAAa,GAAG,KAAK,CAAC;AAElE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;CAyB2C,CAAC;AAE9E,8EAA8E;AAC9E,KAAK,oBAAoB,GAAG;KACzB,CAAC,IAAI,gBAAgB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,GAAG,CAAC,GAAG,KAAK;CAC7F,CAAC,gBAAgB,CAAC,CAAC;AAEpB;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,EAC7D,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,CAAC,EACZ,KAAK,EAAE,MAAM,IAAI,EAGjB,GAAG,aAAa,EAAE,CAAC,SAAS,oBAAoB,GAAG,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,GAClF,IAAI,CAIN"}
+{"version":3,"file":"adapterEventRouting.d.ts","sourceRoot":"","sources":["../../src/adapters/adapterEventRouting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD;;;;;;;;GAQG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,4OAkBpB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,aAAa,GAAG,KAAK,CAAC;AAElE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;CA2B2C,CAAC;AAE9E,8EAA8E;AAC9E,KAAK,oBAAoB,GAAG;KACzB,CAAC,IAAI,gBAAgB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,GAAG,CAAC,GAAG,KAAK;CAC7F,CAAC,gBAAgB,CAAC,CAAC;AAEpB;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,EAC7D,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,CAAC,EACZ,KAAK,EAAE,MAAM,IAAI,EAGjB,GAAG,aAAa,EAAE,CAAC,SAAS,oBAAoB,GAAG,CAAC,aAAa,EAAE,MAAM,IAAI,CAAC,GAAG,EAAE,GAClF,IAAI,CAIN"}