@llblab/pi-kit 0.27.5 → 0.28.0

package/node_modules/@llblab/pi-telegram/lib/menu-settings.ts

@@ -143,19 +143,19 @@ export interface TelegramSettingsMenuRuntimeDeps<
   ) => Promise<void>;
 }
 
-export const SETTINGS_MENU_TITLE = "<b>⚙️ Settings:</b>";
-export const AUTOMATIC_THREAD_CLEANUP_SETTINGS_TITLE =
+const SETTINGS_MENU_TITLE = "<b>⚙️ Settings:</b>";
+const AUTOMATIC_THREAD_CLEANUP_SETTINGS_TITLE =
   "<b>🧹 Thread cleanup:</b>";
-export const INACTIVE_THREAD_REVIEW_TITLE = "<b>🔎 Inactive tabs review:</b>";
-export const DRAFT_PREVIEWS_SETTINGS_TITLE = "<b>📝 Draft previews:</b>";
-export const ASSISTANT_RENDERING_SETTINGS_TITLE =
+const INACTIVE_THREAD_REVIEW_TITLE = "<b>🔎 Inactive tabs review:</b>";
+const DRAFT_PREVIEWS_SETTINGS_TITLE = "<b>📝 Draft previews:</b>";
+const ASSISTANT_RENDERING_SETTINGS_TITLE =
   "<b>🧾 Assistant rendering:</b>";
-export const ACTIVITY_VERBOSITY_SETTINGS_TITLE =
+const ACTIVITY_VERBOSITY_SETTINGS_TITLE =
   "<b>🔬 Activity:</b>";
-export const TIME_INJECTION_MODE_SETTINGS_TITLE =
+const TIME_INJECTION_MODE_SETTINGS_TITLE =
   "<b>🕒 Time injection mode:</b>";
-export const VOICE_REPLY_MODE_SETTINGS_TITLE = "<b>👄 Voice reply mode:</b>";
-export const THREAD_DISPLAY_SETTINGS_TITLE = "<b>🧵 Thread display:</b>";
+const VOICE_REPLY_MODE_SETTINGS_TITLE = "<b>👄 Voice reply mode:</b>";
+const THREAD_DISPLAY_SETTINGS_TITLE = "<b>🧵 Thread display:</b>";
 
 function getVoiceReplyModeLabel(mode: TelegramVoiceReplyMode): string {
   return mode;
@@ -209,7 +209,7 @@ export function buildAutomaticThreadCleanupSettingsText(
   ].join("\n");
 }
 
-export function buildInactiveThreadReviewText(count: number): string {
+function buildInactiveThreadReviewText(count: number): string {
   return [INACTIVE_THREAD_REVIEW_TITLE, "",
     `${count} proven inactive tab${count === 1 ? "" : "s"}.`,
     "No tabs were deleted.",
@@ -393,7 +393,7 @@ export function buildTelegramSettingsMenuReplyMarkup(
   return { inline_keyboard: rows };
 }
 
-export async function openTelegramSettingsMenu<
+async function openTelegramSettingsMenu<
   TModel extends MenuModel = MenuModel,
 >(
   deps: TelegramSettingsMenuOpenDeps<TModel>,
@@ -560,7 +560,7 @@ export function buildVoiceReplyModeSettingsReplyMarkup(
   };
 }
 
-export async function updateTelegramSettingsMenuMessage(
+async function updateTelegramSettingsMenuMessage(
   deps: TelegramSettingsMenuMessageUpdateDeps,
   sectionRegistry?: TelegramSectionRegistry,
 ): Promise<void> {
@@ -581,7 +581,7 @@ export async function updateTelegramSettingsMenuMessage(
   );
 }
 
-export async function updateAutomaticThreadCleanupSettingsMessage(
+async function updateAutomaticThreadCleanupSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
   const enabled = deps.isAutomaticThreadCleanupEnabled();
@@ -591,7 +591,7 @@ export async function updateAutomaticThreadCleanupSettingsMessage(
   );
 }
 
-export async function updateDraftPreviewsSettingsMessage(
+async function updateDraftPreviewsSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
   const enabled = deps.areDraftPreviewsEnabled();
@@ -601,7 +601,7 @@ export async function updateDraftPreviewsSettingsMessage(
   );
 }
 
-export async function updateAssistantRenderingSettingsMessage(
+async function updateAssistantRenderingSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
   const mode = deps.getAssistantRenderingMode();
@@ -611,7 +611,7 @@ export async function updateAssistantRenderingSettingsMessage(
   );
 }
 
-export async function updateActivityVerbositySettingsMessage(
+async function updateActivityVerbositySettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
   const verbosity = deps.getActivityVerbosity();
@@ -621,7 +621,7 @@ export async function updateActivityVerbositySettingsMessage(
   );
 }
 
-export async function updateTimeInjectionModeSettingsMessage(
+async function updateTimeInjectionModeSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
   const mode = deps.getTimeInjectionMode();
@@ -631,7 +631,7 @@ export async function updateTimeInjectionModeSettingsMessage(
   );
 }
 
-export async function updateVoiceReplyModeSettingsMessage(
+async function updateVoiceReplyModeSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
   const mode = deps.getVoiceReplyMode();

package/node_modules/@llblab/pi-telegram/lib/menu-status.ts

@@ -160,6 +160,7 @@ export function buildStatusReplyMarkup(
   queueItemCount = 0,
   sectionRegistry?: TelegramSectionRegistry,
   isVoiceReplyActive?: boolean,
+  pendingCancellationCount = 0,
 ): TelegramReplyMarkup {
   const rows: Array<Array<{ text: string; callback_data: string }>> = [];
   rows.push([
@@ -188,6 +189,10 @@ export function buildStatusReplyMarkup(
       callback_data: "menu:queue",
     },
   ]);
+  if (pendingCancellationCount > 0) rows.push([{
+    text: `❌ Pending cancellations: ${pendingCancellationCount}`,
+    callback_data: "reroutecancel:review:open",
+  }]);
   if (sectionRegistry) {
     const sectionRows = getTelegramSectionMainMenuRows(sectionRegistry);
     for (const row of sectionRows) {
@@ -210,6 +215,7 @@ export function buildTelegramStatusMenuRenderPayload(
   queueItemCount = 0,
   sectionRegistry?: TelegramSectionRegistry,
   isVoiceReplyActive?: boolean,
+  pendingCancellationCount = 0,
 ): TelegramMenuRenderPayload {
   return {
     nextMode: "status",
@@ -221,6 +227,7 @@ export function buildTelegramStatusMenuRenderPayload(
       queueItemCount,
       sectionRegistry,
       isVoiceReplyActive,
+      pendingCancellationCount,
     ),
   };
 }
@@ -234,6 +241,7 @@ export async function updateTelegramStatusMessage(
   queueItemCount = 0,
   sectionRegistry?: TelegramSectionRegistry,
   isVoiceReplyActive?: boolean,
+  pendingCancellationCount = 0,
 ): Promise<void> {
   await editTelegramMenuMessage(
     state,
@@ -244,6 +252,7 @@ export async function updateTelegramStatusMessage(
       queueItemCount,
       sectionRegistry,
       isVoiceReplyActive,
+      pendingCancellationCount,
     ),
     deps,
   );
@@ -258,6 +267,7 @@ export function sendTelegramStatusMessage(
   queueItemCount = 0,
   sectionRegistry?: TelegramSectionRegistry,
   isVoiceReplyActive?: boolean,
+  pendingCancellationCount = 0,
 ): Promise<number | undefined> {
   return sendTelegramMenuMessage(
     state,
@@ -268,6 +278,7 @@ export function sendTelegramStatusMessage(
       queueItemCount,
       sectionRegistry,
       isVoiceReplyActive,
+      pendingCancellationCount,
     ),
     deps,
   );

package/node_modules/@llblab/pi-telegram/lib/menu-thinking.ts

@@ -20,7 +20,7 @@ import {
 export interface TelegramThinkingMenuCallbackDeps {
   setThinkingLevel: (level: ThinkingLevel) => void;
   getCurrentThinkingLevel: () => ThinkingLevel;
-  updateStatusMessage: () => Promise<void>;
+  updateThinkingMenuMessage: () => Promise<void>;
   answerCallbackQuery: (
     callbackQueryId: string,
     text?: string,
@@ -112,7 +112,7 @@ export async function handleTelegramThinkingMenuCallbackAction(
     return true;
   }
   deps.setThinkingLevel(action.level);
-  await deps.updateStatusMessage();
+  await deps.updateThinkingMenuMessage();
   await deps.answerCallbackQuery(
     callbackQueryId,
     `Thinking: ${deps.getCurrentThinkingLevel()}`,

package/node_modules/@llblab/pi-telegram/lib/menu.ts

@@ -255,6 +255,7 @@ export interface TelegramMenuActionRuntimeDeps<
   getActiveModel: (ctx: TContext) => TModel | undefined;
   getThinkingLevel: () => ThinkingLevel;
   getQueueItemCount?: () => number;
+  getPendingCancellationCount?: () => number;
   buildStatusHtml: (ctx: TContext) => string;
   storeModelMenuState: (state: TelegramModelMenuState<TModel>) => void;
   isIdle: (ctx: TContext) => boolean;
@@ -702,7 +703,7 @@ export async function handleTelegramMenuCallbackRuntime<
             deps.updateStatus(ctx);
           },
           getCurrentThinkingLevel: deps.getThinkingLevel,
-          updateStatusMessage: () => deps.updateStatusMessage(state, ctx),
+          updateThinkingMenuMessage: () => deps.updateThinkingMenuMessage(state, ctx),
           answerCallbackQuery: deps.answerCallbackQuery,
           isVoiceReplyActive: deps.isVoiceReplyActive,
         },
@@ -782,6 +783,7 @@ export function createTelegramMenuActionRuntimeWithStateBuilder<
     getActiveModel: deps.getActiveModel,
     getThinkingLevel: deps.getThinkingLevel,
     getQueueItemCount: deps.getQueueItemCount,
+    getPendingCancellationCount: deps.getPendingCancellationCount,
     buildStatusHtml: deps.buildStatusHtml,
     storeModelMenuState: deps.storeModelMenuState,
     isIdle: deps.isIdle,
@@ -819,6 +821,7 @@ export function createTelegramMenuActionRuntime<
         deps.getQueueItemCount?.() ?? 0,
         deps.sectionRegistry,
         deps.isVoiceReplyActive?.(),
+        deps.getPendingCancellationCount?.() ?? 0,
       ),
     sendStatusMessage: (chatId, replyToMessageId, ctx, threadId) =>
       openTelegramStatusMenu({
@@ -852,6 +855,7 @@ export function createTelegramMenuActionRuntime<
             queueItemCount,
             deps.sectionRegistry,
             deps.isVoiceReplyActive?.(),
+            deps.getPendingCancellationCount?.() ?? 0,
           ),
         storeModelMenuState: deps.storeModelMenuState,
       }),

package/node_modules/@llblab/pi-telegram/lib/outbound-attachments.ts

@@ -51,7 +51,7 @@ export function getTelegramOutboundAttachmentByteLimitFromEnv(
   return defaultValue;
 }
 
-export const TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES =
+const TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES =
   getTelegramOutboundAttachmentByteLimitFromEnv(process.env, [
     "PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES",
     "TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES",

package/node_modules/@llblab/pi-telegram/lib/outbound-buttons.ts

@@ -11,6 +11,7 @@ import type {
   TelegramInlineKeyboardMarkup,
 } from "./keyboard.ts";
 import {
+  getTelegramActionString as getTelegramButtonString,
   parseTelegramActionPayloadRows,
   parseTelegramButtonPayloadRows,
   replaceTelegramButtonFences,
@@ -101,16 +102,6 @@ function normalizeMarkdownAfterButtonExtraction(markdown: string): string {
   return markdown.replace(/\n{3,}/g, "\n\n").trim();
 }
 
-function getTelegramButtonString(
-  payload: Record<string, unknown>,
-  key: string,
-): string | undefined {
-  const value = payload[key];
-  if (typeof value !== "string") return undefined;
-  const trimmed = value.trim();
-  return trimmed || undefined;
-}
-
 function parseTelegramButtonAction(
   payload: Record<string, unknown>,
 ): TelegramOutboundButtonAction | undefined {

package/node_modules/@llblab/pi-telegram/lib/outbound-markup.ts

@@ -4,6 +4,8 @@
  * Owns top-level assistant action comment extraction, attribute parsing, and markup stripping shared by voice and outbound delivery
  */
 
+import { isWireRecord as isTelegramActionPayload } from "./wire.ts";
+
 export interface TelegramTopLevelHtmlComment {
   raw: string;
   content: string;
@@ -150,7 +152,7 @@ export function replaceTopLevelHtmlComments(
   return result + markdown.slice(offset);
 }
 
-export function findTopLevelOpenOrPartialHtmlCommentIndex(
+function findTopLevelOpenOrPartialHtmlCommentIndex(
   markdown: string,
 ): number {
   const { openCommentStart } = collectTopLevelHtmlComments(markdown);
@@ -180,23 +182,6 @@ export function findTopLevelOpenOrPartialHtmlCommentIndex(
   return -1;
 }
 
-export function parseTopLevelTelegramComment(
-  comment: TelegramTopLevelHtmlComment,
-  command: string,
-): { head: string; body?: string } | undefined {
-  let normalizedContent = comment.content.replace(/^\s+/, "");
-  normalizedContent = normalizedContent.replace(/^!/, "");
-  const [rawHead = "", ...bodyLines] = normalizedContent.split(/\r?\n/);
-  let head = rawHead.trimStart();
-  if (!head.startsWith(command)) return undefined;
-  const nextChar = head[command.length];
-  if (nextChar !== undefined && !/\s|:/.test(nextChar)) return undefined;
-  return {
-    head: head.slice(command.length),
-    ...(bodyLines.length > 0 ? { body: bodyLines.join("\n") } : {}),
-  };
-}
-
 function parseTolerantTelegramAttributes(
   source: string,
   names: readonly string[],
@@ -214,10 +199,6 @@ function parseTolerantTelegramAttributes(
   return Object.keys(attributes).length > 0 ? attributes : undefined;
 }
 
-function isTelegramActionPayload(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
 function removeTelegramJsonTrailingCommas(source: string): string {
   let normalized = "";
   let inString = false;
@@ -268,7 +249,7 @@ function looksLikeTelegramNamedJsonObject(
   return /^\{\s*"(?:[^"\\]|\\.)*"\s*:/u.test(source.slice(offset));
 }
 
-export function parseTelegramActionPayload(
+function parseTelegramActionPayload(
   comment: TelegramTopLevelHtmlComment,
   command: string,
 ): Record<string, unknown> | undefined {
@@ -711,7 +692,7 @@ export interface TelegramVoiceReplyPlan {
   rate?: string;
 }
 
-function getTelegramActionString(
+export function getTelegramActionString(
   payload: Record<string, unknown>,
   key: string,
 ): string | undefined {

package/node_modules/@llblab/pi-telegram/lib/outbound.ts

@@ -9,7 +9,7 @@ import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 
 import type { TelegramAssistantSegmentEvent } from "./activity.ts";
-import { resolveTelegramTempDir } from "./paths.ts";
+import { resolveTelegramAttachmentsDir } from "./paths.ts";
 import * as Replies from "./replies.ts";
 import type { TelegramPreparedPreviewDelivery } from "./preview.ts";
 import { isTelegramApiCommitUnknownError } from "./telegram-api.ts";
@@ -202,7 +202,7 @@ export function registerTelegramOutboundHandler(
   };
 }
 
-export function getTelegramOutboundProgrammaticHandlers(
+function getTelegramOutboundProgrammaticHandlers(
   kind: string,
 ): TelegramOutboundProgrammaticHandler[] {
   const registry = getOrCreateOutboundHandlerRegistry();
@@ -451,7 +451,7 @@ function getVoiceReplyTemplateValues(
 }
 
 function getDefaultTelegramVoiceTempDir(): string {
-  return resolveTelegramTempDir();
+  return resolveTelegramAttachmentsDir();
 }
 
 async function generateTelegramVoiceReplyFileWithHandler(
@@ -598,7 +598,7 @@ async function transformTelegramOutboundTextWithHandler(
   return result.stdout.trim() || text;
 }
 
-export async function transformTelegramOutboundText(
+async function transformTelegramOutboundText(
   text: string,
   options: {
     handlers?: TelegramOutboundHandlerConfig[];
@@ -658,7 +658,7 @@ async function transformTelegramOutboundReplyMarkup<TReplyMarkup>(
   return { ...replyMarkup, inline_keyboard: translatedRows } as TReplyMarkup;
 }
 
-export async function transformTelegramOutboundTextReply<
+async function transformTelegramOutboundTextReply<
   TReplyMarkup = unknown,
 >(
   text: string,

package/node_modules/@llblab/pi-telegram/lib/paths.ts

@@ -3,13 +3,15 @@
  * Zones: telemetry paths, filesystem, runtime identity
  * Owns agent-dir detection and extension-local path derivation
  *
- * This domain is pure/path-only: it resolves directories and file paths
- * from environment and runtime identity. It does not read config, manage
- * state, or import broader Telegram domains.
+ * This domain is path-only: it resolves directories and file paths from
+ * environment and runtime identity. Its only filesystem read canonicalizes the
+ * existing agent-dir prefix; it does not read config, manage state, or import
+ * broader Telegram domains.
  */
 import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 
 export const TELEGRAM_DEFAULT_PROFILE_NAME = "default";
 
@@ -62,12 +64,56 @@ export function resolveTelegramConfigPath(): string {
   return join(resolveAgentDir(), "telegram.json");
 }
 
-/** Telegram bridge temporary directory (<agentDir>/tmp/telegram). */
+/**
+ * Resolve symlinks in the longest existing prefix of `path` and keep the missing suffix. Strict journal reads require
+ * canonical anchors, so a symlinked agent directory (for example macOS `/var` → `/private/var`) must not leak in.
+ * Relative input is returned unchanged so callers' exact-absolute-path guards still reject it. Windows keeps its
+ * spelling: strict journal reads are POSIX-only there, and resolving a drive-less root would add a drive letter.
+ */
+function canonicalizeExistingPrefix(path: string): string {
+  if (!isAbsolute(path) || process.platform === "win32") return path;
+  const absolute = resolve(path);
+  const missing: string[] = [];
+  for (let current = absolute; ; current = dirname(current)) {
+    try { return join(realpathSync(current), ...missing.reverse()); }
+    catch (error) {
+      if ((error as { code?: unknown }).code !== "ENOENT" || dirname(current) === current) return absolute;
+      missing.push(basename(current));
+    }
+  }
+}
+
+/** Telegram bridge temporary directory (<agentDir>/tmp/pi-telegram); releases before 0.52.0 used `tmp/telegram`. */
 export function resolveTelegramTempDir(agentDir = resolveAgentDir()): string {
-  return join(agentDir, "tmp", "telegram");
+  return join(canonicalizeExistingPrefix(agentDir), "tmp", "pi-telegram");
+}
+
+/** Consolidated-root service artifacts (transaction guards, staging and IPC), never session custody. */
+export function resolveTelegramRuntimeDir(agentDir = resolveAgentDir()): string {
+  return join(resolveTelegramTempDir(agentDir), "runtime");
 }
 
-/** Telegram transport ownership store (<agentDir>/tmp/telegram/owners.json). */
+/** Rotated shared runtime event segments, outside the persistent root-file census. */
+export function resolveTelegramRuntimeLogsDir(agentDir = resolveAgentDir()): string {
+  return join(resolveTelegramTempDir(agentDir), "logs");
+}
+
+/** Consolidated runtime state for every logical profile (`tmp/pi-telegram/state.json`). */
+export function resolveTelegramStatePath(agentDir = resolveAgentDir()): string {
+  return join(resolveTelegramTempDir(agentDir), "state.json");
+}
+
+/** Flat attachment scratch directory (<agentDir>/tmp/pi-telegram/attachments). */
+export function resolveTelegramAttachmentsDir(agentDir = resolveAgentDir()): string {
+  return join(resolveTelegramTempDir(agentDir), "attachments");
+}
+
+/** Read-only pre-0.52.0 ownership file, consulted only to refuse a second poller beside a live older leader. */
+export function resolveLegacyTelegramOwnersPath(agentDir = resolveAgentDir()): string {
+  return join(agentDir, "tmp", "telegram", "owners.json");
+}
+
+/** Telegram transport ownership store (<agentDir>/tmp/pi-telegram/owners.json). */
 export function resolveTelegramOwnersPath(): string {
   return join(resolveTelegramTempDir(), "owners.json");
 }
@@ -89,19 +135,17 @@ export function resolveTelegramProfileTempFilePath(
   );
 }
 
-export function getTelegramDiagnosticsDisplayPaths(profileName?: string): {
+export function getTelegramDiagnosticsDisplayPaths(_profileName?: string): {
   state: string;
   logs: string;
 } {
-  const suffix = getTelegramProfilePathSuffix(profileName);
-  const profileSlug = suffix.slice(1);
   return {
-    state: `~/.pi/agent/tmp/telegram/state${suffix}.json`,
-    logs: `~/.pi/agent/tmp/telegram/logs${profileSlug ? `.${profileSlug}` : ""}.jsonl`,
+    state: "~/.pi/agent/tmp/pi-telegram/state.json",
+    logs: "~/.pi/agent/tmp/pi-telegram/logs.jsonl",
   };
 }
 
-/** Durable Workspace admission ledger (<agentDir>/tmp/telegram/workspace-admission[.<profile>].json). */
+/** Durable Workspace admission ledger (<agentDir>/tmp/pi-telegram/workspace-admission[.<profile>].json). */
 export function resolveTelegramWorkspaceAdmissionPath(
   agentDir = resolveAgentDir(),
   profileName?: string,
@@ -121,6 +165,31 @@ export function resolveTelegramWorkspaceAdmissionPathForProfile(
   return resolveTelegramWorkspaceAdmissionPath(resolveAgentDir(), profileName);
 }
 
+/** Consolidated non-session service journal (`journals/<kind>.<profile sha256>.json`) and its runtime namespace. */
+export function resolveTelegramServiceJournalStorage(
+  kind: "thread-cleanup" | "channel-posts",
+  agentDir = resolveAgentDir(),
+  profileName = TELEGRAM_DEFAULT_PROFILE_NAME,
+): { path: string; runtimeDir: string } {
+  const profileHash = createHash("sha256").update(profileName).digest("hex");
+  return {
+    path: join(resolveTelegramTempDir(agentDir), "journals", `${kind}.${profileHash}.json`),
+    runtimeDir: resolveTelegramRuntimeDir(agentDir),
+  };
+}
+
+/** Bind one non-session journal to its exact colocated-root service namespace, never a format fallback. */
+export function getTelegramJournalPublicationPaths(path: string, runtimeDir?: string): {
+  transactionPath: string;
+  temporaryBasePath: string;
+} {
+  if (runtimeDir === undefined) return { transactionPath: `${path}.transaction`, temporaryBasePath: path };
+  requireTelegramStoragePathReference(path, resolve(path));
+  requireTelegramStoragePathReference(runtimeDir, join(dirname(dirname(path)), "runtime"));
+  if (basename(dirname(path)) !== "journals") throw new Error("Telegram service journal must use its journals namespace.");
+  return { transactionPath: join(runtimeDir, `${basename(path)}.transaction`), temporaryBasePath: join(runtimeDir, basename(path)) };
+}
+
 /** Durable inactive Thread cleanup work-set journal. */
 export function resolveTelegramThreadCleanupWorkPath(
   agentDir = resolveAgentDir(),
@@ -137,7 +206,7 @@ export function resolveTelegramChannelPostJournalPath(
   return resolveTelegramProfileTempFilePath("channel-posts", "json", agentDir, profileName);
 }
 
-/** Durable inbound update journal (<agentDir>/tmp/telegram/inbox[.<profile>].json). */
+/** Durable inbound update journal (<agentDir>/tmp/pi-telegram/inbox[.<profile>].json). */
 export function resolveTelegramUpdateJournalPath(
   agentDir = resolveAgentDir(),
   profileName?: string,
@@ -178,7 +247,98 @@ export function resolveTelegramFollowerJournalPath(
   );
 }
 
-/** Runtime event log (<agentDir>/tmp/telegram/logs.jsonl). */
-export function resolveTelegramRuntimeLogPath(): string {
-  return resolveTelegramProfileTempFilePath("logs", "jsonl");
+const TELEGRAM_SESSION_DIRECTORY_MAX_LENGTH = 200;
+const WINDOWS_RESERVED_NAME = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\..*)?$/u;
+
+/**
+ * Directory name for a session id. Lowercase letters, digits, `_`, `-` and inner `.` stay verbatim, so every real
+ * (UUID-shaped) id is unchanged; any other UTF-8 byte is percent-encoded. Uppercase is encoded so case-insensitive
+ * filesystems never merge two sessions; a leading or trailing dot and Windows reserved names are encoded so the name
+ * can never be `.`/`..`, hidden, or a device. The encoding is reversible; an empty or over-long result is refused.
+ */
+export function encodeTelegramSessionDirectoryName(sessionId: string): string | undefined {
+  if (typeof sessionId !== "string" || sessionId.length === 0) return undefined;
+  const bytes = Buffer.from(sessionId, "utf8");
+  if (bytes.toString("utf8") !== sessionId) return undefined;
+  let name = "";
+  bytes.forEach((byte, index) => {
+    const char = String.fromCharCode(byte);
+    const safe = /[a-z0-9_-]/u.test(char) || (char === "." && index > 0 && index < bytes.length - 1);
+    name += safe ? char : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+  });
+  if (WINDOWS_RESERVED_NAME.test(name)) name = `%${name.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}${name.slice(1)}`;
+  return name.length <= TELEGRAM_SESSION_DIRECTORY_MAX_LENGTH ? name : undefined;
+}
+
+/** Inverse of `encodeTelegramSessionDirectoryName`; undefined unless the name is exactly canonical. */
+export function decodeTelegramSessionDirectoryName(name: string): string | undefined {
+  if (!/^[a-z0-9_.%A-F-]+$/u.test(name)) return undefined;
+  const bytes: number[] = [];
+  for (let index = 0; index < name.length; index++) {
+    if (name[index] === "%") {
+      const hex = name.slice(index + 1, index + 3);
+      if (!/^[0-9A-F]{2}$/u.test(hex)) return undefined;
+      bytes.push(Number.parseInt(hex, 16));
+      index += 2;
+    } else bytes.push(name.charCodeAt(index));
+  }
+  const decoded = Buffer.from(bytes).toString("utf8");
+  return encodeTelegramSessionDirectoryName(decoded) === name ? decoded : undefined;
+}
+
+/** Root of every session folder (<agentDir>/tmp/pi-telegram/sessions). */
+export function resolveTelegramSessionsDir(agentDir = resolveAgentDir()): string {
+  return join(resolveTelegramTempDir(agentDir), "sessions");
+}
+
+/** One session's folder (<agentDir>/tmp/pi-telegram/sessions/<session id>). */
+export function resolveTelegramSessionDir(sessionId: string, agentDir = resolveAgentDir()): string {
+  const name = encodeTelegramSessionDirectoryName(sessionId);
+  if (!name) throw new Error("Telegram session directory requires a usable session id.");
+  return join(resolveTelegramSessionsDir(agentDir), name);
+}
+
+/** Hash naming one recipient incarnation inside its session folder; unchanged from the former follower inbox. */
+export function getTelegramRecipientJournalHash(recipientBindingKey: string): string {
+  if (!recipientBindingKey) throw new Error("Telegram session journal binding key is required.");
+  return createHash("sha256").update(recipientBindingKey).digest("hex").slice(0, 16);
+}
+
+/** Durable per-session journal (`sessions/<session id>/journal.<hash>[.<profile>].json`); the name never reveals a role. */
+export function resolveTelegramSessionJournalPath(
+  sessionId: string,
+  recipientBindingKey: string,
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return join(
+    resolveTelegramSessionDir(sessionId, agentDir),
+    `journal.${getTelegramRecipientJournalHash(recipientBindingKey)}${getTelegramProfilePathSuffix(profileName)}.json`,
+  );
+}
+
+/** Leader polling journal hosted by the session that first led (`sessions/<id>/inbox[.<profile>].json`); owners.json names it. */
+export function resolveTelegramSessionPollingJournalPath(
+  sessionId: string,
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return join(resolveTelegramSessionDir(sessionId, agentDir), `inbox${getTelegramProfilePathSuffix(profileName)}.json`);
+}
+
+/** Accept only a canonical `sessions/<id>/inbox[.<profile>].json` beneath this agent's runtime. */
+export function isTelegramSessionPollingJournalPath(path: string, agentDir = resolveAgentDir()): boolean {
+  const parts = relative(resolveTelegramSessionsDir(agentDir), path).split(sep);
+  return isAbsolute(path) && parts.length === 2 && decodeTelegramSessionDirectoryName(parts[0]!) !== undefined &&
+    /^inbox(?:\.[a-zA-Z0-9._-]+)?\.json$/u.test(parts[1]!);
+}
+
+/** Runtime event log (<agentDir>/tmp/pi-telegram/logs.jsonl). */
+export function resolveTelegramRuntimeLogPath(agentDir = resolveAgentDir()): string {
+  return resolveTelegramProfileTempFilePath("logs", "jsonl", agentDir);
+}
+
+/** Bounded previous shared log segment below `logs/`. */
+export function resolveTelegramPreviousSharedRuntimeLogPath(agentDir = resolveAgentDir()): string {
+  return join(resolveTelegramRuntimeLogsDir(agentDir), "logs._prev.jsonl");
 }

package/node_modules/@llblab/pi-telegram/lib/pi.ts

@@ -263,8 +263,11 @@ export function getExtensionContextCwd(ctx: ExtensionContext): string {
   return ctx.cwd;
 }
 
-export function getExtensionContextSessionId(ctx: ExtensionContext): string {
-  return ctx.sessionManager.getSessionId();
+export function getExtensionContextSessionId(ctx: ExtensionContext): string;
+export function getExtensionContextSessionId(ctx: ExtensionContext | undefined): string | undefined;
+export function getExtensionContextSessionId(ctx: ExtensionContext | undefined): string | undefined {
+  // Minimal hosts and stale contexts may omit a session manager; absence is not an invented ID.
+  return ctx?.sessionManager?.getSessionId?.();
 }
 
 export function isExtensionContextIdle(ctx: ExtensionContext): boolean {