@llblab/pi-telegram 0.24.0 → 0.24.1

package/docs/architecture.md

@@ -105,6 +105,8 @@ Mirrored domain regressions live in `/tests/*.test.ts`. Shared test fixtures sho
 
 Telegram configuration lives in `~/.pi/agent/telegram.json`. Bot/session identity (`botToken`, `botUsername`, `botId`, `allowedUserId`, `lastUpdateId`) persists only under `profiles.default` or `profiles.<name>`; shared handlers and assistant/voice/time settings stay top-level. Authoritative transport ownership lives separately in the pi-telegram-private `~/.pi/agent/tmp/telegram/owners.json` store. Its top-level slots are `default` and validated named profile names; unrelated extensions never read or write this file.
 
+`telegram.json` is one global cross-instance configuration document. Ordinary reads rely on atomic publication and do not take the mutation guard. Every cooperating Pi instance persists only its recursive delta from the snapshot it loaded, merges that delta into the latest disk document inside `telegram.json.transaction`, and publishes atomically only when the semantic result differs; a no-op merge adopts the newer disk snapshot in memory without replacing the file. Unrelated global and profile changes therefore survive stale writers, while `lastUpdateId` additionally merges monotonically. Two serialized writers changing the same leaf use commit order, so the later local delta wins. A non-transactional external editor cannot participate in that conflict protocol: it should write through same-directory atomic replacement while Pi is idle, then let instances reload; an editor racing the transaction may lose its same-leaf change and must retry from the resulting file.
+
 ### Setup Flow
 
 `/telegram-setup` progressively resolves the bot token:
@@ -123,9 +125,19 @@ Telegram configuration lives in `~/.pi/agent/telegram.json`. Bot/session identit
 - Session replacement suspends polling/watchers without releasing ownership so the next session in the same process can resume. A registered follower snapshots its assigned target into a short-lived same-process handoff, stops the old receiver/heartbeat, and re-registers through the live leader without marking or replacing its Telegram thread.
 - Live external owners require explicit takeover confirmation. Long-lived timers compare against snapshotted owner identity and stop local transport work when the slot no longer matches.
 - `owners.json` owns only Telegram transport control. Local extension and accepted queue state remain per Pi instance when ownership moves, but previews, final delivery, dispatch transport mutations, and delayed Bot API work fail closed until exact direct or follower authority becomes valid again.
-- Every acquisition, refresh, release, takeover, and stale recovery serializes through the sibling `owners.json.transaction` guard. The guard publishes one private generation-named owner record atomically, validates filename/payload generation agreement, fences stale recovery and delayed release against replacement-owner ABA, and fails closed on malformed state, unverifiable ownership, contention timeout, or unsupported filesystem behavior. The JSON store publishes through a private same-directory temporary file and atomic rename; atomic payload replacement does not replace transaction serialization.
+- Exact ownership remains checked every second, while the durable owner heartbeat refresh runs every two seconds and becomes stale after eight seconds. This keeps replacement detection responsive while halving steady-state atomic `owners.json` rewrites without changing the cross-platform file-transaction authority. Every acquisition, refresh, release, takeover, and stale recovery serializes through the sibling `owners.json.transaction` guard. The guard publishes one private generation-named owner record atomically, validates filename/payload generation agreement, fences stale recovery and delayed release against replacement-owner ABA, and fails closed on malformed state, unverifiable ownership, contention timeout, or unsupported filesystem behavior. The JSON store publishes through a private same-directory temporary file and atomic rename; atomic payload replacement does not replace transaction serialization.
 - `owners.json` is authoritative and private. `state.json` remains an observable snapshot, `logs.jsonl` remains diagnostics, and followers remain authenticated bus registrations rather than ownership-file writers.
 
+### Persistence I/O Baseline
+
+The three runtime files have different authority and write pressure. Preserve that distinction when optimizing them:
+
+- `owners.json` is safety-critical transport authority. Acquire, release, takeover, stale recovery, and two-second leader lease refresh mutate it. The steady-state baseline is one cached atomic rewrite every two seconds per active profile, or 43,200 refreshes/day; one-second ownership checks are read-only. Every mutation serializes the full cross-process read/check/write through `owners.json.transaction`.
+- `state.json` combines recovery-critical thread/capability state with observational runtime projections. Every explicit thread-store `persist()` builds a semantic snapshot, but an unchanged payload skips temporary-file creation and rename after ignoring `writtenAtMs`; changed snapshots retain the full atomic replacement path. Diagnostics scheduling coalesces requests across a bounded 100 ms window. Only the exact transport owner commits; non-owners reload current disk state instead of publishing.
+- `logs.jsonl` is fail-soft observational evidence, never routing authority. Runtime events admitted in one JavaScript turn batch by captured profile path into one size check, one profile-wide file transaction, and one append while preserving event order. Batching adds no timer or shutdown-loss window; separate profiles remain isolated, and one failed group does not drop another. Scope reset and rotation retain their serialized copy/replace path. The 5 MiB value is a rotation threshold: an authorized writer rotates between batched records before the next record crosses it, so overshoot is bounded to one admitted record plus reset metadata; a writer without reset authority defers rotation to the owner.
+
+This baseline counts write-producing code paths rather than filesystem implementation details that vary between ext4, APFS, NTFS, and network-backed home directories. Optimization evidence should compare these deterministic triggers first, then use platform smoke evidence for rename, named-pipe, crash, and cleanup behavior. Recovery-critical `state.json` fields are `bot`, `identities`, `reservations`, `pendingProvisions`, `syncObservations`, and `threads`; `runtime`, `liveRoster`, `diagnostics`, and `writtenAtMs` are observational and may use bounded coalescing when authority checks remain unchanged.
+
 Version `0.24.0` intentionally does not read or migrate the former agent-level `locks.json`; upgrading resets Telegram ownership. Run `/telegram-connect` when a fresh owner is not elected automatically. Delete `~/.pi/agent/tmp/telegram/owners.json` and its stale transaction guard, when no owner process is live, to reset only pi-telegram transport ownership without deleting configuration, diagnostics, or other extensions' state.
 
 ### Threaded Mode Multi-Instance Bus

package/docs/multi-instance-bus.md

@@ -147,7 +147,7 @@ A registered instance exposes:
 
 ## Leader Election
 
-Leader election is heartbeat-gated and lock-backed:
+Leader election is heartbeat-gated and lock-backed. The polling owner checks exact lock ownership every second, refreshes its durable lease every two seconds, and becomes stale after eight seconds; the serialized expected-owner transaction remains the final cross-platform election authority.
 
 1. On startup, read the Telegram lock.
 2. If no leader exists, acquire leadership and start polling.
@@ -161,9 +161,9 @@ Followers first try to re-register after leader reload or unknown-heartbeat resp
 
 Implemented transport:
 
-### Local IPC endpoint under agent temp dir
+### Local IPC endpoint with bounded native paths
 
-Leader opens a local Node `net` endpoint: a Unix-domain socket under the agent temp directory on Unix-like platforms, or a deterministic Windows named pipe (`\\.\pipe\pi-telegram-...`) on native Windows. On Unix, each server listens on a private generation socket and atomically publishes the stable profile path as a relative symlink; delayed shutdown closes only its private path and cannot remove a replacement generation's link. Followers register, heartbeat, and exchange routed events. The transport boundary owns endpoint derivation, socket-vs-pipe detection, bounded operation-aware retry policy, timeout/transient IPC error classification, endpoint reachability probes, and request-scoped transport events. Follower registration uses a longer registration-specific response timeout than ordinary heartbeat/forwarding calls because the leader may need to provision a Telegram thread before it can return the assigned target; timing out that handshake leaves a visible tab with no follower heartbeat. Keep this handshake to the true critical path: create/reuse the target, persist the live binding, and return it. Connected notices and replaced-thread reconciliation cleanup are non-critical and should run after registration so a follower becomes routable before Telegram client/server UI convergence work finishes.
+Leader opens a local Node `net` endpoint: a Unix-domain socket under the agent temp directory on Unix-like platforms, or a deterministic Windows named pipe (`\\.\pipe\pi-telegram-...`) on native Windows. A filesystem-style endpoint supplied by legacy state or a transport harness normalizes deterministically to the same Windows pipe boundary before listen/connect. On Unix, an endpoint that would exceed conservative domain-socket pathname limits maps to a private user-scoped, hash-derived path under the OS temp directory; ordinary agent paths remain under `tmp/telegram`. On Unix, each server listens on a private generation socket and atomically publishes the stable profile path as a relative symlink; delayed shutdown closes only its private path and cannot remove a replacement generation's link. Followers register, heartbeat, and exchange routed events. The transport boundary owns endpoint derivation, socket-vs-pipe detection, bounded operation-aware retry policy, timeout/transient IPC error classification, endpoint reachability probes, and request-scoped transport events. Follower registration uses a longer registration-specific response timeout than ordinary heartbeat/forwarding calls because the leader may need to provision a Telegram thread before it can return the assigned target; timing out that handshake leaves a visible tab with no follower heartbeat. Keep this handshake to the true critical path: create/reuse the target, persist the live binding, and return it. Connected notices and replaced-thread reconciliation cleanup are non-critical and should run after registration so a follower becomes routable before Telegram client/server UI convergence work finishes.
 
 Pros:
 

package/docs/public-api.md

@@ -109,6 +109,8 @@ interface TelegramConfig {
 
 Bot/session identity always persists under `profiles.<name>`. The ordinary setup path uses `profiles.default`; `/telegram-setup default` and `/telegram-connect default` are exact aliases for the bare commands. Named profiles use the same shape. Shared handlers plus `assistant`, `voice`, and `time` remain top-level. On the first `0.24.0` load, unambiguous legacy root identity moves atomically into `profiles.default`; identical duplicates collapse, complementary fields merge, and conflicting values fail closed without modifying the file.
 
+The file is global across Pi instances. Cooperating instances serialize recursive delta merges through `telegram.json.transaction`, preserve unrelated global/profile changes from newer disk snapshots, and merge `lastUpdateId` monotonically. A semantically unchanged merge adopts the latest disk state in memory without replacing the file; later commits win when two deltas intentionally change the same leaf. For manual edits, stop or idle the connected instances, publish a complete valid file atomically, and let them reload. A non-transactional editor racing Pi persistence has no same-leaf conflict guarantee.
+
 Hidden/default semantics are represented by absence:
 
 - `assistant.proactivePush` defaults to `true`; omit it to keep projection enabled, or set it explicitly to `false` to disable it. When enabled, each completed public assistant text block from local or autonomous work is projected to the authorized Telegram target once and in source order. This includes visible intermediate commentary/checkpoints and the final block. It excludes token deltas, hidden reasoning, tool calls/arguments/results, Telegram-owned turns, empty blocks, and stale authority. Projection uses the configured Rich or HTML assistant renderer and binds admitted work to the exact target, profile/token transport generation, direct leader epoch or follower registration generation, and session generation. The old top-level `proactivePush` key is ignored; move the setting manually under `assistant`.

package/lib/bus-transport.ts

@@ -35,21 +35,17 @@ export interface TelegramBusTransportRetryPolicyOverrides {
 
 export type TelegramBusTransportOperation = "registration" | "operation";
 
-export const TELEGRAM_BUS_REGISTRATION_RETRY: TelegramBusTransportRetryPolicy = {
-  attempts: 10,
-  delayMs: 150,
-};
+export const TELEGRAM_BUS_REGISTRATION_RETRY: TelegramBusTransportRetryPolicy =
+  {
+    attempts: 10,
+    delayMs: 150,
+  };
 
 export const TELEGRAM_BUS_OPERATION_RETRY: TelegramBusTransportRetryPolicy = {
   attempts: 3,
   delayMs: 100,
 };
 
-export const TELEGRAM_BUS_PIPE_REGISTRATION_RETRY =
-  TELEGRAM_BUS_REGISTRATION_RETRY;
-
-export const TELEGRAM_BUS_PIPE_OPERATION_RETRY = TELEGRAM_BUS_OPERATION_RETRY;
-
 export function getTelegramBusPipePath(input: {
   agentDir: string;
   scope: string;
@@ -200,13 +196,11 @@ export function createTelegramBusTransportTimeoutError(
 
 export function delayTelegramBusTransportRetry(ms: number): Promise<void> {
   return new Promise((resolve) => {
-    const timer = setTimeout(resolve, ms);
-    timer.unref?.();
+    setTimeout(resolve, ms);
   });
 }
 
-export interface TelegramBusTransportProbeResult
-  extends TelegramBusTransportEndpointDiagnostics {
+export interface TelegramBusTransportProbeResult extends TelegramBusTransportEndpointDiagnostics {
   reachable: boolean;
   error?: TelegramBusTransportErrorInfo;
 }
@@ -238,7 +232,6 @@ export function probeTelegramBusEndpoint(input: {
         ),
       });
     }, timeoutMs);
-    timeout.unref?.();
     socket.once("connect", () => settle({ ...diagnostics, reachable: true }));
     socket.once("error", (error) =>
       settle({

package/lib/bus.ts

@@ -5,7 +5,7 @@
  * cross-instance forwarding helpers, and the live follower registry model.
  */
 
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import {
   chmodSync,
   existsSync,
@@ -23,7 +23,7 @@ import {
   type Server,
   type Socket,
 } from "node:net";
-import { platform as getPlatform } from "node:os";
+import { platform as getPlatform, tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 
 import {
@@ -33,6 +33,7 @@ import {
   getTelegramBusEndpointDiagnostics,
   getTelegramBusFollowerEndpoint,
   getTelegramBusLeaderEndpoint,
+  getTelegramBusPipePath,
   getTelegramBusTransportRetryPolicy,
   isTelegramBusPipePath,
   isRetryableTelegramBusTransportError,
@@ -43,8 +44,6 @@ import {
 import type { TelegramTarget } from "./target.ts";
 import { resolveAgentDir } from "./paths.ts";
 
-export type TelegramBusRole = "leader" | "follower";
-
 export interface TelegramBusProcessRuntime {
   instanceId: string;
   manualFollowerOwnerId: string;
@@ -524,10 +523,38 @@ export interface TelegramBusLocalServer {
 
 export type TelegramBusSocketPathSource = string | (() => string);
 
+const TELEGRAM_BUS_MAX_DIRECT_UNIX_ENDPOINT_BYTES = 80;
+
 export function resolveTelegramBusSocketPath(
   source: TelegramBusSocketPathSource,
+  platform: NodeJS.Platform | string = getPlatform(),
 ): string {
-  return typeof source === "function" ? source() : source;
+  const endpoint = typeof source === "function" ? source() : source;
+  if (platform === "win32") {
+    if (isTelegramBusPipePath(endpoint)) return endpoint;
+    return getTelegramBusPipePath({
+      agentDir: dirname(endpoint),
+      scope: basename(endpoint),
+    });
+  }
+  const ownerScope = process.getuid?.() ?? "user";
+  const fallbackDir = join(tmpdir(), `pi-telegram-${ownerScope}`);
+  if (
+    dirname(endpoint) === fallbackDir &&
+    /^[0-9a-f]{16}\.sock$/u.test(basename(endpoint))
+  ) {
+    return endpoint;
+  }
+  if (
+    Buffer.byteLength(endpoint) <= TELEGRAM_BUS_MAX_DIRECT_UNIX_ENDPOINT_BYTES
+  ) {
+    return endpoint;
+  }
+  const digest = createHash("sha256")
+    .update(endpoint)
+    .digest("hex")
+    .slice(0, 16);
+  return join(fallbackDir, `${digest}.sock`);
 }
 
 export interface TelegramBusLocalServerDeps {
@@ -617,7 +644,7 @@ export function createTelegramBusForeignOwnedUpdateForwarder<
       deps.recordRuntimeEvent?.(
         "bus",
         response?.kind === "bus.ack"
-          ? response.message ?? "Follower rejected forwarded Telegram update."
+          ? (response.message ?? "Follower rejected forwarded Telegram update.")
           : "Follower returned no forwarding acknowledgement.",
         {
           phase: "foreign-update-forward-rejected",
@@ -885,7 +912,7 @@ export function createTelegramBusLocalServer(
       const endpointGeneration = randomBytes(8).toString("hex");
       const listenPath = usesWindowsPipe
         ? socketPath
-        : join(dirname(socketPath), `.pi-telegram-${endpointGeneration}.sock`);
+        : join(dirname(socketPath), `.pt-${endpointGeneration}.sock`);
       activeSocketPath = socketPath;
       activeListenPath = listenPath;
       deps.recordTransportEvent?.(
@@ -1110,7 +1137,6 @@ function sendTelegramBusLocalEnvelopeOnce(
         ),
       );
     }, timeoutMs);
-    timeout.unref?.();
     socket.setEncoding("utf8");
     socket.once("connect", () => {
       socket.write(encodeTelegramBusEnvelope(options.envelope));
@@ -1130,16 +1156,20 @@ function sendTelegramBusLocalEnvelopeOnce(
 export async function sendTelegramBusLocalEnvelope(
   options: TelegramBusLocalClientOptions,
 ): Promise<TelegramBusEnvelope | undefined> {
-  const attempts = Math.max(1, options.retry?.attempts ?? 1);
-  const delayMs = Math.max(0, options.retry?.delayMs ?? 0);
+  const resolvedOptions = {
+    ...options,
+    socketPath: resolveTelegramBusSocketPath(options.socketPath),
+  };
+  const attempts = Math.max(1, resolvedOptions.retry?.attempts ?? 1);
+  const delayMs = Math.max(0, resolvedOptions.retry?.delayMs ?? 0);
   for (let attempt = 1; ; attempt += 1) {
     try {
-      return await sendTelegramBusLocalEnvelopeOnce(options);
+      return await sendTelegramBusLocalEnvelopeOnce(resolvedOptions);
     } catch (error) {
       const info = classifyTelegramBusTransportError(error);
-      options.recordTransportEvent?.("client-failed", {
-        ...getTelegramBusEndpointDiagnostics(options.socketPath),
-        ...getTelegramBusEnvelopeDiagnostics(options.envelope),
+      resolvedOptions.recordTransportEvent?.("client-failed", {
+        ...getTelegramBusEndpointDiagnostics(resolvedOptions.socketPath),
+        ...getTelegramBusEnvelopeDiagnostics(resolvedOptions.envelope),
         attempt,
         attempts,
         ...info,
@@ -1147,9 +1177,9 @@ export async function sendTelegramBusLocalEnvelope(
       if (attempt >= attempts || !isRetryableTelegramBusTransportError(error)) {
         throw error;
       }
-      options.recordTransportEvent?.("client-retry", {
-        ...getTelegramBusEndpointDiagnostics(options.socketPath),
-        ...getTelegramBusEnvelopeDiagnostics(options.envelope),
+      resolvedOptions.recordTransportEvent?.("client-retry", {
+        ...getTelegramBusEndpointDiagnostics(resolvedOptions.socketPath),
+        ...getTelegramBusEnvelopeDiagnostics(resolvedOptions.envelope),
         attempt,
         attempts,
         delayMs,
@@ -1408,8 +1438,7 @@ function parseForwardMessageEnvelope(
         (value.forwardCommentBatchPosition === "comment" ||
           value.forwardCommentBatchPosition === "forward")
           ? {
-              forwardCommentBatchPosition:
-                value.forwardCommentBatchPosition,
+              forwardCommentBatchPosition: value.forwardCommentBatchPosition,
             }
           : {}),
         sentAtMs: value.sentAtMs,

package/lib/command-templates.ts

@@ -36,9 +36,7 @@ export interface CommandTemplateObjectConfig {
 }
 
 export type CommandTemplateValue =
-  | string
-  | CommandTemplateConfig[]
-  | CommandTemplateObjectConfig;
+  string | CommandTemplateConfig[] | CommandTemplateObjectConfig;
 
 export type CommandTemplateConfig = string | CommandTemplateObjectConfig;
 
@@ -90,12 +88,6 @@ const COMMAND_TEMPLATE_RISK_LABEL_ORDER: CommandTemplateRiskLabel[] = [
   "risk.platform_specific",
 ];
 
-export type CommandTemplateExecCommand = (
-  command: string,
-  args: string[],
-  options?: CommandTemplateExecOptions,
-) => Promise<CommandTemplateExecResult>;
-
 function normalizeCommandTemplateArgs(value: string[] | undefined): string[] {
   if (!Array.isArray(value)) return [];
   return value.map(String).map((item) => item.trim());
@@ -257,9 +249,18 @@ function getLeafCommandTemplateRiskLabels(
     labels.add("risk.broad_fs_write");
   }
   if (
-    ["curl", "wget", "ssh", "scp", "sftp", "rsync", "nc", "ncat", "telnet", "ftp"].includes(
-      command,
-    ) ||
+    [
+      "curl",
+      "wget",
+      "ssh",
+      "scp",
+      "sftp",
+      "rsync",
+      "nc",
+      "ncat",
+      "telnet",
+      "ftp",
+    ].includes(command) ||
     (command === "git" &&
       hasAnyArg(args, ["clone", "fetch", "pull", "push", "ls-remote"])) ||
     ["npm", "pnpm", "yarn", "pip", "cargo"].includes(command)
@@ -283,13 +284,32 @@ function getLeafCommandTemplateRiskLabels(
     labels.add("risk.long_running");
   }
   if (
-    ["systemctl", "launchctl", "osascript", "open", "xdg-open", "powershell", "pwsh", "cmd.exe", "apt", "apt-get", "dnf", "yum", "brew", "pacman", "apk", "xclip", "wl-copy"].includes(
-      command,
-    )
+    [
+      "systemctl",
+      "launchctl",
+      "osascript",
+      "open",
+      "xdg-open",
+      "powershell",
+      "pwsh",
+      "cmd.exe",
+      "apt",
+      "apt-get",
+      "dnf",
+      "yum",
+      "brew",
+      "pacman",
+      "apk",
+      "xclip",
+      "wl-copy",
+    ].includes(command)
   ) {
     labels.add("risk.platform_specific");
   }
-  if (["pass", "gpg", "ssh-add"].includes(command) || hasSecretTouchingText(parts)) {
+  if (
+    ["pass", "gpg", "ssh-add"].includes(command) ||
+    hasSecretTouchingText(parts)
+  ) {
     labels.add("risk.secret_touching");
   }
   return sortRiskLabels(labels);
@@ -347,10 +367,6 @@ function pad(value: number, width: number): string {
   return String(value).padStart(width, "0");
 }
 
-export function isCommandTemplateRepeatPlaceholder(name: string): boolean {
-  return /^_{0,6}(?:index|prev|next|repeat)$/.test(name);
-}
-
 export function getCommandTemplateRepeatDefaults(
   index: number,
   repeat: number,

package/lib/config.ts

@@ -119,32 +119,6 @@ export function isValidTelegramProfileName(name: string): boolean {
   );
 }
 
-/**
- * Resolve bot/session identity from the canonical default or named profile.
- * Shared bridge settings always remain top-level.
- */
-export function resolveTelegramActiveProfile(
-  config: TelegramConfig,
-  profileName?: string,
-): {
-  botToken?: string;
-  botUsername?: string;
-  botId?: number;
-  allowedUserId?: number;
-  lastUpdateId?: number;
-} {
-  const effectiveProfileName = profileName ?? TELEGRAM_DEFAULT_PROFILE_NAME;
-  const profile = config.profiles?.[effectiveProfileName];
-  if (!profile) return {};
-  return {
-    botToken: profile.botToken,
-    botUsername: profile.botUsername,
-    botId: profile.botId,
-    allowedUserId: profile.allowedUserId,
-    lastUpdateId: profile.lastUpdateId,
-  };
-}
-
 /** List defined profile names. */
 export function getTelegramProfileNames(config: TelegramConfig): string[] {
   return Object.keys(config.profiles ?? {}).sort();
@@ -560,10 +534,7 @@ export function createTelegramConfigStore(
         !profileName || profileName === TELEGRAM_DEFAULT_PROFILE_NAME
           ? undefined
           : profileName;
-      if (
-        normalizedProfileName &&
-        !config.profiles?.[normalizedProfileName]
-      ) {
+      if (normalizedProfileName && !config.profiles?.[normalizedProfileName]) {
         return false;
       }
       activeProfileName = normalizedProfileName;
@@ -607,9 +578,8 @@ export function createTelegramConfigStore(
       config = normalized.changed
         ? withTelegramFileTransaction(`${configPath}.transaction`, () => {
             const latestConfig = readTelegramConfigForTransaction(configPath);
-            const latestNormalized = normalizeTelegramDefaultProfileConfig(
-              latestConfig,
-            );
+            const latestNormalized =
+              normalizeTelegramDefaultProfileConfig(latestConfig);
             if (latestNormalized.changed) {
               writeTelegramConfigInTransaction(
                 agentDir,
@@ -642,7 +612,9 @@ export function createTelegramConfigStore(
               desiredConfig as Record<string, unknown>,
               latestConfig as Record<string, unknown>,
             ) as TelegramConfig;
-            writeTelegramConfigInTransaction(agentDir, configPath, merged);
+            if (!configValuesEqual(latestConfig, merged)) {
+              writeTelegramConfigInTransaction(agentDir, configPath, merged);
+            }
             return merged;
           },
         );

package/lib/inbound.ts

@@ -23,8 +23,7 @@ const MAX_INBOUND_HANDLER_OUTPUT_LENGTH = 12_000;
 const MAX_INBOUND_HANDLER_FAILURE_STREAM_LENGTH = 4_000;
 
 type TelegramInboundCommandTemplateConfig =
-  | string
-  | CommandTemplateObjectConfig;
+  string | CommandTemplateObjectConfig;
 
 export interface TelegramInboundHandlerConfig {
   match?: string | string[];
@@ -74,10 +73,6 @@ export interface TelegramInboundHandlerExecResult {
   killed: boolean;
 }
 
-export interface TelegramInboundHandlerRuntimeContext {
-  cwd: string;
-}
-
 export interface TelegramInboundHandlerRuntimeDeps<TContext> {
   getHandlers: () => TelegramInboundHandlerConfig[] | undefined;
   execCommand: (
@@ -102,9 +97,7 @@ export interface TelegramInboundHandlerRuntime<TContext> {
 }
 
 export type TelegramInboundProgrammaticHandlerResult =
-  | string
-  | { text: string }
-  | undefined;
+  string | { text: string } | undefined;
 
 export interface TelegramInboundProgrammaticHandlerInput {
   kind: string;
@@ -179,12 +172,6 @@ export function getTelegramInboundProgrammaticHandlers(
   ];
 }
 
-export function hasTelegramInboundHandler(kind?: string): boolean {
-  const registry = getOrCreateInboundHandlerRegistry();
-  if (kind !== undefined) return (registry.handlers.get(kind)?.length ?? 0) > 0;
-  return Array.from(registry.handlers.values()).some((list) => list.length > 0);
-}
-
 export function clearTelegramInboundHandlers(): void {
   getOrCreateInboundHandlerRegistry().handlers.clear();
 }
@@ -281,13 +268,6 @@ export function findTelegramInboundHandlers(
   );
 }
 
-export function findTelegramInboundHandler(
-  handlers: TelegramInboundHandlerConfig[] | undefined,
-  file: TelegramInboundHandlerFile,
-): TelegramInboundHandlerConfig | undefined {
-  return findTelegramInboundHandlers(handlers, file)[0];
-}
-
 function hasInboundFilePlaceholder(value: string): boolean {
   return /\{file\}/.test(value);
 }
@@ -420,9 +400,13 @@ function formatTelegramInboundHandlerFailure(
     `Inbound handler exited with code ${result.code}${result.killed ? " (killed)" : ""}`,
   ];
   if (result.stderr.trim())
-    parts.push(`stderr:\n${truncateTelegramInboundFailureStream(result.stderr)}`);
+    parts.push(
+      `stderr:\n${truncateTelegramInboundFailureStream(result.stderr)}`,
+    );
   if (result.stdout.trim())
-    parts.push(`stdout:\n${truncateTelegramInboundFailureStream(result.stdout)}`);
+    parts.push(
+      `stdout:\n${truncateTelegramInboundFailureStream(result.stdout)}`,
+    );
   return parts.join("\n\n");
 }
 
@@ -445,7 +429,13 @@ async function executeTelegramInboundHandlerInvocation(
     cwd,
     timeout,
     ...(typeof handler === "object" && handler.retry !== undefined
-      ? { retry: resolveTelegramInboundNumericControlField(handler.retry, {}, "retry") }
+      ? {
+          retry: resolveTelegramInboundNumericControlField(
+            handler.retry,
+            {},
+            "retry",
+          ),
+        }
       : {}),
     ...(stdin !== undefined ? { stdin } : {}),
   });
@@ -519,7 +509,13 @@ async function executeTelegramTextHandlerInvocation(
     timeout,
     stdin: text,
     ...(typeof handler === "object" && handler.retry !== undefined
-      ? { retry: resolveTelegramInboundNumericControlField(handler.retry, {}, "retry") }
+      ? {
+          retry: resolveTelegramInboundNumericControlField(
+            handler.retry,
+            {},
+            "retry",
+          ),
+        }
       : {}),
   });
   if (result.code !== 0)

package/lib/lifecycle.ts

@@ -196,19 +196,6 @@ export function createTelegramSessionContextStore<TContext>(
   };
 }
 
-export function createTelegramSessionContextTracker(
-  store: Pick<TelegramSessionContextStore<ExtensionContext>, "set" | "clear">,
-): TelegramSessionLifecycleHooks {
-  return {
-    onSessionStart: async (_event, ctx) => {
-      store.set(ctx);
-    },
-    onSessionShutdown: async (_event, ctx) => {
-      store.clear(ctx);
-    },
-  };
-}
-
 export function createTelegramSessionGenerationFence(
   store: TelegramSessionContextStore<ExtensionContext>,
   hooks: TelegramSessionLifecycleHooks,