@llblab/pi-telegram 0.42.3 → 0.43.0

package/lib/sync.ts

@@ -4,10 +4,11 @@
  * 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 { getTelegramApiErrorRequestTarget, isTelegramStaleTargetHttpError } from "./telegram-api.ts";
 import { getTelegramTargetKey, type TelegramTarget } from "./target.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import {
+  createTelegramCleanupTargetProtection,
   getTelegramTargetFromApiBody,
   isTelegramTopicTargetStaleError,
   provisionOwnBusTopic,
@@ -121,6 +122,7 @@ export interface TelegramManualThreadDisconnectDeps<TSyncState> {
     | undefined;
   topicTargetStore: Pick<
     TelegramTopicTargetStore,
+    | "list"
     | "markStaleByTarget"
     | "persist"
     | "upsertPendingCleanup"
@@ -247,16 +249,21 @@ export function createTelegramManualThreadDisconnectHandler<
           target,
           requestedAtMs: (deps.getNowMs ?? Date.now)(),
         };
+        const departingRecord = deps.topicTargetStore.list().find((record) => record.instanceId === currentRecord.instanceId &&
+          record.target.chatId === target.chatId && record.target.threadId === target.threadId);
+        const isCleanupTargetProtected = createTelegramCleanupTargetProtection(deps.topicTargetStore, departingRecord);
         deps.topicTargetStore.upsertPendingCleanup(intent);
         await deps.topicTargetStore.persist();
+        const cleanupPlan = ThreadReconciler.planThreadReconciliation({
+          nowMs: (deps.getNowMs ?? Date.now)(),
+          currentLeaderEpoch: leaderEpoch,
+          records: [],
+          pendingCleanups: [intent],
+        });
         const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(
-          ThreadReconciler.planThreadReconciliation({
-            nowMs: (deps.getNowMs ?? Date.now)(),
-            currentLeaderEpoch: leaderEpoch,
-            records: [],
-            pendingCleanups: [intent],
-          }),
+          cleanupPlan,
           {
+            isCleanupTargetProtected,
             callApi(method, body) {
               return deps.callApi(method, body);
             },
@@ -277,6 +284,9 @@ export function createTelegramManualThreadDisconnectHandler<
             recordRuntimeEvent: deps.recordRuntimeEvent,
           },
         );
+        if (cleanupPlan.actions.some((action) => isCleanupTargetProtected(action.target, action))) {
+          return "Thread disconnect superseded by a new binding.";
+        }
         cleanupPending = Boolean(cleanup.incompleteActions?.length);
       }
       const leaderTarget = deps.getLeaderTarget();
@@ -404,7 +414,7 @@ export interface TelegramStaleTopicApiErrorRecoveryDeps<TSyncState> {
   topicTargetStore: Pick<
     TelegramTopicTargetStore,
     "load" | "markStaleByTarget" | "persist"
-  >;
+  > & Partial<Pick<TelegramTopicTargetStore, "invalidateTarget">>;
   getSyncState: () => TSyncState;
   setSyncState: (state: TSyncState) => void;
   recordEvent: (
@@ -413,6 +423,46 @@ export interface TelegramStaleTopicApiErrorRecoveryDeps<TSyncState> {
     details?: Record<string, unknown>,
   ) => void;
   getNowMs?: () => number;
+  isCurrent?: () => boolean;
+  isAuthorityCurrent?: () => boolean;
+}
+
+export function captureTelegramStaleTargetRequestRecovery<TSyncState extends TelegramSyncState>(
+  body: Record<string, unknown>,
+  deps: TelegramStaleTopicApiErrorRecoveryDeps<TSyncState> & {
+    topicTargetStore: Pick<TelegramTopicTargetStore, "load" | "list" | "markStaleByTarget" | "persist" | "invalidateTarget">;
+    getCurrentLeaderEpoch: () => number | string | undefined;
+    getSessionGeneration: () => number;
+    getProfileName: () => string | undefined;
+    onRecovered: () => void;
+  },
+): ((error: unknown) => Promise<void>) | undefined {
+  const target = getTelegramTargetFromApiBody(body);
+  const epoch = deps.getCurrentLeaderEpoch();
+  if (!target || epoch === undefined) return undefined;
+  const key = getTelegramTargetKey(target);
+  const record = deps.topicTargetStore.list().find((candidate) => getTelegramTargetKey(candidate.target) === key);
+  if (!record) return undefined;
+  const generation = deps.getSessionGeneration();
+  const profile = deps.getProfileName();
+  const isAuthorityCurrent = (): boolean => deps.getCurrentLeaderEpoch() === epoch &&
+    deps.getSessionGeneration() === generation && deps.getProfileName() === profile;
+  const isCurrent = (): boolean => {
+    const current = deps.topicTargetStore.list().find((candidate) => getTelegramTargetKey(candidate.target) === key);
+    return isAuthorityCurrent() &&
+      current?.instanceId === record.instanceId && current?.profileKey === record.profileKey &&
+      current?.updatedAtMs === record.updatedAtMs && current?.createdAtMs === record.createdAtMs;
+  };
+  return async (error) => {
+    const requestTarget = getTelegramApiErrorRequestTarget(error);
+    if (!isTelegramStaleTargetHttpError(error) || !requestTarget ||
+      getTelegramTargetKey(requestTarget) !== key || !isCurrent()) return;
+    if (await recoverStaleTelegramTopicApiError(
+      { chat_id: target.chatId, message_thread_id: target.threadId }, error, { ...deps, isCurrent, isAuthorityCurrent },
+    )) {
+      deps.onRecovered();
+    }
+  };
 }
 
 export function createTelegramStaleTopicApiErrorRecoveryRuntime<
@@ -448,12 +498,16 @@ export async function recoverStaleTelegramTopicApiError<
   deps: TelegramStaleTopicApiErrorRecoveryDeps<TSyncState>,
 ): Promise<boolean> {
   const target = getTelegramTargetFromApiBody(apiBody);
-  if (!target || !isTelegramTopicTargetStaleError(error)) return false;
-  await deps.topicTargetStore.load();
-  if (
-    !deps.topicTargetStore.markStaleByTarget(target, "deleted", String(error))
-  ) {
-    return false;
+  if (!target || !isTelegramTopicTargetStaleError(error) || deps.isCurrent?.() === false) return false;
+  if (deps.isCurrent) {
+    if (!deps.topicTargetStore.invalidateTarget || !await deps.topicTargetStore.invalidateTarget(
+      target, deps.isCurrent, String(error),
+    )) return false;
+    if (deps.isAuthorityCurrent?.() === false) return false;
+  } else {
+    await deps.topicTargetStore.load();
+    if (!deps.topicTargetStore.markStaleByTarget(target, "deleted", String(error))) return false;
+    await deps.topicTargetStore.persist();
   }
   const nowMs = (deps.getNowMs ?? Date.now)();
   let state = markTelegramSyncSliceSuspect(deps.getSyncState(), "topic-state", {
@@ -466,8 +520,12 @@ export async function recoverStaleTelegramTopicApiError<
     reason: "stale-api-error",
     action: "topic-target-stale",
   }) as TSyncState;
+  state = markTelegramSyncSliceSuspect(state, "target-bindings", {
+    nowMs,
+    reason: "stale-api-error",
+    action: "topic-target-stale",
+  }) as TSyncState;
   deps.setSyncState(state);
-  await deps.topicTargetStore.persist();
   deps.recordEvent("bus", error, {
     phase: "topic-target-stale",
     chatId: target.chatId,
@@ -606,6 +664,7 @@ export async function ensureTelegramLeaderThreadBinding(
   });
   deps.recordThreadReconciliationPlan?.(replacementPlan);
   await ThreadReconciler.applyThreadReconciliationPlan(replacementPlan, {
+    isCleanupTargetProtected: createTelegramCleanupTargetProtection(deps.topicTargetStore),
     callApi: deps.callApi,
     markStaleByTarget: (target, syncStatus, lastSyncError) =>
       deps.topicTargetStore.markStaleByTarget(

package/lib/telegram-api.ts

@@ -466,6 +466,8 @@ export interface TelegramApiClient {
 }
 
 export interface TelegramBridgeApiRuntimeDeps {
+  captureRequestErrorHandler?: (body: Record<string, unknown>) =>
+    ((error: unknown) => Promise<void>) | undefined;
   client: TelegramApiClient;
   tempDir: string;
   maxFileSizeBytes: number;
@@ -634,6 +636,11 @@ export function getTelegramApiErrorRequestTarget(
   return target ? { ...target } : undefined;
 }
 
+export function isTelegramStaleTargetHttpError(error: unknown): boolean {
+  if (!(error instanceof TelegramApiHttpError) || error.status !== 400) return false;
+  return /^Telegram API \w+ failed: HTTP 400: Bad Request: (message thread not found|thread not found|topic not found|topic deleted|topic closed|thread closed|forum topic closed|message thread closed|topic_id_invalid|topic_closed)$/i.test(error.message);
+}
+
 export function isTelegramMessageNotModifiedError(error: unknown): boolean {
   return (
     error instanceof Error && error.message.includes("message is not modified")
@@ -1438,6 +1445,7 @@ export function createTelegramAssistantDraftSender(deps: {
 export function createDefaultTelegramBridgeApiRuntime(deps: {
   getBotToken: () => string | undefined;
   recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];
+  captureRequestErrorHandler?: TelegramBridgeApiRuntimeDeps["captureRequestErrorHandler"];
 }): TelegramBridgeApiRuntime {
   return createTelegramBridgeApiRuntime({
     client: createTelegramApiClient(deps.getBotToken, {
@@ -1447,12 +1455,23 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
     maxFileSizeBytes: TELEGRAM_INBOUND_FILE_MAX_BYTES,
     tempFileMaxAgeMs: TELEGRAM_TEMP_FILE_MAX_AGE_MS,
     recordRuntimeEvent: deps.recordRuntimeEvent,
+    captureRequestErrorHandler: deps.captureRequestErrorHandler,
   });
 }
 
 export function createTelegramBridgeApiRuntime(
   deps: TelegramBridgeApiRuntimeDeps,
 ): TelegramBridgeApiRuntime {
+  const recoverRequestError = async (
+    handler: ((error: unknown) => Promise<void>) | undefined,
+    error: unknown,
+  ): Promise<void> => {
+    try {
+      await handler?.(error);
+    } catch (recoveryError) {
+      deps.recordRuntimeEvent("api", recoveryError, { phase: "stale-target-recovery" });
+    }
+  };
   const now = deps.now ?? Date.now;
   const chatActionMinIntervalMs = Math.max(
     0,
@@ -1488,6 +1507,7 @@ export function createTelegramBridgeApiRuntime(
     body: Record<string, unknown>,
     options?: TelegramApiCallOptions,
   ): Promise<TResponse> => {
+    const recoverError = deps.captureRequestErrorHandler?.(body);
     const chatActionKey = getChatActionKey(method, body);
     if (chatActionKey) {
       const nowMs = now();
@@ -1516,7 +1536,8 @@ export function createTelegramBridgeApiRuntime(
           gate.notBeforeMs = now() + chatActionMinIntervalMs;
           return result;
         })
-        .catch((error: unknown) => {
+        .catch(async (error: unknown) => {
+          await recoverRequestError(recoverError, error);
           if (error instanceof TelegramApiHttpError && error.status === 429) {
             const retryAfterMs = Math.max(
               chatActionMinIntervalMs,
@@ -1550,6 +1571,12 @@ export function createTelegramBridgeApiRuntime(
     try {
       return await deps.client.call<TResponse>(method, body, options);
     } catch (error) {
+      await recoverRequestError(recoverError, error);
+      if (method === "deleteMessage" && error instanceof TelegramApiHttpError &&
+        error.status === 400 && error.message ===
+          "Telegram API deleteMessage failed: HTTP 400: Bad Request: message to delete not found") {
+        return true as TResponse;
+      }
       deps.recordRuntimeEvent(
         "api",
         error,
@@ -1574,6 +1601,7 @@ export function createTelegramBridgeApiRuntime(
       fileName,
       options,
     ) => {
+      const recoverError = deps.captureRequestErrorHandler?.(fields);
       try {
         return await deps.client.callMultipart(
           method,
@@ -1584,6 +1612,7 @@ export function createTelegramBridgeApiRuntime(
           options,
         );
       } catch (error) {
+        await recoverRequestError(recoverError, error);
         deps.recordRuntimeEvent(
           "multipart",
           error,
@@ -1676,11 +1705,13 @@ export function createTelegramBridgeApiRuntime(
     sendRichMessageDraft: (body) =>
       callRecorded<boolean>("sendRichMessageDraft", body),
     editMessageText: async (body) => {
+      const recoverError = deps.captureRequestErrorHandler?.(body);
       try {
         await deps.client.call("editMessageText", body);
         return "edited";
       } catch (error) {
         if (isTelegramMessageNotModifiedError(error)) return "unchanged";
+        await recoverRequestError(recoverError, error);
         deps.recordRuntimeEvent(
           "api",
           error,

package/lib/thread-reconciler.ts

@@ -202,6 +202,7 @@ export interface ThreadReconciliationApplyResult {
 }
 
 export interface ThreadReconciliationApplyPorts {
+  isCleanupTargetProtected?: (target: ThreadTarget, action: ThreadReconciliationAction) => boolean;
   callApi?: <TResponse>(
     method: string,
     body: Record<string, unknown>,
@@ -576,6 +577,7 @@ export async function applyThreadReconciliationPlan(
         incompleteActions.push(action);
         continue;
       }
+      if (ports.isCleanupTargetProtected?.(action.target, action)) continue;
       let closeConfirmed = false;
       try {
         await ports.callApi("closeForumTopic", {
@@ -598,6 +600,7 @@ export async function applyThreadReconciliationPlan(
         incompleteActions.push(action);
         continue;
       }
+      if (ports.isCleanupTargetProtected?.(action.target, action)) continue;
       const changed =
         ports.markStaleByTarget?.(action.target, "closed") ?? false;
       if (changed) persistFences.push(action);
@@ -632,7 +635,12 @@ export async function applyThreadReconciliationPlan(
         continue;
       }
       let deleteConfirmed = false;
+      let superseded = false;
       for (const method of ["closeForumTopic", "deleteForumTopic"]) {
+        if (ports.isCleanupTargetProtected?.(action.target, action)) {
+          superseded = true;
+          break;
+        }
         if (shouldSkipForStaleLeaderEpoch(action, ports)) break;
         try {
           await ports.callApi(method, {
@@ -660,6 +668,15 @@ export async function applyThreadReconciliationPlan(
         incompleteActions.push(action);
         continue;
       }
+      if (superseded || ports.isCleanupTargetProtected?.(action.target, action)) {
+        ports.recordRuntimeEvent?.("telegram", "Cancelled cleanup of a protected Telegram target", {
+          phase: "thread-reconciler-cleanup-target-reused",
+          action: action.kind,
+          chatId: action.target.chatId,
+          threadId: action.target.threadId,
+        });
+        continue;
+      }
       if (!deleteConfirmed) {
         ports.recordRuntimeEvent?.(
           "telegram",

package/lib/threads.ts

@@ -21,6 +21,7 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { dirname } from "node:path";
+import { isDeepStrictEqual } from "node:util";
 
 import {
   isTelegramApiCommitUnknownError,
@@ -229,6 +230,11 @@ export interface TelegramTopicTargetStore {
   /** Discard process-local projections and reload owner-published state. */
   refresh?: () => Promise<void>;
   persist: () => Promise<void>;
+  invalidateTarget: (
+    target: TelegramTarget,
+    isCurrent: () => boolean,
+    lastSyncError: string,
+  ) => Promise<boolean>;
   list: () => TelegramTopicTargetRecord[];
   getFollowerRecoveryHintByTarget?: (
     target: TelegramTarget,
@@ -316,6 +322,53 @@ export function reconcileTelegramFreshAllocationCursor(
   return true;
 }
 
+export function createTelegramCleanupTargetProtection(
+  store: Pick<TelegramTopicTargetStore, "list"> & Partial<Pick<TelegramTopicTargetStore, "listReservations" | "listPendingProvisions" | "listPendingCleanups">>,
+  departingRecord?: TelegramTopicTargetRecord,
+): NonNullable<ThreadReconciler.ThreadReconciliationApplyPorts["isCleanupTargetProtected"]> {
+  const records = store.list();
+  const reservations = store.listReservations?.() ?? [];
+  const provisions = store.listPendingProvisions?.() ?? [];
+  const intents = store.listPendingCleanups?.() ?? [];
+  // Persistence may reconstruct keys in another order and omit undefined
+  // optional fields; neither changes the authority represented by a snapshot.
+  const sameSnapshot = (left: unknown, right: unknown): boolean =>
+    isDeepStrictEqual(JSON.parse(JSON.stringify(left)), JSON.parse(JSON.stringify(right)));
+  return (target, action) => {
+    for (const record of store.list()) {
+      if (!targetMatches(record.target, target)) continue;
+      // A persisted shutdown intent may retire only its original pre-intent
+      // binding. Registration/rebinding after that intent supersedes it.
+      const intent = action.kind === "close-delete-graceful-shutdown-topic"
+        ? intents.find((candidate) => candidate.id === action.cleanupIntentId && candidate.runtimeGeneration === action.runtimeGeneration)
+        : undefined;
+      const expectedDeparting = departingRecord ?? (intent && records.find((candidate) =>
+        candidate.instanceId === intent.instanceId && targetMatches(candidate.target, intent.target) &&
+        candidate.updatedAtMs <= intent.requestedAtMs));
+      if (expectedDeparting && "instanceId" in action &&
+        (action.kind === "close-delete-previous-leader-topic" || action.instanceId === expectedDeparting.instanceId) &&
+        sameSnapshot(record, expectedDeparting)) {
+        if (action.kind === "close-delete-previous-leader-topic" || action.kind === "close-stale-replaced-topic") continue;
+        if (action.kind === "close-delete-graceful-shutdown-topic" &&
+          store.listPendingCleanups?.().some((intent) => intent.id === action.cleanupIntentId &&
+            intent.instanceId === action.instanceId && intent.runtimeGeneration === action.runtimeGeneration &&
+            targetMatches(intent.target, target))) continue;
+      }
+      if (record.status === "active" || record.status === "starting" || record.status === "pending" || record.status === "probe-required") return true;
+    }
+    for (const reservation of store.listReservations?.() ?? []) {
+      if (!targetMatches(reservation.target, target)) continue;
+      if (action.kind !== "close-delete-reserved-topic" || !reservations.some((initial) => sameSnapshot(initial, reservation))) return true;
+    }
+    for (const provision of store.listPendingProvisions?.() ?? []) {
+      if (!provision.target || !targetMatches(provision.target, target)) continue;
+      if (action.kind !== "close-delete-expired-pending-provision-topic" || provision.id !== action.pendingProvisionId ||
+        !provisions.some((initial) => sameSnapshot(initial, provision))) return true;
+    }
+    return false;
+  };
+}
+
 export interface TelegramTopicTargetStoreOptions {
   path: string | (() => string);
   getNowMs?: () => number;
@@ -1230,7 +1283,11 @@ export function createTelegramTopicTargetStore(
       loaded = true;
       return;
     }
+    const revision = mutationRevision;
     const content = await readFile(path, "utf8");
+    // A read begun before a local mutation must not replace the newly admitted
+    // binding/cleanup state with its older disk snapshot.
+    if (mutationRevision !== revision || getPath() !== path) return;
     const rawFile: unknown = JSON.parse(content);
     const file = parseTopicTargetFile(rawFile);
     followerRecoveryHints = parseFollowerRecoveryHints(rawFile);
@@ -1293,25 +1350,20 @@ export function createTelegramTopicTargetStore(
     mutationRevision += 1;
   };
 
-  return {
-    async load() {
-      if (dirty) return;
-      await loadFromDisk();
-    },
-    refresh() {
-      const refresh = persistQueue.then(loadFromDisk);
-      persistQueue = refresh.catch(() => undefined);
-      return refresh;
-    },
-    persist() {
+  const persistSnapshot = (invalidation?: {
+    target: TelegramTarget;
+    isCurrent: () => boolean;
+    lastSyncError: string;
+  }): Promise<boolean> => {
       const persist = persistQueue.then(async () => {
         const path = getPath();
         if (loadedPath !== path && !dirty) resetForPath(path);
         if (options.canPersist && !options.canPersist()) {
-          await loadFromDisk();
-          return;
+          if (!invalidation) await loadFromDisk();
+          return false;
         }
         if (!dirty || !loaded) await loadFromDisk();
+        if (invalidation && !invalidation.isCurrent()) return false;
         await mkdir(dirname(path), { recursive: true });
         const tempPath = `${path}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
         const nowMs = getNowMs();
@@ -1359,6 +1411,21 @@ export function createTelegramTopicTargetStore(
             return serialized;
           }),
         };
+        if (invalidation) {
+          const record = file.threads.find((record) => targetMatches(record.target, invalidation.target));
+          if (!record) return false;
+          file.threads = file.threads.filter((candidate) => candidate !== record);
+          file.syncObservations = file.syncObservations.filter((observation) => !targetMatches(observation.target, record.target));
+          file.syncObservations.push({
+            target: { ...record.target },
+            syncStatus: "deleted",
+            observedAtMs: nowMs,
+            ...(record.instanceId ? { instanceId: record.instanceId } : {}),
+            ...(record.slot ? { slot: record.slot } : {}),
+            lastSyncError: invalidation.lastSyncError,
+            lastReconcileAction: "mark-stale",
+          });
+        }
         let persistedSemanticSnapshot: string | undefined;
         try {
           persistedSemanticSnapshot = serializeTelegramStateSemanticSnapshot(
@@ -1375,7 +1442,7 @@ export function createTelegramTopicTargetStore(
         ) {
           loaded = true;
           dirty = false;
-          return;
+          return true;
         }
         await writeFile(tempPath, `${JSON.stringify(file, null, 2)}\n`, {
           encoding: "utf8",
@@ -1383,6 +1450,25 @@ export function createTelegramTopicTargetStore(
         });
         await chmod(tempPath, 0o600);
         try {
+          if (invalidation) {
+            let applied = false;
+            const commit = () => {
+              if (getPath() !== path || mutationRevision !== persistedRevision ||
+                statusRevision !== persistedStatusRevision || !invalidation.isCurrent()) return;
+              // Fence and rename share one synchronous commit boundary. No stale
+              // invalidation enters the live projection before durable commit.
+              renameSync(tempPath, path);
+              records = new Map(Array.from(records).filter(([, record]) => !targetMatches(record.target, invalidation.target)));
+              syncObservations = file.syncObservations;
+              mutationRevision += 1;
+              dirty = false;
+              applied = true;
+            };
+            if (options.commitPersist) options.commitPersist(commit);
+            else if (!options.canPersist || options.canPersist()) commit();
+            if (!applied) await unlink(tempPath).catch(() => undefined);
+            return applied;
+          }
           if (options.commitPersist) {
             const committed = options.commitPersist(() => {
               renameSync(tempPath, path);
@@ -1404,9 +1490,27 @@ export function createTelegramTopicTargetStore(
         }
         loaded = true;
         if (mutationRevision === persistedRevision) dirty = false;
+        return true;
       });
-      persistQueue = persist.catch(() => undefined);
+      persistQueue = persist.then(() => undefined, () => undefined);
       return persist;
+  };
+
+  return {
+    async load() {
+      if (dirty) return;
+      await loadFromDisk();
+    },
+    refresh() {
+      const refresh = persistQueue.then(loadFromDisk);
+      persistQueue = refresh.catch(() => undefined);
+      return refresh;
+    },
+    async persist() {
+      await persistSnapshot();
+    },
+    invalidateTarget(target, isCurrent, lastSyncError) {
+      return persistSnapshot({ target, isCurrent, lastSyncError });
     },
     list() {
       return Array.from(records.values()).map(cloneRecord);
@@ -2100,6 +2204,7 @@ export async function provisionOwnBusTopic(
   if (typeof chatId !== "number") return undefined;
   await deps.store.load();
   const reservationCleanupPorts = {
+    isCleanupTargetProtected: createTelegramCleanupTargetProtection(deps.store),
     callApi: deps.callApi,
     markStaleByTarget: (
       target: TelegramTarget & { threadId: number },
@@ -2253,9 +2358,11 @@ export async function provisionOwnBusTopic(
       continue;
     }
     const previousLeaderCleanupStartedAtMs = Date.now();
+    const isCleanupTargetProtected = createTelegramCleanupTargetProtection(deps.store, record);
     const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(
       { actions: [action] },
       {
+        isCleanupTargetProtected,
         callApi: deps.callApi,
         markStaleByTarget: (target, syncStatus, lastSyncError) =>
           deps.store.markStaleByTarget(target, syncStatus, lastSyncError),
@@ -2304,6 +2411,7 @@ export async function provisionOwnBusTopic(
         "Previous Telegram leader topic deletion was not confirmed.",
       );
     }
+    if (isCleanupTargetProtected(action.target, action)) continue;
     deps.store.markStaleByTarget(record.target);
     deps.store.reserveThread({
       target: record.target,

package/package.json

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

package/skills/generated-control-surface/SKILL.md

@@ -40,7 +40,9 @@ A surface is an ordered ragged sequence of rows. Each button carries:
 
 - A short, distinct label.
 - The smallest self-contained next-request prompt.
-- Optional presentation state supported by the transport.
+- Optional presentation state supported by the transport, including disabled controls when their visible unavailability helps explain current state.
+
+A disabled control is not an action: it needs no prompt or selected style and must not enqueue a prompt or invoke a bound method. Prefer a meaningful label; omit it only for an intentional blank cell in a spatial layout, never as decorative padding. Preserve its label and position when that makes a changing surface easier to understand; otherwise omit irrelevant controls. Explain non-obvious unavailability without relying on color alone. Retain at least one useful enabled action, such as refresh or navigation. Derive disabled state from the same evidence as the view; an old enabled control still requires current domain validation. Use the transport owner's disabled encoding rather than a dummy prompt or no-op callback.
 
 Prompts must name any target, operation, constraint, or freshness identity whose omission could change the action. Reuse visible context only when it remains unambiguous under delayed or reordered clicks. Never encode volatile output that should be freshly inspected.
 
@@ -57,7 +59,7 @@ Every generated human-readable action label must use `emoji + space + text`; emo
 
 For complex grids, navigation collections, or stateful repeated clicks, read [`references/layout-and-state.md`](./references/layout-and-state.md).
 
-Serialize the resulting rows with the active transport contract. This Skill owns admission and composition, not transport syntax.
+Place a control group beside the section it governs when the transport supports in-body blocks; use a footer for whole-answer actions. Placement must not change the matrix or action semantics. Serialize the resulting rows with the active transport contract. This Skill owns admission and composition, not transport syntax.
 
 ## Safety
 

package/skills/generated-control-surface/references/layout-and-state.md

@@ -10,7 +10,7 @@ Model the surface as ordered ragged rows, not a rectangle to fill. Infer indepen
 - A horizontal pair is earned only by genuine peers with unmistakably compact labels and no plausible wrapping or truncation.
 - Three through five columns are for short symbols, coordinates, glyphs, or codes whose position carries meaning.
 - Six through eight columns require single-glyph or similarly minimal position-bearing labels. Never exceed eight columns on a phone surface.
-- Vary row width intentionally; never pad with empty, duplicate, or no-op controls.
+- Vary row width intentionally; never pad for symmetry with empty, duplicate, or no-op controls. A blank disabled cell is appropriate only when it represents a real unavailable position in a spatial grid.
 - Preserve reading order: orientation/navigation, primary content or choices, secondary controls, then separated destructive actions.
 - Rectangular grids require genuine spatial or coordinate correspondence. Vertical continuity may justify many rows; non-spatial button walls should paginate or group.
 
@@ -32,4 +32,6 @@ Keep trivial state in conversation. Persist a small human-auditable artifact whe
 
 Evaluate repeated clicks against current state, not stale button appearance. Preserve tap-ahead when the transport queues each click independently. In source-then-destination interaction, retain the source selection without duplicating the whole surface; regenerate after a completed transition, invalid input, or evidence that the transport cannot preserve the intermediate view.
 
-Omit unavailable controls when layout does not matter. Preserve occupied or selected cells when spatial topology depends on stable coordinates.
+Omit unavailable controls when layout does not matter. Preserve occupied or selected cells when spatial topology depends on stable coordinates, using the transport's disabled state without a fabricated prompt. Keep a useful enabled navigation or inspection action.
+
+Place each control group beside the content it governs when in-body blocks are supported; keep global navigation and whole-view actions in the footer. Do not duplicate one action in both positions merely for visibility. Row topology and current-state validation stay the same across compact and named representations and across placements; renderer limits and selection feedback belong to the transport.

package/skills/generative-apps/SKILL.md

@@ -29,9 +29,9 @@ Generated Control Surface → current context → model → one ephemeral surfac
 Generative App             → model → reusable program → many evolving surfaces
 ```
 
-Both Skills use the same logical button matrix and `label + prompt` interaction model. The Telegram runtime owns its full JSON/CML notation and callback routing; this Skill owns reusable program judgment, while `generated-control-surface` owns ephemeral agent-authored composition. Shared rendering needs no third button Skill and does not collapse those responsibilities.
+Both Skills use the same logical button matrix and `label + prompt` interaction model. An app may place groups beside their related content using the transport's in-body button blocks or keep whole-view controls in the footer; placement does not change binding, disabled state, or method authority. The Telegram runtime owns its full JSON/CML notation and callback routing; this Skill owns reusable program judgment, while `generated-control-surface` owns ephemeral agent-authored composition. Shared rendering needs no third button Skill and does not collapse those responsibilities.
 
-An app may mix deterministic `app::method` controls and ordinary prompts in one view. Compile only the stable transitions that benefit from inference bypass; keep explanation, interpretation, teaching, and adaptation on the model-mediated plane. When no reusable state or deterministic loop earns a script, load and use `generated-control-surface` instead.
+An app may mix deterministic `app::method` controls and ordinary prompts in one view, including one control group. Compact and named cells may coexist under the shared transport grammar; neither representation nor placement creates another action plane. Compile only the stable transitions that benefit from inference bypass; keep explanation, interpretation, teaching, and adaptation on the model-mediated plane. When no reusable state or deterministic loop earns a script, load and use `generated-control-surface` instead.
 
 The `generated` / `generative` distinction is intentional. Do not rename `generated-control-surface` to a competing generative term.
 
@@ -76,7 +76,7 @@ Another capability remains the authoritative real owner. The app stores validate
 1. Identify the repeated feedback loop, real state owner, and actions that are truly deterministic.
 2. Choose one stable lowercase app and one self-contained `<app>.mjs` source outside the managed installation directory.
 3. Keep `init` and every exported method small, named, bounded, shell-free, and capability-specific.
-4. Render one complete next view after each action.
+4. Render one complete next view after each action. Derive disabled controls from current state using the shared transport contract; visible disabled controls neither invoke methods nor enqueue prompts. Revalidate domain preconditions when an enabled control is invoked, because previously rendered views may be stale.
 5. Mix action planes intentionally:
 
 ```text
@@ -107,6 +107,7 @@ Before presenting an app as working:
 - Inspect the installed initial view and persisted bounded state.
 - Exercise at least one real bound action and prove it bypasses Pi queue/model admission.
 - Exercise at least one ordinary prompt when the app intentionally uses the model plane.
+- Verify the placements actually used by the app and prove disabled cells invoke nothing. A successful ordinary prompt-button smoke is not evidence of app-method dispatch or stale-revision rejection.
 - Verify replacement rejects stale buttons and failed initialization preserves the prior app.
 - For adapters, prove fresh external status and terminal mutation evidence.
 - Confirm failures are bounded, redacted, and do not silently render success.