@llblab/pi-telegram 0.39.1 → 0.39.3

package/AGENTS.md

@@ -81,7 +81,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 - A forwarding delivery id is stable across registration replacement and derives from envelope kind, source `update_id`, and stable recipient binding. Runtime instance and registration generation remain separate attempt fences. Persisted message ownership carries the stable binding so replay can rebind only to its current authenticated registration.
 - A queued receipt persists its acquiring runtime instance, OS pid/process-birth identity, session generation, acquisition id, and acquisition time. Only exact authority may settle or discard it. Same-process session replacement may reconstruct the claim and the original process may settle after transport ownership moves; a foreign process may neither replay nor settle it through generic removal or a copied acquisition id.
 - Startup and elapsed time are not owner-death proof; queued authority has no time lease. Dead-owner cleanup groups the complete receipt and transactionally rechecks pid liveness plus process-birth identity: only an absent PID or mismatched stable Linux/macOS birth proof discards all session-owned sources without replay; a matching proof is `alive`, while Windows or inaccessible birth metadata is `unverifiable`, and both non-dead outcomes keep authority queued. The live-transfer contract is authenticated offer → exact-generation bounded payload staging → recipient CAS acceptance → exact receipt-and-owner ACK → donor removal → recipient readiness. The offer freezes donor settlement/recovery; controls rebuild local closures; negative/mismatched pre-acceptance ACK cancels only an unaccepted offer and retains donor work; a lost post-acceptance ACK cannot cancel recipient authority and leaves donor memory frozen for explicit reconciliation.
-- Execution failures persist bounded diagnostics and attempt state as `retry-wait`. Automatic retry continues indefinitely with exponential `1s → 2s → 4s → 8s → 16s → 32s → 60s` delay capped at 60 seconds; later independent updates continue draining, durable authority is never silently discarded, and legacy `failed` entries resume automatically at startup. Snapshot-plus-segment journals compact only after 256 unapplied revisions or 4 MiB; snapshot-first cleanup tolerates redundant segments, and empty authority may atomically rebind bot/profile identity. Missing snapshots left by the retired broad temp cleanup rebuild only from a complete provably empty segment chain, while revisionless snapshots may recover from a validated later segment predecessor; otherwise the snapshot and segments move atomically under `tmp/telegram/recovery/` before a fresh journal is published and startup continues with informational recovery evidence.
+- Execution failures persist bounded diagnostics and attempt state as `retry-wait`, except that an exact Telegram HTTP 400 stale/deleted-thread API failure with a proven `{chatId, threadId}` terminally settles the currently executing source after best-effort shared binding invalidation. Automatic retry continues indefinitely with exponential `1s → 2s → 4s → 8s → 16s → 32s → 60s` delay capped at 60 seconds; later independent updates continue draining, durable authority is never silently discarded, and legacy `failed` entries resume automatically at startup. Snapshot-plus-segment journals compact only after 256 unapplied revisions or 4 MiB; snapshot-first cleanup tolerates redundant segments, and empty authority may atomically rebind bot/profile identity. Missing snapshots left by the retired broad temp cleanup rebuild only from a complete provably empty segment chain, while revisionless snapshots may recover from a validated later segment predecessor; otherwise the snapshot and segments move atomically under `tmp/telegram/recovery/` before a fresh journal is published and startup continues with informational recovery evidence.
 - An unresolved reaction delays only the exact governed queue item identified by chat/message sources, not unrelated queue work. Queue receipt publication follows in-memory append and precedes dispatch request; receipt-bearing turns remain queued until every exact source commits.
 - The detailed implementation and release gates live in [`docs/architecture.md`](./docs/architecture.md), [`docs/multi-instance-bus.md`](./docs/multi-instance-bus.md), and [`BACKLOG.md`](./BACKLOG.md).
 

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.39.3: Windows IPC And Outbound Voice Hotfix
+
+- `Windows IPC Replacement`: Replaces an older same-process Named Pipe server before a new session generation listens on the stable endpoint, preventing `EADDRINUSE` during reload while keeping a late stop from invalidating its successor.
+- `Windows IPC Fencing`: Applies the ownership commit fence before publishing a Named Pipe, so a stale generation that loses authority cannot expose an endpoint or block its replacement.
+- `Windows Voice Commands`: Executes trusted `.cmd` and `.bat` outbound-handler wrappers through escaped `%ComSpec%` adaptation while preserving direct shell-free execution for native executables, bounded process controls, npm command-shim argument isolation, and paths containing spaces.
+- `Windows Template Paths`: Preserves backslashes in quoted and unquoted Windows executable and artifact paths without breaking intentional escaped whitespace or quotes, allowing configured TTS handlers to produce and upload OGG/Opus voice replies through direct and follower transport.
+
+## 0.39.2: Deleted Thread Receipt Hotfix
+
+- `Deleted Thread Receipt`: Terminally settles the currently executing durable update when Telegram returns exact HTTP 400 stale/deleted-thread evidence for its `{chatId, threadId}`, including leader-first shared-store invalidation followed by follower settlement. Transient, ambiguous, unrelated, and stale-looking HTTP 5xx failures retain indefinite retry authority; persisted follower records remain restart hints rather than speculative live registrations.
+
 ## 0.39.1: Compaction Failure Formatting Hotfix
 
 - `Compaction Failure Formatting`: Preserves the HTML parse mode when a confirmed `/compact` callback reports asynchronous failure, preventing bold standalone failure headings from appearing as literal `<b>…</b>` markup in Telegram.

package/docs/architecture.md

@@ -209,7 +209,7 @@ The profile-scoped journal separates transport progress from semantic progress.
 
 Compaction runs under the journal transaction lock when either 256 unapplied segments or 4 MiB of segment bytes is reached. It publishes the complete private (`0600`) snapshot at revision `R` before best-effort deletion of segments `<= R`; failed cleanup leaves redundant segments that readers ignore. Interrupted cleanup therefore leaves either an older snapshot plus newer authoritative segments or a newer snapshot plus harmless redundant older segments. Revision gaps, conflicting duplicates, malformed segments, and identity mismatches fail closed. The logical reconstructed journal and aggregate unapplied segment bytes are independently bounded at 10,000 entries and 32 MiB as applicable; rejected growth publishes neither snapshot nor segment bytes. Compaction may temporarily require exactly one private complete snapshot of at most 32 MiB. Capacity pauses polling and valid authority files are never automatically deleted, reset, or quarantined. Only a missing-snapshot history that cannot be reconstructed safely uses the explicit evidence-preserving quarantine-and-reset compatibility fallback above.
 
-`pending` entries remain immediately executable while raw interception, routing, or grouping is incomplete. Every execution failure becomes `retry-wait` with durable attempt count, next eligible time, failure class, bounded summary, and latest failure time. The `failed` state remains schema-compatible only for legacy candidate journals and is converted to automatic retry during lifecycle startup. `queued` entries carry exact prompt/control receipts plus the acquiring Pi runtime instance, OS pid/birth identity, session generation, acquisition id, and acquisition time. Queueing alone is never completion.
+`pending` entries remain immediately executable while raw interception, routing, or grouping is incomplete. Execution failures become `retry-wait` with durable attempt count, next eligible time, failure class, bounded summary, and latest failure time, except that an exact HTTP 400 stale/deleted Telegram thread error carrying its proven request `{chatId, threadId}` terminally settles the currently executing source after shared binding invalidation; follower settlement remains idempotent when the leader already persisted that stale binding. The `failed` state remains schema-compatible only for legacy candidate journals and is converted to automatic retry during lifecycle startup. `queued` entries carry exact prompt/control receipts plus the acquiring Pi runtime instance, OS pid/birth identity, session generation, acquisition id, and acquisition time. Queueing alone is never completion.
 
 Queue receipt ownership is independent from the Telegram transport lock. A same-instance, same-process generation may reconstruct its local receipt across a fenced session replacement and may settle it after transport ownership moves. A different process reports the receipt as foreign, never republishes it into its local queue, and cannot complete it even if it reads the acquisition id. Startup no longer treats process replacement as proof that an owner died: foreign and legacy unowned receipts remain durable.
 

package/index.ts

@@ -844,6 +844,16 @@ export default function (pi: Pi.ExtensionAPI) {
         });
       },
     );
+  const staleTopicApiErrorRecoveryDeps = {
+    topicTargetStore: threadStore,
+    getSyncState: telegramSyncStateRuntime.getState,
+    setSyncState: telegramSyncStateRuntime.setState,
+    recordEvent: recordRuntimeEvent,
+  };
+  const recoverStaleTelegramTopicApiError =
+    Sync.createTelegramStaleTopicApiErrorRecoveryRuntime(
+      staleTopicApiErrorRecoveryDeps,
+    );
   const {
     owner: updateWorkerOwnerRuntime,
     leader: updateAdmissionLifecycleRuntime,
@@ -867,6 +877,12 @@ export default function (pi: Pi.ExtensionAPI) {
     worker: {
       defaultHandle: inboundRouteRuntime.handleUpdate,
       onStateChange: runtimeDiagnostics.scheduleSnapshotPersist,
+      settleTerminalExecutionFailure(error) {
+        return Sync.settleStaleTelegramTopicExecutionFailure(
+          error,
+          staleTopicApiErrorRecoveryDeps,
+        );
+      },
     },
     leader: {
       resolveBinding: resolveTelegramUpdateJournalBinding,
@@ -1056,13 +1072,6 @@ export default function (pi: Pi.ExtensionAPI) {
       onPollingStateChange: runtimeDiagnostics.scheduleSnapshotPersist,
       recordRuntimeEvent,
     });
-  const recoverStaleTelegramTopicApiError =
-    Sync.createTelegramStaleTopicApiErrorRecoveryRuntime({
-      topicTargetStore: threadStore,
-      getSyncState: telegramSyncStateRuntime.getState,
-      setSyncState: telegramSyncStateRuntime.setState,
-      recordEvent: recordRuntimeEvent,
-    });
   const authorizeFollowerApiCall = Bus.createTelegramFollowerApiCallAuthorizer({
     isMessageOwned: messageOwnershipRuntime.isOwnedByFollower,
   });

package/lib/bus-follower.ts

@@ -20,6 +20,7 @@ import type { TelegramTarget } from "./target.ts";
 import {
   isTelegramApiMethodRetrySafe,
   TelegramApiCommitUnknownError,
+  TelegramApiStaleTargetError,
 } from "./telegram-api.ts";
 import {
   createTelegramBusFollowerDeliveryIdentity,
@@ -898,6 +899,20 @@ export function createTelegramBusFollowerApiCaller(
       response?.kind === "bus.ack"
         ? response.message
         : "Telegram bus API call did not return an acknowledgement.";
+    if (
+      response?.kind === "bus.ack" &&
+      response.error?.code === "stale-target" &&
+      response.error.chatId !== undefined &&
+      response.error.threadId !== undefined
+    ) {
+      throw new TelegramApiStaleTargetError(
+        message ?? "Telegram thread target is stale.",
+        {
+          chatId: response.error.chatId,
+          threadId: response.error.threadId,
+        },
+      );
+    }
     if (
       response?.kind === "bus.ack" &&
       response.error?.code === "commit-unknown"

package/lib/bus-leader.ts

@@ -8,6 +8,7 @@
 import * as Sync from "./sync.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import {
+  getTelegramApiErrorRequestTarget,
   isTelegramApiCommitUnknownError,
   type TelegramApiCallOptions,
 } from "./telegram-api.ts";
@@ -1756,6 +1757,10 @@ async function handleFollowerApiCall(
       result,
     };
   } catch (error) {
+    const staleTarget =
+      Threads.isTelegramTopicTargetStaleError(error)
+        ? getTelegramApiErrorRequestTarget(error)
+        : undefined;
     return {
       kind: "bus.ack",
       requestId: envelope.requestId,
@@ -1764,14 +1769,22 @@ async function handleFollowerApiCall(
         error instanceof Error
           ? error.message
           : "Telegram bus API call failed.",
-      ...(isTelegramApiCommitUnknownError(error)
+      ...(staleTarget
         ? {
             error: {
-              code: "commit-unknown" as const,
-              method: error.method,
+              code: "stale-target" as const,
+              chatId: staleTarget.chatId,
+              threadId: staleTarget.threadId,
             },
           }
-        : {}),
+        : isTelegramApiCommitUnknownError(error)
+          ? {
+              error: {
+                code: "commit-unknown" as const,
+                method: error.method,
+              },
+            }
+          : {}),
     };
   }
 }

package/lib/bus.ts

@@ -816,8 +816,11 @@ export type TelegramBusEnvelope = (
           | "commit-unknown"
           | "request-id-collision"
           | "ledger-overloaded"
-          | "incompatible-protocol";
+          | "incompatible-protocol"
+          | "stale-target";
         method?: string;
+        chatId?: number;
+        threadId?: number;
       };
     }
 ) & { auth?: string };
@@ -947,6 +950,18 @@ export interface TelegramBusLocalServer {
   ensureEndpoint: () => Promise<boolean>;
 }
 
+const TELEGRAM_ACTIVE_LOCAL_SERVERS = Symbol.for(
+  "@llblab/pi-telegram/active-local-servers",
+);
+type TelegramBusServerGlobal = typeof globalThis & {
+  [TELEGRAM_ACTIVE_LOCAL_SERVERS]?: Map<string, TelegramBusLocalServer>;
+};
+
+function getActiveTelegramBusLocalServers(): Map<string, TelegramBusLocalServer> {
+  const root = globalThis as TelegramBusServerGlobal;
+  return (root[TELEGRAM_ACTIVE_LOCAL_SERVERS] ??= new Map());
+}
+
 export type TelegramBusSocketPathSource = string | (() => string);
 
 const TELEGRAM_BUS_MAX_DIRECT_UNIX_ENDPOINT_BYTES = 80;
@@ -1560,6 +1575,11 @@ export function createTelegramBusLocalServer(
     start: async () => {
       if (server) return;
       const socketPath = resolveTelegramBusSocketPath(deps.socketPath);
+      const activeServers = getActiveTelegramBusLocalServers();
+      const replacedServer = activeServers.get(socketPath);
+      if (replacedServer && replacedServer !== runtime) {
+        await replacedServer.stop();
+      }
       const usesWindowsPipe = isTelegramBusPipePath(socketPath);
       const endpointGeneration = randomBytes(8).toString("hex");
       const listenPath = usesWindowsPipe
@@ -1598,6 +1618,19 @@ export function createTelegramBusLocalServer(
           await delayTelegramBusTransportRetry(25);
         }
       }
+      if (usesWindowsPipe) {
+        await deps.beforeEndpointPublication?.();
+        const committed = deps.commitEndpointPublication
+          ? deps.commitEndpointPublication(() => {})
+          : true;
+        if (!committed) {
+          activeSocketPath = undefined;
+          activeListenPath = undefined;
+          throw new Error(
+            "Telegram bus endpoint publication lost transport ownership.",
+          );
+        }
+      }
       server = createServer((socket) => {
         sockets.add(socket);
         let buffer = "";
@@ -1631,6 +1664,7 @@ export function createTelegramBusLocalServer(
           server?.once("error", reject);
           server?.listen(listenPath, resolve);
         });
+        activeServers.set(socketPath, runtime);
         deps.recordTransportEvent?.(
           "server-started",
           getTelegramBusEndpointDiagnostics(socketPath),
@@ -1671,6 +1705,9 @@ export function createTelegramBusLocalServer(
           server = undefined;
           activeSocketPath = undefined;
           activeListenPath = undefined;
+          if (activeServers.get(socketPath) === runtime) {
+            activeServers.delete(socketPath);
+          }
           if (failedServer) {
             await new Promise<void>((resolve) =>
               failedServer.close(() => resolve()),
@@ -1686,6 +1723,12 @@ export function createTelegramBusLocalServer(
       const activeServer = server;
       const socketPath = activeSocketPath;
       const listenPath = activeListenPath;
+      if (
+        socketPath &&
+        getActiveTelegramBusLocalServers().get(socketPath) === runtime
+      ) {
+        getActiveTelegramBusLocalServers().delete(socketPath);
+      }
       server = undefined;
       activeSocketPath = undefined;
       activeListenPath = undefined;
@@ -2527,13 +2570,24 @@ function parseAckEnvelope(
       code === "commit-unknown" ||
       code === "request-id-collision" ||
       code === "ledger-overloaded" ||
-      code === "incompatible-protocol"
+      code === "incompatible-protocol" ||
+      code === "stale-target"
     ) {
+      const chatId = value.error.chatId;
+      const threadId = value.error.threadId;
+      if (
+        code === "stale-target" &&
+        (!Number.isSafeInteger(chatId) || !Number.isSafeInteger(threadId))
+      ) {
+        return undefined;
+      }
       envelope.error = {
         code,
         ...(typeof value.error.method === "string"
           ? { method: value.error.method }
           : {}),
+        ...(typeof chatId === "number" ? { chatId } : {}),
+        ...(typeof threadId === "number" ? { threadId } : {}),
       };
     }
   }

package/lib/command-templates.ts

@@ -6,7 +6,7 @@
 
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
-import { isAbsolute, resolve } from "node:path";
+import { extname, isAbsolute, normalize, resolve } from "node:path";
 
 export type CommandTemplateFailureScope = "continue" | "branch" | "root";
 
@@ -541,7 +541,8 @@ export function splitCommandTemplate(input: string): string[] {
   let quote: "'" | '"' | undefined;
   let escaped = false;
   let active = false;
-  for (const char of input) {
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index] ?? "";
     if (escaped) {
       current += char;
       escaped = false;
@@ -549,7 +550,16 @@ export function splitCommandTemplate(input: string): string[] {
       continue;
     }
     if (char === "\\" && quote !== "'") {
-      escaped = true;
+      const next = input[index + 1];
+      const escapesNext = quote === '"'
+        ? next === '"' || next === "\\"
+        : next !== undefined &&
+          (/\s/u.test(next) || next === "'" || next === '"' || next === "\\");
+      if (escapesNext) {
+        escaped = true;
+      } else {
+        current += "\\";
+      }
       active = true;
       continue;
     }
@@ -844,15 +854,66 @@ export async function execCommandTemplate(
   return lastResult;
 }
 
+const WINDOWS_COMMAND_META_CHARS = /([()\][%!^"`<>&|;, *?])/g;
+
+function escapeWindowsCommand(value: string): string {
+  return value.replace(WINDOWS_COMMAND_META_CHARS, "^$1");
+}
+
+function escapeWindowsCommandArgument(
+  value: string,
+  doubleEscapeMetaChars: boolean,
+): string {
+  let escaped = value
+    .replace(/(?=(\\+?)?)\1"/g, "$1$1\\\"")
+    .replace(/(?=(\\+?)?)\1$/g, "$1$1");
+  escaped = `"${escaped}"`.replace(WINDOWS_COMMAND_META_CHARS, "^$1");
+  return doubleEscapeMetaChars
+    ? escaped.replace(WINDOWS_COMMAND_META_CHARS, "^$1")
+    : escaped;
+}
+
+function resolveCommandTemplateSpawn(
+  command: string,
+  args: string[],
+): {
+  command: string;
+  args: string[];
+  windowsVerbatimArguments?: boolean;
+} {
+  if (
+    process.platform !== "win32" ||
+    ![".bat", ".cmd"].includes(extname(command).toLowerCase())
+  ) {
+    return { command, args };
+  }
+  const normalizedCommand = normalize(command);
+  const isNodeModulesShim = /[\\/]node_modules[\\/]\.bin[\\/][^\\/]+\.cmd$/iu
+    .test(normalizedCommand);
+  const shellCommand = [
+    escapeWindowsCommand(normalizedCommand),
+    ...args.map((arg) =>
+      escapeWindowsCommandArgument(arg, isNodeModulesShim)
+    ),
+  ].join(" ");
+  return {
+    command: process.env.ComSpec ?? process.env.COMSPEC ?? "cmd.exe",
+    args: ["/d", "/s", "/c", `"${shellCommand}"`],
+    windowsVerbatimArguments: true,
+  };
+}
+
 function execCommandTemplateOnce(
   command: string,
   args: string[],
   options: CommandTemplateExecOptions = {},
 ): Promise<CommandTemplateExecResult> {
   return new Promise((resolve) => {
-    const proc = spawn(command, args, {
+    const invocation = resolveCommandTemplateSpawn(command, args);
+    const proc = spawn(invocation.command, invocation.args, {
       cwd: options.cwd,
       shell: false,
+      windowsVerbatimArguments: invocation.windowsVerbatimArguments,
       stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
     });
     let stdout = "";

package/lib/locks.ts

@@ -423,7 +423,12 @@ function reclaimAbandonedDirectoryGuard(
     // Claim inside the still-occupied guard before making its stable path free.
     renameRecovery(sourcePath, reclaimPath);
   } catch (error) {
-    if ((error as { code?: unknown })?.code === "ENOENT") return false;
+    const code = (error as { code?: unknown })?.code;
+    if (code === "ENOENT") return false;
+    // macOS may report EINVAL instead of ENOENT when another process wins
+    // the same source rename. Only classify it as contention once the
+    // observed source is actually gone; preserve unrelated EINVAL failures.
+    if (code === "EINVAL" && !existsSync(sourcePath)) return false;
     throw error;
   }
 

package/lib/sync.ts

@@ -4,6 +4,7 @@
  * Owns pure contracts for deciding when local Telegram mirror state should be refreshed without querying Telegram on every action
  */
 
+import { getTelegramApiErrorRequestTarget } from "./telegram-api.ts";
 import { getTelegramTargetKey, type TelegramTarget } from "./target.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import {
@@ -423,6 +424,22 @@ export function createTelegramStaleTopicApiErrorRecoveryRuntime<
     recoverStaleTelegramTopicApiError(apiBody, error, deps);
 }
 
+export async function settleStaleTelegramTopicExecutionFailure<
+  TSyncState extends TelegramSyncState,
+>(
+  error: unknown,
+  deps: TelegramStaleTopicApiErrorRecoveryDeps<TSyncState>,
+): Promise<boolean> {
+  const target = getTelegramApiErrorRequestTarget(error);
+  if (!target || !isTelegramTopicTargetStaleError(error)) return false;
+  await recoverStaleTelegramTopicApiError(
+    { chat_id: target.chatId, message_thread_id: target.threadId },
+    error,
+    deps,
+  );
+  return true;
+}
+
 export async function recoverStaleTelegramTopicApiError<
   TSyncState extends TelegramSyncState,
 >(

package/lib/telegram-api.ts

@@ -587,6 +587,7 @@ export function isTelegramApiCommitUnknownError(
 class TelegramApiHttpError extends Error {
   readonly status: number | undefined;
   readonly retryAfterSeconds: number | undefined;
+  requestTarget?: { chatId: number; threadId: number };
   constructor(
     message: string,
     status: number | undefined,
@@ -598,6 +599,41 @@ class TelegramApiHttpError extends Error {
   }
 }
 
+function attachTelegramApiRequestTarget(
+  error: unknown,
+  body: Record<string, unknown> | Record<string, string>,
+): void {
+  if (!(error instanceof TelegramApiHttpError)) return;
+  const chatId = Number(body.chat_id);
+  const threadId = Number(body.message_thread_id);
+  if (!Number.isSafeInteger(chatId) || !Number.isSafeInteger(threadId)) return;
+  error.requestTarget = { chatId, threadId };
+}
+
+export class TelegramApiStaleTargetError extends Error {
+  readonly requestTarget: { chatId: number; threadId: number };
+
+  constructor(
+    message: string,
+    requestTarget: { chatId: number; threadId: number },
+  ) {
+    super(message);
+    this.name = "TelegramApiStaleTargetError";
+    this.requestTarget = { ...requestTarget };
+  }
+}
+
+export function getTelegramApiErrorRequestTarget(
+  error: unknown,
+): { chatId: number; threadId: number } | undefined {
+  const target =
+    error instanceof TelegramApiHttpError ||
+    error instanceof TelegramApiStaleTargetError
+      ? error.requestTarget
+      : undefined;
+  return target ? { ...target } : undefined;
+}
+
 export function isTelegramMessageNotModifiedError(error: unknown): boolean {
   return (
     error instanceof Error && error.message.includes("message is not modified")
@@ -1156,21 +1192,26 @@ export async function callTelegram<TResponse>(
   options?: TelegramApiCallOptions,
 ): Promise<TResponse> {
   const configuredBotToken = assertTelegramBotTokenConfigured(botToken);
-  return callTelegramWithRetry(
-    method,
-    async (family) =>
-      telegramFetch(
-        `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
-        {
-          method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify(body),
-          signal: options?.signal,
-        },
-        family,
-      ),
-    options,
-  );
+  try {
+    return await callTelegramWithRetry(
+      method,
+      async (family) =>
+        telegramFetch(
+          `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
+          {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+            signal: options?.signal,
+          },
+          family,
+        ),
+      options,
+    );
+  } catch (error) {
+    attachTelegramApiRequestTarget(error, body);
+    throw error;
+  }
 }
 
 export type TelegramBotIdentityResponse = Pick<
@@ -1206,43 +1247,48 @@ export async function callTelegramMultipart<TResponse>(
 ): Promise<TResponse> {
   const configuredBotToken = assertTelegramBotTokenConfigured(botToken);
   const fileBlob = await openAsBlob(filePath);
-  return callTelegramWithRetry(
-    method,
-    async (family) => {
-      if (family) {
-        const multipart = await buildTelegramMultipartBody(
-          fields,
-          fileField,
-          fileBlob,
-          fileName,
-        );
+  try {
+    return await callTelegramWithRetry(
+      method,
+      async (family) => {
+        if (family) {
+          const multipart = await buildTelegramMultipartBody(
+            fields,
+            fileField,
+            fileBlob,
+            fileName,
+          );
+          return telegramFetch(
+            `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
+            {
+              method: "POST",
+              headers: { "content-type": multipart.contentType },
+              body: multipart.body as unknown as BodyInit,
+              signal: options?.signal,
+            },
+            family,
+          );
+        }
+        const form = new FormData();
+        for (const [key, value] of Object.entries(fields)) {
+          form.set(key, value);
+        }
+        form.set(fileField, fileBlob, fileName);
         return telegramFetch(
           `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
           {
             method: "POST",
-            headers: { "content-type": multipart.contentType },
-            body: multipart.body as unknown as BodyInit,
+            body: form,
             signal: options?.signal,
           },
-          family,
         );
-      }
-      const form = new FormData();
-      for (const [key, value] of Object.entries(fields)) {
-        form.set(key, value);
-      }
-      form.set(fileField, fileBlob, fileName);
-      return telegramFetch(
-        `${TELEGRAM_API_BASE}/bot${configuredBotToken}/${method}`,
-        {
-          method: "POST",
-          body: form,
-          signal: options?.signal,
-        },
-      );
-    },
-    options,
-  );
+      },
+      options,
+    );
+  } catch (error) {
+    attachTelegramApiRequestTarget(error, fields);
+    throw error;
+  }
 }
 
 export async function downloadTelegramFile(

package/lib/threads.ts

@@ -2882,6 +2882,11 @@ export function getTelegramTargetFromApiBody(
 
 export function isTelegramTopicTargetStaleError(error: unknown): boolean {
   if (!(error instanceof Error)) return false;
+  const status =
+    "status" in error && typeof error.status === "number"
+      ? error.status
+      : undefined;
+  if (status !== undefined && status !== 400) return false;
   const message = error.message.toLowerCase();
   return (
     message.includes("topic_id_invalid") ||

package/lib/updates.ts

@@ -1782,6 +1782,7 @@ export interface TelegramUpdateWorkerRuntimeDeps<TContext> {
   classifyExecutionFailure?: (
     error: unknown,
   ) => TelegramUpdateExecutionFailureClassification;
+  settleTerminalExecutionFailure?: (error: unknown) => Promise<boolean>;
   scheduleRetry?: (callback: () => void, delayMs: number) => unknown;
   cancelRetry?: (handle: unknown) => void;
   batchSize?: number;
@@ -4833,13 +4834,20 @@ export function createTelegramUpdateAdmissionWorkerRuntime<
   });
   worker = createTelegramUpdateWorkerRuntime({
     ...deps,
-    executeUpdate: (update, ctx, signal) => {
+    async executeUpdate(update, ctx, signal) {
       const typedUpdate = update as TUpdate;
-      return executeUpdate(
-        deps.prepareUpdateForExecution?.(typedUpdate) ?? typedUpdate,
-        ctx,
-        signal,
-      );
+      try {
+        return await executeUpdate(
+          deps.prepareUpdateForExecution?.(typedUpdate) ?? typedUpdate,
+          ctx,
+          signal,
+        );
+      } catch (error) {
+        if (await deps.settleTerminalExecutionFailure?.(error)) {
+          return { kind: "complete" };
+        }
+        throw error;
+      }
     },
   });
   return worker;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.39.1",
+  "version": "0.39.3",
   "private": false,
   "publishConfig": {
     "access": "public"