charness 0.0.0-stage → 3.0.0

package/dist/utils/wedgeRecovery.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @description Pure decision for recovering a WEDGED OpenCode session (one that
+ * accepted a prompt but ran no turn — see `openCodeTurnActivity.ts`).
+ *
+ * Three escalating tiers, one attempt each per prompt episode, so the last
+ * dialog is preserved when at all possible and a persistently-wedging session
+ * still cannot loop forever:
+ *
+ *   tier 0 → `resend`  — re-send the prompt to the SAME session (a transient
+ *                        stall recovers here; dialog fully intact, zero cost).
+ *   tier 1 → `fork`    — FORK the session into a fresh one that carries the full
+ *                        conversation, then replay (recovers an instance-level
+ *                        wedge while keeping the dialog). Falls back to `restart`
+ *                        when the adapter can't fork.
+ *   tier 2 → `restart` — blank fresh session + replay (the conversation itself is
+ *                        the poison, e.g. a bloated session — dialog is dropped,
+ *                        but the trigger still runs; verified live on the my-news
+ *                        digest, which is stateless so this is safe).
+ *   else   → `giveUp`  — surface the actionable notice instead of looping.
+ *
+ * `tier` = how many recovery attempts were ALREADY made this episode; it resets
+ * to 0 when a genuine new prompt is forwarded. With no cached prompt to replay
+ * there is nothing to recover → give up.
+ */
+export type WedgeRecoveryAction = 'resend' | 'fork' | 'restart' | 'giveUp';
+export interface WedgeRecoveryState {
+    /** Recovery attempts already made this prompt episode (0, 1, 2, …). */
+    tier: number;
+    /** A raw prompt is cached and can be replayed. */
+    hasReplayPrompt: boolean;
+    /** The adapter can fork its session (carries the dialog); else tier 1 restarts. */
+    canFork: boolean;
+}
+export declare function decideWedgeRecovery(state: WedgeRecoveryState): WedgeRecoveryAction;
+/**
+ * @name ForwardedPromptKind
+ * @description What a forward into the agent is, as far as wedge recovery cares.
+ */
+export interface ForwardedPromptKind {
+    /** A slash command forwarded to the agent — a control token, not worth replaying. */
+    isSlashCommand: boolean;
+    /** The recovery's own replay of the cached prompt. */
+    isRecoveryReplay: boolean;
+    /**
+     * A request wake-up reminder: the open request's original prompt (it carries
+     * the request header) stays the one to replay, and a recovery already under
+     * way for it keeps its tier — else a wedged reminder restarts the escalation.
+     */
+    isRequestReminder: boolean;
+}
+/**
+ * @description Whether a forward becomes the prompt a wedged session replays —
+ * caching it and opening a fresh recovery episode (tier reset). Only a genuine
+ * new prompt does.
+ */
+export declare function checkIsReplayablePrompt(kind: ForwardedPromptKind): boolean;
+//# sourceMappingURL=wedgeRecovery.d.ts.map

package/dist/utils/wedgeRecovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wedgeRecovery.d.ts","sourceRoot":"","sources":["../../src/utils/wedgeRecovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,eAAe,EAAE,OAAO,CAAC;IACzB,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB,CAMlF;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,qFAAqF;IACrF,cAAc,EAAE,OAAO,CAAC;IACxB,sDAAsD;IACtD,gBAAgB,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAE1E"}

package/dist/utils/wedgeRecovery.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideWedgeRecovery = decideWedgeRecovery;
+exports.checkIsReplayablePrompt = checkIsReplayablePrompt;
+function decideWedgeRecovery(state) {
+    if (!state.hasReplayPrompt)
+        return 'giveUp';
+    if (state.tier === 0)
+        return 'resend';
+    if (state.tier === 1)
+        return state.canFork ? 'fork' : 'restart';
+    if (state.tier === 2)
+        return 'restart';
+    return 'giveUp';
+}
+/**
+ * @description Whether a forward becomes the prompt a wedged session replays —
+ * caching it and opening a fresh recovery episode (tier reset). Only a genuine
+ * new prompt does.
+ */
+function checkIsReplayablePrompt(kind) {
+    return !kind.isSlashCommand && !kind.isRecoveryReplay && !kind.isRequestReminder;
+}
+//# sourceMappingURL=wedgeRecovery.js.map

package/dist/utils/wedgeRecovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wedgeRecovery.js","sourceRoot":"","sources":["../../src/utils/wedgeRecovery.ts"],"names":[],"mappings":";;AAmCA,kDAMC;AAwBD,0DAEC;AAhCD,SAAgB,mBAAmB,CAAC,KAAyB;IAC3D,IAAI,CAAC,KAAK,CAAC,eAAe;QAAE,OAAO,QAAQ,CAAC;IAC5C,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACtC,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACvC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAmBD;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,IAAyB;IAC/D,OAAO,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,gBAAgB,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC;AACnF,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,30 @@
+/** Return the signal's Error reason, including a stable fallback for non-Error reasons. */
+export declare function getAbortError(signal: AbortSignal): Error;
+/**
+ * @description Whether a caught error is the abort raised for a cancelled
+ * operation. Matches on the error IDENTITY (`name`), never on its message text.
+ *
+ * Covers every abort this codebase can raise: a bare `controller.abort()` puts a
+ * DOMException named `AbortError` on `signal.reason`, and an abort carrying a
+ * custom reason (the MCP cancellation notification passes a string) is surfaced
+ * by {@link getAbortError} as a fresh `Error` with the same name.
+ */
+export declare function checkIsAbortError(error: unknown): boolean;
+/** Sleep for the requested duration, rejecting promptly when the caller aborts. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * @description Strip the `@botusername` Telegram appends to a slash command in
+ * a group/supergroup.
+ *
+ * In groups, the Telegram client turns `/context` into
+ * `/context@my_bot` (always, when the command is in the bot's command menu;
+ * also whenever multiple bots are present). We forward un-owned slash commands
+ * verbatim to the agent's CLI, which does NOT recognise the `@my_bot` suffix —
+ * so `/context` silently no-ops. Strip the mention from the FIRST token only,
+ * preserving any arguments: `/context@my_bot keep notes` → `/context keep notes`.
+ *
+ * Only touches a leading `/command@mention`; ordinary text and mid-text `@`s
+ * (e.g. `email me @ foo`) are left untouched. Pure + exported for unit tests.
+ */
+export declare function stripCommandBotMention(text: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK,CAKxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED,mFAAmF;AACnF,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAarE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/utils.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAbortError = getAbortError;
+exports.checkIsAbortError = checkIsAbortError;
+exports.sleep = sleep;
+exports.stripCommandBotMention = stripCommandBotMention;
+/** Return the signal's Error reason, including a stable fallback for non-Error reasons. */
+function getAbortError(signal) {
+    if (signal.reason instanceof Error)
+        return signal.reason;
+    const error = new Error('The operation was aborted');
+    error.name = 'AbortError';
+    return error;
+}
+/**
+ * @description Whether a caught error is the abort raised for a cancelled
+ * operation. Matches on the error IDENTITY (`name`), never on its message text.
+ *
+ * Covers every abort this codebase can raise: a bare `controller.abort()` puts a
+ * DOMException named `AbortError` on `signal.reason`, and an abort carrying a
+ * custom reason (the MCP cancellation notification passes a string) is surfaced
+ * by {@link getAbortError} as a fresh `Error` with the same name.
+ */
+function checkIsAbortError(error) {
+    return error instanceof Error && error.name === 'AbortError';
+}
+/** Sleep for the requested duration, rejecting promptly when the caller aborts. */
+function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(getAbortError(signal));
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', handleAbort);
+            resolve();
+        }, ms);
+        const handleAbort = () => {
+            clearTimeout(timer);
+            if (signal)
+                reject(getAbortError(signal));
+        };
+        signal?.addEventListener('abort', handleAbort, { once: true });
+    });
+}
+/**
+ * @description Strip the `@botusername` Telegram appends to a slash command in
+ * a group/supergroup.
+ *
+ * In groups, the Telegram client turns `/context` into
+ * `/context@my_bot` (always, when the command is in the bot's command menu;
+ * also whenever multiple bots are present). We forward un-owned slash commands
+ * verbatim to the agent's CLI, which does NOT recognise the `@my_bot` suffix —
+ * so `/context` silently no-ops. Strip the mention from the FIRST token only,
+ * preserving any arguments: `/context@my_bot keep notes` → `/context keep notes`.
+ *
+ * Only touches a leading `/command@mention`; ordinary text and mid-text `@`s
+ * (e.g. `email me @ foo`) are left untouched. Pure + exported for unit tests.
+ */
+function stripCommandBotMention(text) {
+    return text.replace(/^(\/[A-Za-z0-9_]+)@[A-Za-z0-9_]+/, '$1');
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":";;AACA,sCAKC;AAWD,8CAEC;AAGD,sBAaC;AAgBD,wDAEC;AArDD,2FAA2F;AAC3F,SAAgB,aAAa,CAAC,MAAmB;IAC/C,IAAI,MAAM,CAAC,MAAM,YAAY,KAAK;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IACzD,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IACrD,KAAK,CAAC,IAAI,GAAG,YAAY,CAAC;IAC1B,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAAC,KAAc;IAC9C,OAAO,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC;AAC/D,CAAC;AAED,mFAAmF;AACnF,SAAgB,KAAK,CAAC,EAAU,EAAE,MAAoB;IACpD,IAAI,MAAM,EAAE,OAAO;QAAE,OAAO,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAClE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;YAClD,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,MAAM,WAAW,GAAG,GAAG,EAAE;YACvB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,MAAM;gBAAE,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5C,CAAC,CAAC;QACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,sBAAsB,CAAC,IAAY;IACjD,OAAO,IAAI,CAAC,OAAO,CAAC,kCAAkC,EAAE,IAAI,CAAC,CAAC;AAChE,CAAC"}

package/dist/validation.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @description Path-traversal-safe validation of user-supplied `subdir`
+ * arguments to `/bind` and friends. Extracted from `src/bot.ts` so that
+ * the security-critical logic can be unit-tested without spinning up the
+ * whole Telegraf surface (plan §11 Этап 7, R3).
+ *
+ * The exported `validateSubdir(workRoot, rawSubdir)` returns the *relative*
+ * form of the resolved path (so on-disk records survive a `WORK_ROOT`
+ * rename) and throws a `BindError` whose `.code` lets callers map to a
+ * localised reply string.
+ *
+ * Defence-in-depth covers four classes of attack:
+ *  - **Path traversal** — strict equality OR prefix-with-separator check
+ *    after `realpathSync`. Without the trailing `path.sep`, an attacker
+ *    pointing `WORK_ROOT=/work_root` could bind `../work_root_evil` and
+ *    `startsWith` would happily accept it.
+ *  - **Symlink-out** — `realpathSync` on both the root and the candidate
+ *    resolves every symlink before the prefix check, so a symlink inside
+ *    `WORK_ROOT` pointing at `/etc` is rejected.
+ *  - **Control chars / NUL** — many filesystems happily store these; tmux
+ *    and shell-quoting downstream do not. Reject up front.
+ *  - **Unicode NFC drift** — macOS Terminal sends NFD by default while
+ *    the on-disk entry is usually NFC. Normalise the input to NFC before
+ *    `path.resolve` so the realpath lookup actually finds it.
+ *
+ * Plan §13.7 / D35 / R3.
+ */
+import { type PaginatedSlice } from './utils/paginateList';
+/**
+ * @description Error class with a stable `code` field so the bot can map
+ * each failure mode to a localised reply (`i18n.ts → bind.*`) without
+ * pattern-matching error messages.
+ */
+export declare class BindError extends Error {
+    readonly code: BindErrorCode;
+    constructor(code: BindErrorCode, message: string);
+}
+export type BindErrorCode = 'BIND_INVALID_CHARS' | 'BIND_NOT_FOUND' | 'BIND_OUTSIDE_ROOT' | 'BIND_NOT_DIRECTORY';
+/**
+ * @description Resolve `rawSubdir` against `workRoot` and confirm it
+ * actually lives inside it. Returns the *relative* form (e.g. `"overview"`)
+ * so persisted bindings survive a `WORK_ROOT` path change such as a host
+ * mount rename. Throws `BindError` on every failure mode the caller needs
+ * to distinguish.
+ */
+export declare function validateSubdir(workRoot: string, rawSubdir: string): string;
+export type BoundWorkDirDecision = {
+    kind: 'proceed';
+    subdir: string;
+    workDir: string;
+} | {
+    kind: 'refuse';
+} | {
+    kind: 'invalid';
+    error: BindError;
+};
+/**
+ * @description Resolve a persisted binding back to a real working directory.
+ * A binding row in state.json is not enough: the folder may have been deleted
+ * or replaced after `/bind`. Agent startup/list/resume must fail before any
+ * adapter side effects in that case.
+ */
+export declare function resolveBoundWorkDir(workRoot: string, binding: {
+    subdir: string;
+} | null): BoundWorkDirDecision;
+/**
+ * @description Normalise a name (topic title or subdir) for fuzzy auto-bind
+ * matching.
+ *
+ * Folds three predictable drifts between Telegram topic titles and on-disk
+ * folder names:
+ *   - case: `Overview` ↔ `overview`
+ *   - separator: `my-api` ↔ `my_api` ↔ `my api` ↔ `my.api`
+ *   - edge whitespace: `  overview  ` ↔ `overview`
+ *
+ * NFC normalisation runs first so macOS-flavoured NFD doesn't slip past
+ * the separator collapse.
+ *
+ * Anything more aggressive (typo tolerance, partial matches) is
+ * intentionally out of scope — auto-bind has to stay predictable; if it
+ * starts guessing the user loses trust in the rule.
+ *
+ * Plan §11 Этап 7 polish (smart auto-bind fuzzy, §20.10).
+ */
+export declare function normaliseTopicName(s: string): string;
+/**
+ * @description Find the on-disk subdir whose normalised name matches the
+ * normalised topic title. Returns `null` if no match (auto-bind falls
+ * through to the picker UX).
+ *
+ * Caller is expected to have already filtered `subdirs` to the entries
+ * surfaced in the UI — `listAvailableSubdirs` does that.
+ */
+export declare function findAutobindSubdir(topicName: string, subdirs: readonly string[]): string | null;
+export type BindPage = PaginatedSlice<string>;
+/**
+ * @description Pure pagination math for the `/bind` keyboard. Extracted
+ * here so the slice / clamp logic can be unit-tested without booting
+ * Telegraf (which is what `buildBindKeyboard` in `bot.ts` wraps it with).
+ *
+ * Plan §11 Этап 7 polish — pagination kicks in once `listAvailableSubdirs`
+ * surfaces more than `pageSize` folders.
+ *
+ * `pageSize` must be positive; the bot uses `BIND_PAGE_SIZE = 20`. Out-of-
+ * range `page` values are clamped silently — a stale callback after the
+ * disk state shrank just lands on the last available page.
+ *
+ * Thin wrapper over the shared {@link paginateList}: the `/model` picker needs
+ * the same math, so the rules live there and this keeps the `/bind`-flavoured
+ * name its call sites already use.
+ */
+export declare function paginateBindList(subdirs: readonly string[], page: number, pageSize: number): BindPage;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAKH,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEzE;;;;GAIG;AACH,qBAAa,SAAU,SAAQ,KAAK;aACN,IAAI,EAAE,aAAa;gBAAnB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM;CAIjE;AAED,MAAM,MAAM,aAAa,GACrB,oBAAoB,GACpB,gBAAgB,GAChB,mBAAmB,GACnB,oBAAoB,CAAC;AAEzB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CA0D1E;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GACjC,oBAAoB,CAStB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,GAAG,IAAI,CAOf;AAED,MAAM,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,QAAQ,CAEV"}

package/dist/validation.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * @description Path-traversal-safe validation of user-supplied `subdir`
+ * arguments to `/bind` and friends. Extracted from `src/bot.ts` so that
+ * the security-critical logic can be unit-tested without spinning up the
+ * whole Telegraf surface (plan §11 Этап 7, R3).
+ *
+ * The exported `validateSubdir(workRoot, rawSubdir)` returns the *relative*
+ * form of the resolved path (so on-disk records survive a `WORK_ROOT`
+ * rename) and throws a `BindError` whose `.code` lets callers map to a
+ * localised reply string.
+ *
+ * Defence-in-depth covers four classes of attack:
+ *  - **Path traversal** — strict equality OR prefix-with-separator check
+ *    after `realpathSync`. Without the trailing `path.sep`, an attacker
+ *    pointing `WORK_ROOT=/work_root` could bind `../work_root_evil` and
+ *    `startsWith` would happily accept it.
+ *  - **Symlink-out** — `realpathSync` on both the root and the candidate
+ *    resolves every symlink before the prefix check, so a symlink inside
+ *    `WORK_ROOT` pointing at `/etc` is rejected.
+ *  - **Control chars / NUL** — many filesystems happily store these; tmux
+ *    and shell-quoting downstream do not. Reject up front.
+ *  - **Unicode NFC drift** — macOS Terminal sends NFD by default while
+ *    the on-disk entry is usually NFC. Normalise the input to NFC before
+ *    `path.resolve` so the realpath lookup actually finds it.
+ *
+ * Plan §13.7 / D35 / R3.
+ */
+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.BindError = void 0;
+exports.validateSubdir = validateSubdir;
+exports.resolveBoundWorkDir = resolveBoundWorkDir;
+exports.normaliseTopicName = normaliseTopicName;
+exports.findAutobindSubdir = findAutobindSubdir;
+exports.paginateBindList = paginateBindList;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const canonicalPathContainment_1 = require("./utils/canonicalPathContainment");
+const paginateList_1 = require("./utils/paginateList");
+/**
+ * @description Error class with a stable `code` field so the bot can map
+ * each failure mode to a localised reply (`i18n.ts → bind.*`) without
+ * pattern-matching error messages.
+ */
+class BindError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BindError';
+    }
+}
+exports.BindError = BindError;
+/**
+ * @description Resolve `rawSubdir` against `workRoot` and confirm it
+ * actually lives inside it. Returns the *relative* form (e.g. `"overview"`)
+ * so persisted bindings survive a `WORK_ROOT` path change such as a host
+ * mount rename. Throws `BindError` on every failure mode the caller needs
+ * to distinguish.
+ */
+function validateSubdir(workRoot, rawSubdir) {
+    // Control chars and NUL bytes can be stored on disk but explode in
+    // shell-quoted paths downstream (tmux send-keys, opencode HTTP URLs).
+    // Reject up front so the failure mode is a localised reply, not a
+    // confusing tmux error.
+    if (/[\x00-\x1f]/.test(rawSubdir)) {
+        throw new BindError('BIND_INVALID_CHARS', 'subdir contains control characters');
+    }
+    // Normalise to NFC — input from macOS Terminal often arrives NFD, but
+    // the on-disk entry was created NFC, so naive string compare misses it
+    // and realpathSync would throw ENOENT.
+    const normalised = rawSubdir.normalize('NFC').trim();
+    if (!normalised) {
+        throw new BindError('BIND_INVALID_CHARS', 'subdir is empty');
+    }
+    let realRoot;
+    try {
+        realRoot = fs.realpathSync(workRoot);
+    }
+    catch (error) {
+        // The boot-time check already verified workRoot exists; treat this
+        // as a transient (e.g. user removed it after start) and translate
+        // to a not-found error so the caller reports a localised message
+        // rather than a stack trace.
+        const errorMessage = error instanceof Error ? error.message : 'unknown error';
+        throw new BindError('BIND_NOT_FOUND', `WORK_ROOT vanished: ${errorMessage}`);
+    }
+    let canonicalCandidate;
+    let isWithinRoot;
+    try {
+        ({ canonicalPath: canonicalCandidate, isWithinRoot } =
+            (0, canonicalPathContainment_1.resolveCanonicalPathContainment)(realRoot, normalised));
+    }
+    catch {
+        throw new BindError('BIND_NOT_FOUND', `subdir not found: ${normalised}`);
+    }
+    if (!isWithinRoot) {
+        throw new BindError('BIND_OUTSIDE_ROOT', `subdir resolves outside WORK_ROOT: ${canonicalCandidate}`);
+    }
+    // Reject /bind . — binding to WORK_ROOT itself is exactly the unbound
+    // state we just spent the whole stage stopping users from sliding into.
+    // It also has no meaningful project context (no CLAUDE.md / .git scope).
+    if (canonicalCandidate === realRoot) {
+        throw new BindError('BIND_OUTSIDE_ROOT', 'cannot bind to WORK_ROOT itself; pick a subfolder');
+    }
+    const stat = fs.statSync(canonicalCandidate);
+    if (!stat.isDirectory()) {
+        throw new BindError('BIND_NOT_DIRECTORY', `${normalised} is not a directory`);
+    }
+    // Store the *relative* form so the on-disk record survives `WORK_ROOT`
+    // path changes (e.g. mount point rename). `getWorkDir` re-joins this
+    // with the current `ENV.workRoot` at runtime.
+    return path.relative(realRoot, canonicalCandidate);
+}
+/**
+ * @description Resolve a persisted binding back to a real working directory.
+ * A binding row in state.json is not enough: the folder may have been deleted
+ * or replaced after `/bind`. Agent startup/list/resume must fail before any
+ * adapter side effects in that case.
+ */
+function resolveBoundWorkDir(workRoot, binding) {
+    if (!binding)
+        return { kind: 'refuse' };
+    try {
+        const subdir = validateSubdir(workRoot, binding.subdir);
+        return { kind: 'proceed', subdir, workDir: fs.realpathSync(path.resolve(workRoot, subdir)) };
+    }
+    catch (e) {
+        if (e instanceof BindError)
+            return { kind: 'invalid', error: e };
+        throw e;
+    }
+}
+/**
+ * @description Normalise a name (topic title or subdir) for fuzzy auto-bind
+ * matching.
+ *
+ * Folds three predictable drifts between Telegram topic titles and on-disk
+ * folder names:
+ *   - case: `Overview` ↔ `overview`
+ *   - separator: `my-api` ↔ `my_api` ↔ `my api` ↔ `my.api`
+ *   - edge whitespace: `  overview  ` ↔ `overview`
+ *
+ * NFC normalisation runs first so macOS-flavoured NFD doesn't slip past
+ * the separator collapse.
+ *
+ * Anything more aggressive (typo tolerance, partial matches) is
+ * intentionally out of scope — auto-bind has to stay predictable; if it
+ * starts guessing the user loses trust in the rule.
+ *
+ * Plan §11 Этап 7 polish (smart auto-bind fuzzy, §20.10).
+ */
+function normaliseTopicName(s) {
+    return s.normalize('NFC').toLowerCase().trim().replace(/[\s._-]+/g, '-');
+}
+/**
+ * @description Find the on-disk subdir whose normalised name matches the
+ * normalised topic title. Returns `null` if no match (auto-bind falls
+ * through to the picker UX).
+ *
+ * Caller is expected to have already filtered `subdirs` to the entries
+ * surfaced in the UI — `listAvailableSubdirs` does that.
+ */
+function findAutobindSubdir(topicName, subdirs) {
+    const normalisedName = normaliseTopicName(topicName);
+    if (!normalisedName)
+        return null;
+    for (const subdir of subdirs) {
+        if (normaliseTopicName(subdir) === normalisedName)
+            return subdir;
+    }
+    return null;
+}
+/**
+ * @description Pure pagination math for the `/bind` keyboard. Extracted
+ * here so the slice / clamp logic can be unit-tested without booting
+ * Telegraf (which is what `buildBindKeyboard` in `bot.ts` wraps it with).
+ *
+ * Plan §11 Этап 7 polish — pagination kicks in once `listAvailableSubdirs`
+ * surfaces more than `pageSize` folders.
+ *
+ * `pageSize` must be positive; the bot uses `BIND_PAGE_SIZE = 20`. Out-of-
+ * range `page` values are clamped silently — a stale callback after the
+ * disk state shrank just lands on the last available page.
+ *
+ * Thin wrapper over the shared {@link paginateList}: the `/model` picker needs
+ * the same math, so the rules live there and this keeps the `/bind`-flavoured
+ * name its call sites already use.
+ */
+function paginateBindList(subdirs, page, pageSize) {
+    return (0, paginateList_1.paginateList)(subdirs, page, pageSize);
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}

package/dist/voiceQueue.d.ts

@@ -0,0 +1,7 @@
+import type { SessionKey } from './sessionKey';
+import { type SerialQueue } from './utils/serialQueue';
+/**
+ * @description Get (create-on-miss) the voice transcription queue for a thread.
+ */
+export declare function getVoiceTranscriptionQueue(key: SessionKey): SerialQueue;
+//# sourceMappingURL=voiceQueue.d.ts.map

package/dist/voiceQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voiceQueue.d.ts","sourceRoot":"","sources":["../src/voiceQueue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAkB1E;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,UAAU,GAAG,WAAW,CAQvE"}

package/dist/voiceQueue.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVoiceTranscriptionQueue = getVoiceTranscriptionQueue;
+const sessionKey_1 = require("./sessionKey");
+const serialQueue_1 = require("./utils/serialQueue");
+/**
+ * @description Per-thread FIFO queues for voice transcription jobs. Telegraf's
+ * polling loop awaits `Promise.all(updates.map(handleUpdate))` before issuing
+ * the next `getUpdates`, so a slow Groq transcription awaited inside the voice
+ * handler stalls intake of EVERY update (the whole bot freezes). The handler
+ * therefore does only cheap gating, then ENQUEUES the download+transcribe+
+ * forward job here and returns — the job runs off the update loop.
+ *
+ * One queue per thread key preserves per-topic ORDER (two voices in one topic
+ * transcribe+forward in arrival order) while letting different topics run in
+ * parallel; a stuck job blocks only its own thread's queue, never the bot.
+ *
+ * The map is bounded by the number of topics, so entries are never evicted.
+ */
+const voiceTranscriptionQueues = new Map();
+/**
+ * @description Get (create-on-miss) the voice transcription queue for a thread.
+ */
+function getVoiceTranscriptionQueue(key) {
+    const kStr = (0, sessionKey_1.keyToString)(key);
+    let queue = voiceTranscriptionQueues.get(kStr);
+    if (!queue) {
+        queue = (0, serialQueue_1.createSerialQueue)();
+        voiceTranscriptionQueues.set(kStr, queue);
+    }
+    return queue;
+}
+//# sourceMappingURL=voiceQueue.js.map

package/dist/voiceQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voiceQueue.js","sourceRoot":"","sources":["../src/voiceQueue.ts"],"names":[],"mappings":";;AAuBA,gEAQC;AA9BD,6CAA2C;AAC3C,qDAA0E;AAE1E;;;;;;;;;;;;;GAaG;AACH,MAAM,wBAAwB,GAAG,IAAI,GAAG,EAAuB,CAAC;AAEhE;;GAEG;AACH,SAAgB,0BAA0B,CAAC,GAAe;IACxD,MAAM,IAAI,GAAG,IAAA,wBAAW,EAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,KAAK,GAAG,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,IAAA,+BAAiB,GAAE,CAAC;QAC5B,wBAAwB,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/examples/.env.example

@@ -0,0 +1,17 @@
+# Paths for docker-compose.yml (README "Run with Docker"). The bot's settings and tokens are not here: they are in
+# the instance env file below, which stays on the host and is mounted read-only.
+
+# A full clone of the repository for the container (not a worktree, not the checkout a host instance runs from).
+CHECKOUT=/srv/telegramcode/checkout
+# The agents' home: their Claude / OpenCode login, sessions and CLI installs. Log them in once:
+#   docker exec -it telegramcode-main claude   →   /login
+AGENTS_HOME=/srv/telegramcode/home
+# The instance env file: TELEGRAM_BOT_TOKEN, ALLOWED_GROUP_ID, DATA_DIR, WORK_ROOT, … as for a host install.
+INSTANCE_ENV_FILE=/srv/telegramcode/instance.env
+# The DATA_DIR and WORK_ROOT the instance env file sets: mounted at the same paths inside.
+TELEGRAMCODE_DATA_DIR=/srv/telegramcode/data
+TELEGRAMCODE_WORK_ROOT=/srv/projects
+
+# Rootful Docker only (see the `user:` line in docker-compose.yml).
+# UID=1000
+# GID=1000

package/examples/docker-compose.yml

@@ -0,0 +1,36 @@
+# The whole bot in one container (README "Run with Docker"): the bot, tmux, every agent it starts, OpenCode and
+# the bot's MCP server. Build the image once from the checkout this file mounts:
+#
+#   cd <checkout> && docker build -t telegramcode -f docker/Dockerfile .
+#
+# Copy .env.example to .env next to this file and fill in the paths. The bot's own settings and tokens are NOT
+# here: they live in your instance env file (INSTANCE_ENV_FILE), which the container reads read-only. Every host
+# path that file names (DATA_DIR, WORK_ROOT, TMUX_TMPDIR, …) is mounted at the SAME path: TELEGRAMCODE_DATA_DIR
+# and TELEGRAMCODE_WORK_ROOT are its DATA_DIR and WORK_ROOT (prefixed, because compose prefers a variable your
+# shell exports over .env).
+#
+# A second instance: copy the service with its own name, hostname, checkout, home, data dir and env file
+# (another bot token and group). Ports and tmux servers are private to each container.
+#
+# Never `docker compose restart` — it ignores depends_on; use `docker compose down && docker compose up -d`.
+# To restart only the bot (agents keep running): docker exec telegramcode-main telegramcode-restart-bot
+
+services:
+  telegramcode:
+    image: telegramcode
+    container_name: telegramcode-main
+    # Fixed: the instance lock tells this container's own restarts from another machine by it.
+    hostname: telegramcode-main
+    restart: unless-stopped
+    # The bot flushes its state and releases its lock before it exits.
+    stop_grace_period: 60s
+    # Rootful Docker only: run as your own user (rootless Docker maps the container's root to you already).
+    # user: "${UID}:${GID}"
+    volumes:
+      - ${CHECKOUT}:/opt/telegramcode
+      - ${AGENTS_HOME}:/home/telegramcode
+      - ${TELEGRAMCODE_DATA_DIR}:${TELEGRAMCODE_DATA_DIR}
+      - ${TELEGRAMCODE_WORK_ROOT}:${TELEGRAMCODE_WORK_ROOT}
+      - ${INSTANCE_ENV_FILE}:${INSTANCE_ENV_FILE}:ro
+    environment:
+      - ENV_FILE=${INSTANCE_ENV_FILE}