@llblab/pi-telegram 0.39.1 → 0.39.2

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,10 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 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 };
@@ -2527,13 +2530,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/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.2",
   "private": false,
   "publishConfig": {
     "access": "public"