charness 0.0.0-stage → 3.0.0

package/dist/sessionKey.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @description Platform-agnostic conversation addressing for the core.
+ *
+ * The core routes every agent session, every output frame and every piece of
+ * persisted state by a {@link SessionKey}. It deliberately knows NOTHING about
+ * how that key is spelled on the wire: serialization belongs to the connector
+ * that owns the surface (see {@link SessionKeyCodec}).
+ *
+ * That split is load-bearing rather than cosmetic. The serialized key leaks onto
+ * disk in four places — `state.json` field names, tmux session names, the
+ * per-thread JSON maps under `DATA_DIR`, and the file-intake directories — so a
+ * unified cross-platform format would rename all of them and orphan every live
+ * agent session. Keeping the format inside the connector lets Telegram keep its
+ * historical `"<chatId>:<threadId>"` spelling byte-for-byte while a future
+ * tracker or Teams connector picks a prefixed form of its own.
+ */
+/**
+ * @name PlatformId
+ * @description The surfaces the core can address. `test` is the in-repo test
+ * double used to exercise degraded capability paths; real surfaces are added
+ * here when their connector lands.
+ */
+export type PlatformId = 'telegram' | 'jira' | 'test';
+/**
+ * @description The core's routing key: a conversation on one platform.
+ *
+ * - `space`  — the container: Telegram chat id, tracker project, Teams channel.
+ * - `thread` — the conversation inside it: Telegram `message_thread_id`,
+ *   tracker issue key, Teams thread id.
+ *
+ * Both are strings because only Telegram's ids happen to be numeric; the core
+ * never does arithmetic on them, it only compares and serializes. A connector
+ * that needs the native type converts at its own boundary.
+ */
+export interface SessionKey {
+    platform: PlatformId;
+    space: string;
+    thread: string;
+}
+/**
+ * @description The connector's ownership of its own key spelling.
+ *
+ * `matches` is what makes {@link keyFromString} work without a platform
+ * argument: the 20-odd decode call sites read strings back out of `state.json`,
+ * `DATA_DIR` maps and the scheduler's MCP surface, where no platform is in hand.
+ * The registry asks each codec whether a string is its own and the first owner
+ * decodes, so recognition stays with the connector that defined the format.
+ *
+ * Formats MUST be mutually unambiguous. Telegram's is all-numeric
+ * (`-100123:42`); every later platform uses a `<platform>:` prefix, which the
+ * numeric shape can never match.
+ */
+export interface SessionKeyCodec {
+    readonly platform: PlatformId;
+    encode(key: SessionKey): string;
+    decode(serialized: string): SessionKey;
+    matches(serialized: string): boolean;
+    /**
+     * Inverse of {@link keyToSlug} for this platform's keys: the key a slug was
+     * built from with `separator`, or `null` when the slug is not one of this
+     * platform's. Only the codec knows where its halves end once every `:` became
+     * the separator. Optional — a codec without it is never read back from a
+     * tmux session or directory name.
+     *
+     * Slug shapes MUST be mutually unambiguous too, and that is a separate
+     * guarantee: `keyToSlug` is lossy, so formats that are disjoint as strings
+     * can still collide as slugs. {@link tryKeyFromSlug} takes the first codec
+     * that claims a name, and a misread name is a session adopted or reaped for
+     * the wrong conversation.
+     */
+    decodeSlug?(slug: string, separator: string): SessionKey | null;
+}
+/**
+ * @description Register (or replace) a platform's codec. Idempotent per
+ * platform so a module that self-registers on import is safe to import twice,
+ * and so a test can swap a codec without leaving a duplicate behind.
+ */
+export declare function registerSessionKeyCodec(codec: SessionKeyCodec): void;
+/** Drop a platform's codec — only the S5 test double needs this. */
+export declare function unregisterSessionKeyCodec(platform: PlatformId): void;
+/** The codec owning `platform`, or `null` when none is registered. */
+export declare function getSessionKeyCodec(platform: PlatformId): SessionKeyCodec | null;
+/**
+ * @description Canonical serialization of a {@link SessionKey} — the `Map` key
+ * and `state.json` field name form. Dispatches to the owning connector's codec.
+ *
+ * Round-trips losslessly with {@link keyFromString}.
+ */
+export declare function keyToString(key: SessionKey): string;
+/**
+ * @description Inverse of {@link keyToString}. Throws on input no registered
+ * codec claims — callers should only feed strings that came from
+ * {@link keyToString} or from a trusted state file. Use
+ * {@link tryKeyFromString} where a hand-edited state file must be survivable.
+ */
+export declare function keyFromString(serialized: string): SessionKey;
+/**
+ * @description Non-throwing {@link keyFromString} — returns `null` so callers
+ * iterating a persisted map can skip a rogue field instead of aborting the
+ * whole load. Deliberately still throws when NO codec is registered at all
+ * (see {@link assertRegistryArmed}): skipping every field silently is the one
+ * outcome worse than crashing.
+ */
+export declare function tryKeyFromString(serialized: string): SessionKey | null;
+/**
+ * @description The serialized key rewritten for a context that cannot carry
+ * `:` — a tmux session name (`-`) or a directory name (`_`).
+ *
+ * Single source of truth for the three on-disk name shapes that embed a key:
+ * tmux sessions, the `DATA_DIR/files/` intake dirs and the
+ * `DATA_DIR/jsonstream/` session dirs. All three previously open-coded the
+ * same substitution.
+ *
+ * The inverse is {@link tryKeyFromSlug}: each codec reads its own slugs back,
+ * since a format with more than one `:` (Jira's) cannot be split on a fixed
+ * position once they all became the separator.
+ */
+export declare function keyToSlug(key: SessionKey, separator: string): string;
+/**
+ * @description Inverse of {@link keyToSlug}: the first registered codec that
+ * recognises the slug decodes it, so a tmux session or directory name of any
+ * platform parses back to its key. `null` for a slug no codec claims (an
+ * unrelated tmux session, a foreign directory). Throws on an empty registry,
+ * like {@link tryKeyFromString}.
+ */
+export declare function tryKeyFromSlug(slug: string, separator: string): SessionKey | null;
+/**
+ * @description Structural equality for two keys.
+ *
+ * `platform` is part of the comparison on purpose: without it a Telegram
+ * conversation `{space:'123', thread:'5'}` would equal a tracker one with the
+ * same ids, and two unrelated conversations would silently collide in any Map
+ * or lookup built on this predicate.
+ */
+export declare function keysEqual(a: SessionKey, b: SessionKey): boolean;
+//# sourceMappingURL=sessionKey.d.ts.map

package/dist/sessionKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionKey.d.ts","sourceRoot":"","sources":["../src/sessionKey.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,UAAU,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAAC;IAChC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAAC;IACvC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAAC;CACjE;AAKD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAOpE;AAED,oEAAoE;AACpE,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAGpE;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,UAAU,GAAG,eAAe,GAAG,IAAI,CAE/E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAInD;AAkBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAK5D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAStE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAOjF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAE/D"}

package/dist/sessionKey.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * @description Platform-agnostic conversation addressing for the core.
+ *
+ * The core routes every agent session, every output frame and every piece of
+ * persisted state by a {@link SessionKey}. It deliberately knows NOTHING about
+ * how that key is spelled on the wire: serialization belongs to the connector
+ * that owns the surface (see {@link SessionKeyCodec}).
+ *
+ * That split is load-bearing rather than cosmetic. The serialized key leaks onto
+ * disk in four places — `state.json` field names, tmux session names, the
+ * per-thread JSON maps under `DATA_DIR`, and the file-intake directories — so a
+ * unified cross-platform format would rename all of them and orphan every live
+ * agent session. Keeping the format inside the connector lets Telegram keep its
+ * historical `"<chatId>:<threadId>"` spelling byte-for-byte while a future
+ * tracker or Teams connector picks a prefixed form of its own.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSessionKeyCodec = registerSessionKeyCodec;
+exports.unregisterSessionKeyCodec = unregisterSessionKeyCodec;
+exports.getSessionKeyCodec = getSessionKeyCodec;
+exports.keyToString = keyToString;
+exports.keyFromString = keyFromString;
+exports.tryKeyFromString = tryKeyFromString;
+exports.keyToSlug = keyToSlug;
+exports.tryKeyFromSlug = tryKeyFromSlug;
+exports.keysEqual = keysEqual;
+/** Registration order matters: {@link keyFromString} asks `matches` in it. */
+const codecs = [];
+/**
+ * @description Register (or replace) a platform's codec. Idempotent per
+ * platform so a module that self-registers on import is safe to import twice,
+ * and so a test can swap a codec without leaving a duplicate behind.
+ */
+function registerSessionKeyCodec(codec) {
+    const existing = codecs.findIndex((registered) => registered.platform === codec.platform);
+    if (existing >= 0) {
+        codecs[existing] = codec;
+        return;
+    }
+    codecs.push(codec);
+}
+/** Drop a platform's codec — only the S5 test double needs this. */
+function unregisterSessionKeyCodec(platform) {
+    const existing = codecs.findIndex((registered) => registered.platform === platform);
+    if (existing >= 0)
+        codecs.splice(existing, 1);
+}
+/** The codec owning `platform`, or `null` when none is registered. */
+function getSessionKeyCodec(platform) {
+    return codecs.find((registered) => registered.platform === platform) ?? null;
+}
+/**
+ * @description Canonical serialization of a {@link SessionKey} — the `Map` key
+ * and `state.json` field name form. Dispatches to the owning connector's codec.
+ *
+ * Round-trips losslessly with {@link keyFromString}.
+ */
+function keyToString(key) {
+    const codec = getSessionKeyCodec(key.platform);
+    if (!codec)
+        throw new Error(`No SessionKeyCodec registered for platform "${key.platform}"`);
+    return codec.encode(key);
+}
+/**
+ * @description Guard against the one failure mode the registry could otherwise
+ * hide: an entry point that reaches a decode site without ever importing a
+ * connector. Every codec-less decode would then look like ordinary malformed
+ * data, so `state.json` would load as zero bindings and every live agent
+ * session would appear orphaned — silently. An empty registry is a wiring bug,
+ * never bad data, so it throws from BOTH the strict and the lenient decoder.
+ */
+function assertRegistryArmed() {
+    if (codecs.length === 0) {
+        throw new Error('No SessionKeyCodec registered — the platform connector module was never imported');
+    }
+}
+/**
+ * @description Inverse of {@link keyToString}. Throws on input no registered
+ * codec claims — callers should only feed strings that came from
+ * {@link keyToString} or from a trusted state file. Use
+ * {@link tryKeyFromString} where a hand-edited state file must be survivable.
+ */
+function keyFromString(serialized) {
+    assertRegistryArmed();
+    const codec = codecs.find((registered) => registered.matches(serialized));
+    if (!codec)
+        throw new Error(`Invalid SessionKey string: "${serialized}"`);
+    return codec.decode(serialized);
+}
+/**
+ * @description Non-throwing {@link keyFromString} — returns `null` so callers
+ * iterating a persisted map can skip a rogue field instead of aborting the
+ * whole load. Deliberately still throws when NO codec is registered at all
+ * (see {@link assertRegistryArmed}): skipping every field silently is the one
+ * outcome worse than crashing.
+ */
+function tryKeyFromString(serialized) {
+    assertRegistryArmed();
+    const codec = codecs.find((registered) => registered.matches(serialized));
+    if (!codec)
+        return null;
+    try {
+        return codec.decode(serialized);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @description The serialized key rewritten for a context that cannot carry
+ * `:` — a tmux session name (`-`) or a directory name (`_`).
+ *
+ * Single source of truth for the three on-disk name shapes that embed a key:
+ * tmux sessions, the `DATA_DIR/files/` intake dirs and the
+ * `DATA_DIR/jsonstream/` session dirs. All three previously open-coded the
+ * same substitution.
+ *
+ * The inverse is {@link tryKeyFromSlug}: each codec reads its own slugs back,
+ * since a format with more than one `:` (Jira's) cannot be split on a fixed
+ * position once they all became the separator.
+ */
+function keyToSlug(key, separator) {
+    return keyToString(key).replaceAll(':', separator);
+}
+/**
+ * @description Inverse of {@link keyToSlug}: the first registered codec that
+ * recognises the slug decodes it, so a tmux session or directory name of any
+ * platform parses back to its key. `null` for a slug no codec claims (an
+ * unrelated tmux session, a foreign directory). Throws on an empty registry,
+ * like {@link tryKeyFromString}.
+ */
+function tryKeyFromSlug(slug, separator) {
+    assertRegistryArmed();
+    for (const codec of codecs) {
+        const key = codec.decodeSlug?.(slug, separator) ?? null;
+        if (key)
+            return key;
+    }
+    return null;
+}
+/**
+ * @description Structural equality for two keys.
+ *
+ * `platform` is part of the comparison on purpose: without it a Telegram
+ * conversation `{space:'123', thread:'5'}` would equal a tracker one with the
+ * same ids, and two unrelated conversations would silently collide in any Map
+ * or lookup built on this predicate.
+ */
+function keysEqual(a, b) {
+    return a.platform === b.platform && a.space === b.space && a.thread === b.thread;
+}
+//# sourceMappingURL=sessionKey.js.map

package/dist/sessionKey.js.map

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

package/dist/sessionPick.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @description Pure decision logic for the `/sessions` number-reply picker.
+ *
+ * Extracted from `bot.ts` so it can be unit-tested without booting Telegraf
+ * (mirrors `agentTrigger.ts` / `threadRouting.ts`). Given the raw reply text
+ * and how many sessions were shown, it decides what the bot should do — it
+ * does NOT touch any state or perform the resume itself.
+ */
+/**
+ * @name SessionPickAction
+ * @description Discriminated outcome of interpreting a reply while a thread
+ * is armed in session-pick mode.
+ *
+ * - `cancel`     — user typed `0` (or `/cancel` is handled separately); exit pick-mode.
+ * - `select`     — a valid 1-based number; `index` is the 0-based list index to resume.
+ * - `invalid`    — a number outside `1..listLength`; stay armed, show an error.
+ * - `passthrough`— non-numeric text; exit pick-mode and let normal handling run.
+ */
+export type SessionPickAction = {
+    kind: 'cancel';
+} | {
+    kind: 'select';
+    index: number;
+} | {
+    kind: 'invalid';
+} | {
+    kind: 'passthrough';
+};
+/**
+ * @description Decide how to treat `text` for a thread armed in session-pick
+ * mode, given that `listLength` sessions were shown.
+ *
+ * Rules:
+ *   - "0"               → cancel
+ *   - "n" (1..len)      → select index n-1
+ *   - "n" (out of range)→ invalid (caller keeps the thread armed)
+ *   - anything else     → passthrough (caller disarms, normal flow continues)
+ *
+ * Surrounding whitespace on a bare number is tolerated ("  3 " → select 2).
+ */
+export declare function checkSessionPickAction(text: string, listLength: number): SessionPickAction;
+//# sourceMappingURL=sessionPick.d.ts.map

package/dist/sessionPick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionPick.d.ts","sourceRoot":"","sources":["../src/sessionPick.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,CAAC;AAQ5B;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAQ1F"}

package/dist/sessionPick.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * @description Pure decision logic for the `/sessions` number-reply picker.
+ *
+ * Extracted from `bot.ts` so it can be unit-tested without booting Telegraf
+ * (mirrors `agentTrigger.ts` / `threadRouting.ts`). Given the raw reply text
+ * and how many sessions were shown, it decides what the bot should do — it
+ * does NOT touch any state or perform the resume itself.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSessionPickAction = checkSessionPickAction;
+/** Matches a reply that is ONLY an optional-whitespace-wrapped run of digits. */
+const bareNumberPattern = /^\s*(\d+)\s*$/;
+/** The sentinel number a user sends to cancel the picker without resuming. */
+const cancelNumber = 0;
+/**
+ * @description Decide how to treat `text` for a thread armed in session-pick
+ * mode, given that `listLength` sessions were shown.
+ *
+ * Rules:
+ *   - "0"               → cancel
+ *   - "n" (1..len)      → select index n-1
+ *   - "n" (out of range)→ invalid (caller keeps the thread armed)
+ *   - anything else     → passthrough (caller disarms, normal flow continues)
+ *
+ * Surrounding whitespace on a bare number is tolerated ("  3 " → select 2).
+ */
+function checkSessionPickAction(text, listLength) {
+    const match = bareNumberPattern.exec(text);
+    if (!match)
+        return { kind: 'passthrough' };
+    const picked = Number(match[1]);
+    if (picked === cancelNumber)
+        return { kind: 'cancel' };
+    if (picked >= 1 && picked <= listLength)
+        return { kind: 'select', index: picked - 1 };
+    return { kind: 'invalid' };
+}
+//# sourceMappingURL=sessionPick.js.map

package/dist/sessionPick.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionPick.js","sourceRoot":"","sources":["../src/sessionPick.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAoCH,wDAQC;AA1BD,iFAAiF;AACjF,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAE1C,8EAA8E;AAC9E,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB;;;;;;;;;;;GAWG;AACH,SAAgB,sBAAsB,CAAC,IAAY,EAAE,UAAkB;IACrE,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IAE3C,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,IAAI,MAAM,KAAK,YAAY;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACvD,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM,IAAI,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE,CAAC;IACtF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC"}

package/dist/shutdown.d.ts

@@ -0,0 +1,126 @@
+/**
+ * @description Ordered, deterministic graceful-shutdown sequence shared by
+ * every signal-driven exit path (`SIGINT`, `SIGTERM`) of the bot.
+ *
+ * **Why a dedicated module:**
+ *
+ *   - **Single owner of exit ordering.** The previous code had two SIGTERM
+ *     handlers: `installLockCleanupHandlers()` (in `instanceLock.ts`) was
+ *     registered first and called `releaseLock(); process.exit(0)` *synchronously*,
+ *     pre-empting the bot's own async `state.flush()`. Frequent reloads
+ *     under nodemon could therefore lose the last <500ms of state (one
+ *     debounce window). The fix is to remove the lock module's signal
+ *     handlers entirely and route every signal through this orchestrator,
+ *     which awaits the flush before releasing the lock.
+ *
+ *   - **Bounded by a watchdog.** If `state.flush()` hangs (disk full,
+ *     network FS that lost its mount), the sequence still terminates
+ *     within {@link DEFAULT_WATCHDOG_MS} so the next nodemon respawn can
+ *     reclaim the lock instead of waiting forever.
+ *
+ *   - **Testable.** Dependencies are injected, so a unit test can assert
+ *     ordering (`state.flush()` resolves before `releaseLock()`) and
+ *     watchdog behaviour without spinning up Telegram or the lockfile.
+ *
+ * **What it deliberately does NOT do:** stop tmux sessions or kill the
+ * OpenCode HTTP server. Both run in external process groups and survive
+ * the bot process by design — the reattach path on the next boot picks
+ * them up. Killing them here would defeat the whole "hot reload keeps
+ * agents alive" property the surrounding plan rests on.
+ */
+/**
+ * @description Upper bound (ms) on the whole graceful-shutdown sequence — the
+ * watchdog forces `releaseLock(); exit(0)` when it elapses first. Raised from
+ * 3s when the sequence gained the bounded (≤~7s) output flush. Exported because
+ * the lock module's same-token handoff wait must OUT-WAIT this window (the
+ * incoming nodemon respawn polls the lock while the predecessor finishes
+ * shutting down); an undersized wait aborts the new process and leaves the bot
+ * down until the next file change.
+ */
+export declare const DEFAULT_WATCHDOG_MS = 10000;
+export interface ShutdownDeps {
+    /** Name of the triggering signal (`SIGINT` / `SIGTERM` / etc.), for logs. */
+    signal: string;
+    /** Telegraf bot; only `.stop(signal)` is called. */
+    bot: {
+        stop: (signal?: string) => void;
+    };
+    /** State store; only `.flush()` is awaited. */
+    state: {
+        flush: () => Promise<void>;
+    };
+    /**
+     * Optional: drain the off-loop update dispatcher's per-thread queues so
+     * updates enqueued during the ~1s hot-reload window still finish routing to
+     * their live agent (the `dropPendingUpdates:false` guarantee). Runs AFTER
+     * `bot.stop()` (polling halted → no new enqueue) and BEFORE `state.flush()`
+     * (so the drained handlers' state writes land in the flush). MUST self-bound
+     * (the dispatcher races its own timeout) so it can't eat the flush's watchdog
+     * budget; the outer watchdog is the backstop.
+     */
+    drainPendingUpdates?: () => Promise<void>;
+    /**
+     * Optional: flush every thread's not-yet-delivered agent output (the
+     * coalesce buffers / DM drafts, then the paced send FIFOs) so a hot-reload
+     * restart can't swallow answer chunks that were already emitted but not yet
+     * sent. Runs AFTER {@link cleanupTimers} and BEFORE {@link clearTransientFrames}
+     * (content lands first, then the transient frames are deleted) — both before
+     * `bot.stop()`, while the Telegram client is fully alive. MUST self-bound
+     * (the bot-side flush races its own timeout) so a hung Telegram API can't
+     * eat the whole watchdog budget; the outer watchdog is the backstop.
+     */
+    finalizePendingOutput?: () => Promise<void>;
+    /** Release the single-instance lockfile (idempotent — owner-checked inside). */
+    releaseLock: () => void;
+    /** Terminate the process. Real prod value: `(code) => process.exit(code)`. */
+    exit: (code: number) => void;
+    /** Optional: clear any setInterval handles the bot kept (GC sweep, etc.). */
+    cleanupTimers?: () => void;
+    /**
+     * Optional: best-effort delete of any TRANSIENT status frames (the
+     * "✽ working…" liveness frame, the live thinking indicator, the dedicated
+     * sub-agent status) still on screen, so a graceful exit doesn't leave them
+     * orphaned in a topic forever (their ids live only in volatile in-memory
+     * state). Runs AFTER {@link cleanupTimers} (so no tick re-creates a frame
+     * mid-sweep) and BEFORE `bot.stop()` (the Telegram client must still send the
+     * deletes). MUST self-bound (see the bot-side sweep) so a slow API can't eat
+     * into `state.flush()`'s watchdog budget; the outer watchdog is the backstop.
+     */
+    clearTransientFrames?: () => Promise<void>;
+    /** Logger; defaults to `console.log`. Tests pass a sink to silence output. */
+    log?: (msg: string) => void;
+    /** Override the watchdog for tests. */
+    watchdogMs?: number;
+}
+/**
+ * @description Run the ordered shutdown sequence:
+ *
+ *   1. `cleanupTimers()` — drop any background `setInterval`s so they
+ *      don't fire mid-shutdown and re-dirty state.
+ *   1a. `await finalizePendingOutput()` — flush the not-yet-delivered agent
+ *      output (coalesce buffers / DM drafts → send FIFOs) while the Telegram
+ *      client is still up, so a restart can't swallow it. Self-bounded.
+ *   1b. `await clearTransientFrames()` — best-effort delete of the
+ *      "✽ working…" / thinking / sub-agent status frames still on screen,
+ *      while the Telegram client is still up. Self-bounded so it can't
+ *      starve the flush.
+ *   2. `bot.stop(signal)` — Telegraf stops long-polling. Synchronous in
+ *      Telegraf 4.x, so safe to call before the flush.
+ *   2b. `await drainPendingUpdates()` — drain the off-loop update queues so
+ *      updates enqueued during a hot-reload still route to their live agent.
+ *      Self-bounded, so it can't starve the flush's watchdog budget.
+ *   3. `await state.flush()` — atomic-write any pending state changes.
+ *      THIS is the step the old `releaseLock(); process.exit(0)` raced;
+ *      we wait for the on-disk rename to land here.
+ *   4. `releaseLock()` — drop the lockfile so the incoming nodemon
+ *      respawn can claim it. Idempotent and owner-checked, so the
+ *      `process.on('exit')` safety net in `lock.ts` finding nothing to do
+ *      is fine.
+ *   5. `exit(0)` — let Node tear the rest down.
+ *
+ * The watchdog races the whole sequence (steps 2-4): if it fires first,
+ * we still call `releaseLock(); exit(0)` so the operator's terminal
+ * unblocks and nodemon's next iteration finds a free lock.
+ */
+export declare function gracefulShutdown(deps: ShutdownDeps): Promise<void>;
+//# sourceMappingURL=shutdown.d.ts.map

package/dist/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../src/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,GAAG,EAAE;QAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACzC,+CAA+C;IAC/C,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;IACtC;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;;;;;;OASG;IACH,qBAAqB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,gFAAgF;IAChF,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,8EAA8E;IAC9E,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B;;;;;;;;;OASG;IACH,oBAAoB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,8EAA8E;IAC9E,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuFxE"}