@llblab/pi-telegram 0.51.5 → 0.52.0

package/lib/sections.ts

@@ -284,7 +284,7 @@ function buildTelegramSectionCallbackContext(
 // --- GlobalThis Bridge ---
 
 /** @internal */
-export function setGlobalTelegramSectionRegistry(
+function setGlobalTelegramSectionRegistry(
   registry: TelegramSectionRegistry,
 ): void {
   (globalThis as Record<string, unknown>)[SECTION_REGISTRY_KEY] = registry;

package/lib/status.ts

@@ -1,9 +1,41 @@
 /**
  * Telegram status rendering helpers
  * Zones: telegram ui, pi agent diagnostics, tui
- * Builds usage, cost, and context summaries for the interactive Telegram status view
+ * Owns status summaries, redacted diagnostics, projection lifecycle and compact connection-failure copy
+ * Excludes canonical state, transport admission and filesystem policy
  */
 
+import { isDeepStrictEqual } from "node:util";
+
+/** UI copy is allowlisted; raw exception text belongs only in redacted diagnostics. */
+export function formatTelegramConnectionFailure(error: unknown): string {
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  const status = error && typeof error === "object" && "status" in error ? error.status : undefined;
+  const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+  if (status === 401) return "Telegram token rejected. Run /telegram-setup.";
+  if (status === 403) return "Telegram access denied. Check /telegram-status --debug.";
+  if ((typeof code === "string" && ["ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND", "ECONNRESET"].includes(code)) ||
+      /network unavailable|fetch failed/i.test(message)) {
+    return "Telegram network unavailable. Retry /telegram-connect.";
+  }
+  if (/Workspace slots?.*(?:unavailable|exhausted)|no free.*slot/i.test(message)) {
+    return "No Telegram slot available. Check /telegram-status --debug.";
+  }
+  if (code === "incompatible-protocol" || /protocol.*(?:incompatible|mismatch)|incompatible.*protocol/i.test(message)) {
+    return "Telegram instances are incompatible. Update them together.";
+  }
+  if (/unsupported.*(?:journal|version)|(?:journal|version).*unsupported/i.test(message)) {
+    return "Telegram state version unsupported. Use a compatible runtime.";
+  }
+  if (/follower registration failed|active in another Pi instance/i.test(message)) {
+    return "Telegram leader is active but unavailable. Check /telegram-status --debug.";
+  }
+  if (/unfinished Thread creation does not match/i.test(message)) {
+    return "Telegram Thread creation is unresolved. Check /telegram-status --debug.";
+  }
+  return "Telegram connection failed. Check /telegram-status --debug.";
+}
+
 const TELEGRAM_STATUS_DEFAULT_PROFILE_NAME = "default";
 
 export type TelegramStatusQueueLane = "control" | "priority" | "default";
@@ -434,7 +466,7 @@ function truncateTelegramRuntimeEventText(
   return `${text.slice(0, maxLength).trimEnd()}… [truncated ${text.length - maxLength} chars]`;
 }
 
-export function redactTelegramRuntimeMessage(
+function redactTelegramRuntimeMessage(
   message: string,
   botToken: string | undefined,
 ): string {
@@ -550,7 +582,7 @@ export function registerTelegramStatusLineProvider(
   };
 }
 
-export function getTelegramStatusLineProviderResults(
+function getTelegramStatusLineProviderResults(
   ctx: TelegramStatusLineProviderContext,
 ): TelegramStatusLineProviderResult[] {
   const results: TelegramStatusLineProviderResult[] = [];
@@ -813,13 +845,19 @@ export function createTelegramRuntimeLogScope(input: {
   };
 }
 
-export function createTelegramStatusSnapshot(
-  state: TelegramBridgeStatusLineState,
-): {
+export interface TelegramStatusSnapshot {
   runtime: Record<string, unknown>;
   liveRoster: Record<string, unknown>;
   diagnostics: Record<string, unknown>;
-} {
+}
+export interface TelegramStoredRuntimeProjection extends TelegramStatusSnapshot {
+  version: 1;
+  source: "snapshot";
+  writtenAtMs: number;
+}
+export function createTelegramStatusSnapshot(
+  state: TelegramBridgeStatusLineState,
+): TelegramStatusSnapshot {
   return {
     runtime: {
       busRole: state.busRole,
@@ -840,7 +878,6 @@ export function createTelegramStatusSnapshot(
       ...(state.localBus ? { localBus: state.localBus } : {}),
       topicTargets: state.topicTargets ?? [],
       reservations: state.threadReservations ?? [],
-      syncObservations: state.topicSyncObservations ?? [],
     },
     diagnostics: {
       pendingDispatch: state.pendingDispatch,
@@ -854,17 +891,94 @@ export function createTelegramStatusSnapshot(
   };
 }
 
+function isRuntimeProjection(value: unknown): value is TelegramStoredRuntimeProjection {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return record.version === 1 && record.source === "snapshot" && Number.isSafeInteger(record.writtenAtMs) && (record.writtenAtMs as number) >= 0 &&
+    Object.keys(record).every(key => ["version", "source", "writtenAtMs", "runtime", "liveRoster", "diagnostics"].includes(key)) &&
+    ["runtime", "liveRoster", "diagnostics"].every(key => record[key] !== null && typeof record[key] === "object" && !Array.isArray(record[key]));
+}
+export interface TelegramRuntimeProjectionScope {
+  path: string;
+  profile: string;
+}
+export interface TelegramRuntimeProjectionStorage {
+  read: (scope: TelegramRuntimeProjectionScope) => unknown;
+  /** The adapter must enforce exact owner plus the supplied physical/logical scope in one transaction. */
+  publish: (
+    scope: TelegramRuntimeProjectionScope,
+    mutate: (current: unknown) => { value: unknown; changed: boolean },
+    isCurrent: () => boolean,
+  ) => boolean;
+}
+export interface TelegramRuntimeProjectionStoreOptions {
+  getPath: () => string;
+  getProfile: () => string | undefined;
+  /** Capture exact owner/context/session authority at submission, never renew it after the queued await. */
+  captureAuthority: () => (() => boolean) | undefined;
+  storage: TelegramRuntimeProjectionStorage;
+  getNowMs?: () => number;
+}
+/** Observational runtime storage only; Workspace, admission, transport, logs and recovery remain with their owners. */
+export function createTelegramRuntimeProjectionStore(options: TelegramRuntimeProjectionStoreOptions): {
+  read: () => TelegramStoredRuntimeProjection | undefined;
+  persist: (snapshot: TelegramStatusSnapshot) => Promise<boolean>;
+} {
+  let publicationQueue = Promise.resolve();
+  const { getPath, getProfile: readProfile, captureAuthority } = options;
+  const { read, publish } = options.storage;
+  const getNowMs = options.getNowMs ?? Date.now;
+  const getProfile = (): string => readProfile() || TELEGRAM_STATUS_DEFAULT_PROFILE_NAME;
+  return {
+    read() {
+      try {
+        const path = getPath(), profile = getProfile(), value = read({ path, profile });
+        return getPath() === path && getProfile() === profile && isRuntimeProjection(value) ? value : undefined;
+      } catch { return undefined; }
+    },
+    async persist(snapshot) {
+      const path = getPath(), profile = getProfile(), authority = captureAuthority();
+      if (!authority) return false;
+      // Freeze wire content at submission, but do not duplicate the event log in persistent runtime state.
+      const semantic = JSON.parse(JSON.stringify({ version: 1, source: "snapshot", runtime: snapshot.runtime,
+        liveRoster: snapshot.liveRoster, diagnostics: snapshot.diagnostics })) as Omit<TelegramStoredRuntimeProjection, "writtenAtMs">;
+      if (!isRuntimeProjection({ ...semantic, writtenAtMs: 0 })) throw new Error("Telegram runtime projection is malformed.");
+      delete semantic.diagnostics.recentRuntimeEvents;
+      const isCurrent = (): boolean => getPath() === path && getProfile() === profile && authority() === true;
+      const publication = publicationQueue.then(() => {
+        if (!isCurrent()) return false;
+        return publish({ path, profile }, current => {
+          if (isRuntimeProjection(current)) {
+            const { writtenAtMs: _writtenAtMs, ...existing } = current;
+            if (isDeepStrictEqual(existing, semantic)) return { value: current, changed: false };
+          }
+          const writtenAtMs = getNowMs();
+          if (!Number.isSafeInteger(writtenAtMs) || writtenAtMs < 0) throw new Error("Telegram runtime projection timestamp is invalid.");
+          return { value: { ...semantic, writtenAtMs }, changed: true };
+        }, isCurrent) === true;
+      });
+      publicationQueue = publication.then(() => undefined, () => undefined);
+      return publication;
+    },
+  };
+}
+
 const TELEGRAM_DIAGNOSTICS_SNAPSHOT_COALESCE_MS = 100;
 
 export function createTelegramRuntimeDiagnosticsSnapshotScheduler(deps: {
-  persistSnapshot: () => Promise<void>;
+  persistSnapshot: (isCurrent: () => boolean) => Promise<void>;
   recordError: (error: unknown) => void;
-  setTimer?: (callback: () => void, ms: number) => { unref?: () => void };
-}): () => void {
+  captureScope?: () => (() => boolean) | undefined;
+  setTimer?: (callback: () => void, ms: number) => { unref?: () => void } | number;
+  clearTimer?: (timer: { unref?: () => void } | number) => void;
+}): (() => void) & { resume(): void; suspend(): Promise<void> } {
   const setTimer = deps.setTimer ?? setTimeout;
-  let timer: { unref?: () => void } | number | undefined;
+  const clearTimer = deps.clearTimer ?? ((handle) => clearTimeout(handle as ReturnType<typeof setTimeout>));
+  let generation = 0;
+  let enabled = true;
+  let timer: { token: object; handle: { unref?: () => void } | number } | undefined;
   let persistPromise: Promise<void> | undefined;
-  let pending = false;
+  let pending: (() => boolean) | undefined;
   const recordError = (error: unknown): void => {
     try {
       deps.recordError(error);
@@ -872,30 +986,72 @@ export function createTelegramRuntimeDiagnosticsSnapshotScheduler(deps: {
       // Snapshot diagnostics cannot create an unhandled scheduler rejection.
     }
   };
-  const request = (): void => {
-    if (timer || persistPromise) {
-      pending = true;
-      return;
+  const cancelTimer = (): void => {
+    const previous = timer;
+    timer = undefined;
+    if (previous) {
+      try { clearTimer(previous.handle); } catch (error) { recordError(error); }
     }
-    timer = setTimer(() => {
+  };
+  const capture = (): (() => boolean) | undefined => {
+    if (!enabled) return undefined;
+    const expectedGeneration = generation;
+    let scope: (() => boolean) | undefined;
+    try { scope = deps.captureScope ? deps.captureScope() : () => true; }
+    catch (error) { recordError(error); return undefined; }
+    if (!scope) return undefined;
+    return () => {
+      if (!enabled || generation !== expectedGeneration) return false;
+      try { return scope!(); } catch (error) { recordError(error); return false; }
+    };
+  };
+  const arm = (): void => {
+    if (timer || persistPromise || !pending) return;
+    const authority = pending;
+    if (!authority()) { pending = undefined; return; }
+    const token = {};
+    const handle = setTimer(() => {
+      if (timer?.token !== token) return;
       timer = undefined;
+      const publicationAuthority = pending;
+      pending = undefined;
+      if (!authority() || !publicationAuthority?.()) return;
       let tracked: Promise<void>;
       tracked = Promise.resolve()
-        .then(deps.persistSnapshot)
+        .then(() => publicationAuthority() ? deps.persistSnapshot(publicationAuthority) : undefined)
         .catch(recordError)
         .finally(() => {
           if (persistPromise !== tracked) return;
           persistPromise = undefined;
-          if (pending) {
-            pending = false;
-            request();
-          }
+          // Only an explicitly captured new request can arm a successor publication.
+          arm();
         });
       persistPromise = tracked;
     }, TELEGRAM_DIAGNOSTICS_SNAPSHOT_COALESCE_MS);
-    if (typeof timer !== "number") timer?.unref?.();
+    timer = { token, handle };
+    if (typeof handle !== "number") handle.unref?.();
+  };
+  const request = (): void => {
+    const authority = capture();
+    if (!authority) return;
+    pending = authority;
+    arm();
   };
-  return request;
+  return Object.assign(request, {
+    resume() {
+      generation += 1;
+      cancelTimer();
+      pending = undefined;
+      enabled = true;
+    },
+    suspend() {
+      enabled = false;
+      generation += 1;
+      cancelTimer();
+      pending = undefined;
+      return persistPromise ?? Promise.resolve();
+    },
+  });
 }
 
 export function getTelegramStatusBarProcessingStatus(state: {
@@ -1353,16 +1509,9 @@ function buildTelegramBridgeCompactStatusLines(
     : state.activeSourceMessageIds?.length
       ? "active"
       : "idle";
-  const diagnosticsProfileName =
-    state.activeProfileName === TELEGRAM_STATUS_DEFAULT_PROFILE_NAME
-      ? undefined
-      : state.activeProfileName;
-  const profileSuffix = diagnosticsProfileName
-    ? `.${diagnosticsProfileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`
-    : "";
   const diagnosticsPaths = state.diagnosticPaths ?? {
-    state: `~/.pi/agent/tmp/telegram/state${profileSuffix}.json`,
-    logs: `~/.pi/agent/tmp/telegram/logs${profileSuffix}.jsonl`,
+    state: "~/.pi/agent/tmp/pi-telegram/state.json",
+    logs: "~/.pi/agent/tmp/pi-telegram/logs.jsonl",
   };
   return [
     "connection:",
@@ -1414,7 +1563,7 @@ export function buildTelegramBridgeStatusLines(
   return buildTelegramBridgeCompactStatusLines(state);
 }
 
-export function buildTelegramBridgeDiagnosticStatusLines(
+function buildTelegramBridgeDiagnosticStatusLines(
   state: TelegramBridgeStatusLineState,
 ): string[] {
   const controlQueueCount = state.queuedItems.filter(
@@ -1591,7 +1740,7 @@ function buildTelegramStatusRoleSuffix(
   return ` @${state.busRole}`;
 }
 
-export function buildStatusHtml(
+function buildStatusHtml(
   ctx: TelegramStatusContext,
   activeModel: TelegramStatusActiveModel | undefined,
   bridgeStatus?: TelegramBridgeStatusLineState,

package/lib/sync.ts

@@ -8,6 +8,7 @@ import { getTelegramApiErrorRequestTarget, isTelegramStaleTargetHttpError } from
 import { getTelegramTargetKey, type TelegramTarget } from "./target.ts";
 import * as ThreadReconciler from "./thread-reconciler.ts";
 import { TelegramWorkspaceSlotUnavailableError } from "./workspace-slots.ts";
+import { normalizeTelegramWorkspacePath } from "./workspace-identity.ts";
 import {
   createTelegramWorkspaceAdmissionOperationId,
   runWithTelegramWorkspaceAdmissionsAsync,
@@ -20,7 +21,6 @@ import {
   getTelegramThreadOwnerKey,
   isSameTelegramProcessInstance,
   isTelegramTopicTargetStaleError,
-  normalizeTelegramWorkspacePath,
   provisionOwnBusTopic,
   type TelegramOwnTopicProvisionResult,
   type TelegramTopicTargetStore,
@@ -179,7 +179,7 @@ export interface TelegramManualThreadDisconnectDeps<TSyncState> {
   getNowMs?: () => number;
 }
 
-export function markTelegramConfigSyncChange<
+function markTelegramConfigSyncChange<
   TSyncState extends TelegramSyncState,
 >(state: TSyncState, action: string, options?: { nowMs?: number }): TSyncState {
   const nowMs = options?.nowMs ?? Date.now();
@@ -245,7 +245,7 @@ export interface TelegramSessionRestartThreadCleanupDeps<
   suspendPolling: () => Promise<void>;
 }
 
-export function createTelegramSessionRestartThreadCleanupHandler<
+function createTelegramSessionRestartThreadCleanupHandler<
   TSyncState extends TelegramSyncState,
 >(
   deps: TelegramSessionRestartThreadCleanupDeps<TSyncState>,
@@ -773,6 +773,7 @@ export async function ensureTelegramLeaderThreadBinding(
     : undefined;
   const legacyWorkspaceBinding =
     workspaceIdentity?.instanceSlot === "a" &&
+    deps.sessionId === undefined &&
     !persistedWorkspaceBinding &&
     typeof legacyLeaderRecord?.target.threadId === "number"
       ? {
@@ -885,10 +886,9 @@ export async function ensureTelegramLeaderThreadBinding(
       (record.status === "active" || record.status === "starting")
     );
   });
-  // Short-circuit: when the instance already has an active thread and we are not
-  // force-freshing, reuse it without re-provisioning. A thread belongs to the
-  // live instance binding, not to one transient Pi session lifecycle.
-  if (!deps.forceFreshUnnamed && priorTargets.length > 0) {
+  // Legacy callers without session identity may reuse the active instance target.
+  // Session-aware callers must resolve their exact Workspace binding instead.
+  if (deps.sessionId === undefined && !deps.forceFreshUnnamed && priorTargets.length > 0) {
     const record = priorTargets[0];
     deps.recordEvent(
       "telegram",
@@ -997,7 +997,7 @@ export async function ensureTelegramLeaderThreadBinding(
   }
 }
 
-export const TELEGRAM_SYNC_SLICE_TARGET_BINDINGS = "target-bindings";
+const TELEGRAM_SYNC_SLICE_TARGET_BINDINGS = "target-bindings";
 
 export const TELEGRAM_SYNC_SLICES = [
   "bot-identity",

package/lib/telegram-api.ts

@@ -8,14 +8,15 @@
 
 import { randomUUID } from "node:crypto";
 import { createWriteStream, openAsBlob } from "node:fs";
-import { mkdir, readdir, stat, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { request as requestHttps } from "node:https";
 import { join } from "node:path";
-import { resolveTelegramTempDir } from "./paths.ts";
+import type { TelegramAttachmentSource } from "./media.ts";
+import { resolveTelegramAttachmentsDir } from "./paths.ts";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 
-export const TELEGRAM_API_BASE = "https://api.telegram.org";
+const TELEGRAM_API_BASE = "https://api.telegram.org";
 
 export const TELEGRAM_FILE_MAX_BYTES = 50 * 1024 * 1024;
 
@@ -34,12 +35,10 @@ export function getTelegramInboundFileByteLimitFromEnv(
 }
 
 function getTelegramApiTempDir(): string {
-  return resolveTelegramTempDir();
+  return resolveTelegramAttachmentsDir();
 }
 const TELEGRAM_TEMP_FILE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const activeTelegramApiWorkspaceAdmissionOperationIds = new Set<string>();
-const TELEGRAM_TEMP_SCRATCH_FILE_PATTERN =
-  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}-/u;
 const TELEGRAM_INBOUND_FILE_MAX_BYTES = getTelegramInboundFileByteLimitFromEnv(
   process.env,
   ["PI_TELEGRAM_INBOUND_FILE_MAX_BYTES", "TELEGRAM_MAX_FILE_SIZE_BYTES"],
@@ -750,6 +749,8 @@ export interface TelegramBridgeApiRuntimeDeps {
   tempDir: string;
   maxFileSizeBytes: number;
   tempFileMaxAgeMs: number;
+  /** Bot `@username` (or numeric id) naming private-chat attachments. */
+  getBotScope?: () => string | undefined;
   recordRuntimeEvent: (
     kind: "api" | "multipart" | "download",
     error: unknown,
@@ -774,7 +775,11 @@ export interface TelegramBridgeApiRuntime {
     fileName: string,
     options?: TelegramApiCallOptions,
   ) => Promise<TResponse>;
-  downloadFile: (fileId: string, suggestedName: string) => Promise<string>;
+  downloadFile: (
+    fileId: string,
+    suggestedName: string,
+    source?: TelegramAttachmentSource,
+  ) => Promise<string>;
   deleteWebhook: (signal?: AbortSignal) => Promise<boolean>;
   getUpdates: (
     body: Record<string, unknown>,
@@ -853,6 +858,28 @@ function sanitizeFileName(name: string): string {
   return name.replace(/[^a-zA-Z0-9._-]+/g, "_");
 }
 
+/** Names follow `<kind>-<scope>-<messageId>[-<index>][-<name>|.<ext>]`. */
+/**
+ * `scope` is the bot `@username` (id fallback) in a private chat and the public chat `@username` (id fallback) elsewhere.
+ * A negative chat id loses its sign, so the name never contains two adjacent dashes.
+ */
+export function createTelegramAttachmentFileName(
+  source: TelegramAttachmentSource,
+  generatedName: string,
+  botScope?: string,
+): string {
+  const chat = source.chat;
+  const clean = (value: string): string => sanitizeFileName(value.replace(/^@/u, "")).replace(/^[-.]+/u, "");
+  const scope = source.scope ? clean(source.scope) : chat?.type === "private" || !chat
+    ? botScope ? clean(botScope) : chat ? String(Math.abs(chat.id)) : ""
+    : chat.username ? clean(chat.username) : String(Math.abs(chat.id));
+  const dot = generatedName.lastIndexOf(".");
+  const extension = dot > 0 ? sanitizeFileName(generatedName.slice(dot)) : "";
+  const tail = source.userFileName ? `-${clean(source.userFileName)}` : extension;
+  return [sanitizeFileName(source.kind), scope, String(source.messageId)].filter(Boolean).join("-") +
+    (source.index !== undefined ? `-${source.index}` : "") + tail;
+}
+
 class TelegramApiMalformedSuccessError extends Error {
   constructor(method: string, detail: string) {
     super(`Telegram API ${method} ${detail}`);
@@ -1490,9 +1517,8 @@ export async function cleanupTelegramTempFiles(
     return 0;
   }
   for (const entry of entries) {
-    if (!entry.isFile() || !TELEGRAM_TEMP_SCRATCH_FILE_PATTERN.test(entry.name)) {
-      continue;
-    }
+    // The directory holds only attachment scratch files, so age alone decides.
+    if (!entry.isFile()) continue;
     const path = join(tempDir, entry.name);
     try {
       const stats = await stat(path);
@@ -1643,10 +1669,9 @@ export async function downloadTelegramFile(
   );
   assertTelegramFileSizeWithinLimit(file.file_size, options?.maxFileSizeBytes);
   await mkdir(tempDir, { recursive: true, mode: 0o700 });
-  const targetPath = join(
-    tempDir,
-    `${randomUUID()}-${sanitizeFileName(suggestedName)}`,
-  );
+  // Names carry scope and message id, so the same message maps to the same path; publish by rename.
+  const targetPath = join(tempDir, sanitizeFileName(suggestedName));
+  const partPath = `${targetPath}.${randomUUID()}.part`;
   const response = await callTelegramTransportRequest((family) =>
     telegramFetch(
       `${TELEGRAM_API_BASE}/file/bot${configuredBotToken}/${file.file_path}`,
@@ -1665,11 +1690,12 @@ export async function downloadTelegramFile(
   try {
     await writeTelegramDownloadResponse(
       response,
-      targetPath,
+      partPath,
       options?.maxFileSizeBytes,
     );
+    await rename(partPath, targetPath);
   } catch (error) {
-    await removeTelegramPartialDownload(targetPath);
+    await removeTelegramPartialDownload(partPath);
     throw error;
   }
   return targetPath;
@@ -1700,21 +1726,6 @@ export async function answerTelegramCallbackQuery(
   }
 }
 
-export async function deleteTelegramMessage(
-  botToken: string | undefined,
-  chatId: number,
-  messageId: number,
-): Promise<void> {
-  try {
-    await callTelegram<boolean>(botToken, "deleteMessage", {
-      chat_id: chatId,
-      message_id: messageId,
-    });
-  } catch {
-    // ignore
-  }
-}
-
 export function createTelegramChatActionSender<TAction extends string>(
   sendChatAction: (
     chatId: number,
@@ -1802,6 +1813,7 @@ export type TelegramWorkspaceThreadDeletionTransport = (
 
 export function createDefaultTelegramBridgeApiRuntime(deps: {
   getBotToken: () => string | undefined;
+  getBotScope?: () => string | undefined;
   recordRuntimeEvent: TelegramBridgeApiRuntimeDeps["recordRuntimeEvent"];
   captureRequestErrorHandler?: TelegramBridgeApiRuntimeDeps["captureRequestErrorHandler"];
   targetActivity?: TelegramApiTargetActivityRuntime;
@@ -1831,6 +1843,7 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
     tempDir: getTelegramApiTempDir(),
     maxFileSizeBytes: TELEGRAM_INBOUND_FILE_MAX_BYTES,
     tempFileMaxAgeMs: TELEGRAM_TEMP_FILE_MAX_AGE_MS,
+    ...(deps.getBotScope ? { getBotScope: deps.getBotScope } : {}),
     recordRuntimeEvent: deps.recordRuntimeEvent,
     captureRequestErrorHandler: deps.captureRequestErrorHandler,
   });
@@ -2040,11 +2053,13 @@ export function createTelegramBridgeApiRuntime(
      * Downloads a file from the Telegram servers into the local temp directory.
      * Used for inbound voice messages, photos, documents, etc.
      */
-    downloadFile: async (fileId, suggestedName) => {
+    downloadFile: async (fileId, suggestedName, source) => {
       try {
         return await deps.client.downloadFile(
           fileId,
-          suggestedName,
+          source
+            ? createTelegramAttachmentFileName(source, suggestedName, deps.getBotScope?.())
+            : suggestedName,
           deps.tempDir,
           {
             maxFileSizeBytes: deps.maxFileSizeBytes,

package/lib/thread-cleanup-manager.ts

@@ -10,6 +10,12 @@ import { dirname } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 
 import { renameTelegramPathWithRetry, withTelegramFileTransaction } from "./locks.ts";
+import { getTelegramJournalPublicationPaths } from "./paths.ts";
+import {
+  isWireRecord as isObject,
+  hasOnlyWireKeys as onlyKeys,
+  isNonNegativeWireInteger as safeTime,
+} from "./wire.ts";
 import type { TelegramWorkspaceDeletionPermit,
   TelegramWorkspaceDestructiveFence,
   TelegramWorkspaceRetirementFence } from "./workspace-admission.ts";
@@ -247,15 +253,6 @@ export interface TelegramThreadCleanupWorkStore {
   list(): TelegramThreadCleanupWorkSet[];
 }
 
-function isObject(value: unknown): value is Record<string, unknown> {
-  return !!value && typeof value === "object" && !Array.isArray(value);
-}
-function onlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
-  const allowed = new Set(keys); return Object.keys(value).every(key => allowed.has(key));
-}
-function safeTime(value: unknown): value is number {
-  return Number.isSafeInteger(value) && (value as number) >= 0;
-}
 function validateWorkSet(value: unknown, profileName: string): TelegramThreadCleanupWorkSet {
   if (!isObject(value) || !onlyKeys(value, ["operationId", "createdAtMs", "entries"]) ||
       typeof value.operationId !== "string" || !value.operationId || !safeTime(value.createdAtMs) ||
@@ -311,11 +308,23 @@ function sameCandidates(left: readonly TelegramThreadCleanupCandidate[], right:
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
+function parseTelegramThreadCleanupWorkFile(value: unknown, profileName: string, tokenSha256: string): TelegramThreadCleanupWorkFile {
+  if (!isObject(value) || !onlyKeys(value, ["version", "profileName", "tokenSha256", "workSets"]) ||
+      value.version !== 1 || value.profileName !== profileName || value.tokenSha256 !== tokenSha256 || !Array.isArray(value.workSets))
+    throw new Error("Telegram Thread cleanup store identity or schema does not match.");
+  const workSets = value.workSets.map(workSet => validateWorkSet(workSet, profileName));
+  if (new Set(workSets.map(workSet => workSet.operationId)).size !== workSets.length)
+    throw new Error("Telegram Thread cleanup operation identity is ambiguous.");
+  return { version: 1, profileName, tokenSha256, workSets };
+}
+
 export function createTelegramThreadCleanupWorkStore(options: {
-  path: string; profileName: string; tokenSha256: string; maxWorkSets?: number;
+  path: string; runtimeDir?: string; profileName: string; tokenSha256: string; maxWorkSets?: number;
   maxBytes?: number; getNowMs?: () => number;
   onPublicationBoundary?: (boundary: "after-write-before-rename" | "after-rename") => void;
 }): TelegramThreadCleanupWorkStore {
+  options = { ...options };
+  const publicationPaths = getTelegramJournalPublicationPaths(options.path, options.runtimeDir);
   const maxWorkSets = options.maxWorkSets ?? 32;
   const maxBytes = options.maxBytes ?? 1024 * 1024;
   const now = options.getNowMs ?? Date.now;
@@ -344,21 +353,15 @@ export function createTelegramThreadCleanupWorkStore(options: {
           opened.mtimeNs !== before.mtimeNs) throw new Error("Telegram Thread cleanup store changed during inspection.");
       value = JSON.parse(readFileSync(fd, "utf8")) as unknown;
     } finally { closeSync(fd); }
-    if (!isObject(value) || !onlyKeys(value, ["version", "profileName", "tokenSha256", "workSets"]) ||
-        value.version !== 1 || value.profileName !== options.profileName ||
-        value.tokenSha256 !== options.tokenSha256 || !Array.isArray(value.workSets))
-      throw new Error("Telegram Thread cleanup store identity or schema does not match.");
-    const workSets = value.workSets.map(workSet => validateWorkSet(workSet, options.profileName));
-    if (new Set(workSets.map(workSet => workSet.operationId)).size !== workSets.length)
-      throw new Error("Telegram Thread cleanup operation identity is ambiguous.");
-    return { version: 1, profileName: options.profileName, tokenSha256: options.tokenSha256, workSets };
+    return parseTelegramThreadCleanupWorkFile(value, options.profileName, options.tokenSha256);
   };
   const publish = (file: TelegramThreadCleanupWorkFile): void => {
     if (file.workSets.length > maxWorkSets) throw new Error("Telegram Thread cleanup work-set capacity reached.");
     const serialized = `${JSON.stringify(file, null, 2)}\n`;
     if (Buffer.byteLength(serialized) > maxBytes) throw new Error("Telegram Thread cleanup byte capacity reached.");
-    const temporaryPath = `${options.path}.${process.pid}.${randomUUID()}.tmp`;
+    const temporaryPath = `${publicationPaths.temporaryBasePath}.${process.pid}.${randomUUID()}.tmp`;
     mkdirSync(dirname(options.path), { recursive: true, mode: 0o700 });
+    mkdirSync(dirname(temporaryPath), { recursive: true, mode: 0o700 });
     try {
       writeFileSync(temporaryPath, serialized, { mode: 0o600 });
       chmodSync(temporaryPath, 0o600);
@@ -370,7 +373,7 @@ export function createTelegramThreadCleanupWorkStore(options: {
     } finally { try { unlinkSync(temporaryPath); } catch { /* rename consumed it */ } }
   };
   const mutate = <T>(operation: (file: TelegramThreadCleanupWorkFile) => T): T =>
-    withTelegramFileTransaction(`${options.path}.transaction`, () => operation(read()));
+    withTelegramFileTransaction(publicationPaths.transactionPath, () => operation(read()));
   return {
     prepare(operationId, candidates) {
       if (!operationId || candidates.length === 0 || candidates.some(candidate => candidate.profileName !== options.profileName))
@@ -435,7 +438,7 @@ export function createTelegramThreadCleanupWorkStore(options: {
     },
     list() {
       return structuredClone(withTelegramFileTransaction(
-        `${options.path}.transaction`,
+        publicationPaths.transactionPath,
         () => read().workSets,
       ));
     },