@llblab/pi-telegram 0.52.2 → 0.53.1

package/dist/lib/outbound.js

@@ -6,15 +6,15 @@
 import { randomUUID } from "node:crypto";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import { resolveTelegramAttachmentsDir } from "./paths.js";
-import * as Replies from "./replies.js";
-import { isTelegramApiCommitUnknownError } from "./telegram-api.js";
 import { planTelegramButtonReply, } from "./outbound-buttons.js";
 import { planTelegramVoiceReply, stripTelegramCommentMarkupForDelivery, } from "./outbound-markup.js";
 import { createTelegramVoiceReplySender as createTelegramVoiceReplySenderWithPorts } from "./outbound-voice.js";
+import { resolveTelegramAttachmentsDir } from "./paths.js";
+import * as Replies from "./replies.js";
+import { assertTelegramApiCallAuthority, isTelegramApiCommitUnknownError, } from "./telegram-api.js";
 const OUTBOUND_HANDLER_REGISTRY_KEY = "__piTelegramOutboundHandlers__";
 const VOICE_EVENT_RECORDER_KEY = "__piTelegramVoiceEventRecorder__";
-import { buildCommandTemplateInvocation, expandCommandTemplateConfigs, substituteCommandTemplateToken, } from "./command-templates.js";
+import { buildCommandTemplateInvocation, createCommandTemplateRecovery, getCommandTemplateCompositionSteps, shouldRunCommandTemplateConfig, getCommandTemplateConfiguredTimeout, getCommandTemplateStepTimeout, resolveCommandTemplateNumericField, } from "./command-templates.js";
 const DEFAULT_VOICE_TIMEOUT_MS = 120_000;
 export function bindTelegramRuntimeEventRecorder(recorder) {
     globalThis[VOICE_EVENT_RECORDER_KEY] = recorder;
@@ -25,7 +25,6 @@ export function recordTelegramRuntimeEvent(category, error, details) {
         recorder(category, error, details);
     }
 }
-export { normalizeMarkdownAfterVoiceExtraction, planTelegramVoiceReply, stripTelegramCommentMarkupForDelivery, stripTelegramCommentMarkupForPreview, stripTelegramVoiceMarkupForPreview, } from "./outbound-markup.js";
 // --- Programmatic Outbound Handler Registry Runtime ---
 function getOrCreateOutboundHandlerRegistry() {
     const existing = globalThis[OUTBOUND_HANDLER_REGISTRY_KEY];
@@ -62,35 +61,8 @@ function getTelegramOutboundProgrammaticHandlers(kind) {
     return [...(registry.handlers.get(kind) ?? [])];
 }
 // --- Voice Reply Timeout Helpers ---
-function resolveOutboundNumericControlField(value, values, label) {
-    if (value === undefined)
-        return undefined;
-    const resolved = typeof value === "string"
-        ? substituteCommandTemplateToken(value, values, label)
-        : value;
-    if (resolved === "")
-        return undefined;
-    const numeric = Number(resolved);
-    if (!Number.isFinite(numeric) || numeric < 0)
-        throw new Error(`Command template ${label} must be a non-negative number.`);
-    return numeric;
-}
-function getVoiceReplyConfiguredTimeout(config) {
-    const timeout = typeof config === "string" ? undefined : config?.timeout;
-    return resolveOutboundNumericControlField(timeout, {}, "timeout");
-}
 function getVoiceReplyTimeout(config) {
-    return getVoiceReplyConfiguredTimeout(config) ?? DEFAULT_VOICE_TIMEOUT_MS;
-}
-function getRemainingVoiceReplyTimeout(timeout, startedAt) {
-    return Math.max(1, timeout - (Date.now() - startedAt));
-}
-function getVoiceReplyCompositionStepTimeout(handlerTimeout, step, startedAt) {
-    const remaining = getRemainingVoiceReplyTimeout(handlerTimeout, startedAt);
-    const stepTimeout = getVoiceReplyConfiguredTimeout(step);
-    return stepTimeout === undefined
-        ? remaining
-        : Math.min(stepTimeout, remaining);
+    return (getCommandTemplateConfiguredTimeout(config) ?? DEFAULT_VOICE_TIMEOUT_MS);
 }
 function formatVoiceReplyExecutionFailure(label, result) {
     const parts = [
@@ -102,6 +74,9 @@ function formatVoiceReplyExecutionFailure(label, result) {
         parts.push(`stdout:\n${result.stdout.trimEnd()}`);
     return parts.join("\n\n");
 }
+function withCommandTemplateRecovery(recover) {
+    return recover ? { recover } : {};
+}
 async function runVoiceReplyCommand(label, config, values, options) {
     if (!options.execCommand) {
         throw new Error("execCommand is required for command template execution");
@@ -115,7 +90,12 @@ async function runVoiceReplyCommand(label, config, values, options) {
         timeout: options.timeout,
         ...(typeof config === "object" && config.retry !== undefined
             ? {
-                retry: resolveOutboundNumericControlField(config.retry, {}, "retry"),
+                retry: resolveCommandTemplateNumericField(config.retry, {}, "retry"),
+                ...withCommandTemplateRecovery(createCommandTemplateRecovery(config, values, {
+                    cwd: options.cwd,
+                    timeout: options.timeout,
+                    execCommand: options.execCommand,
+                })),
             }
             : {}),
         ...(options.stdin !== undefined ? { stdin: options.stdin } : {}),
@@ -150,12 +130,6 @@ export function findTelegramOutboundHandlers(handlers, type) {
         typeof handler === "object" &&
         outboundHandlerMatchesType(handler, type));
 }
-function getTelegramVoiceHandlerCompositionSteps(handler) {
-    if (Array.isArray(handler.template)) {
-        return expandCommandTemplateConfigs(handler);
-    }
-    return [];
-}
 function extractVoiceReplyPath(stdout) {
     const path = stdout.trim().split(/\r?\n/).filter(Boolean).at(-1);
     if (!path)
@@ -194,15 +168,19 @@ async function generateTelegramVoiceReplyFileWithHandler(text, options) {
         mp3Path: join(options.tempDir, `${artifactId}-voice.mp3`),
         oggPath: join(options.tempDir, `${artifactId}-voice.ogg`),
     });
-    const steps = getTelegramVoiceHandlerCompositionSteps(options.handler);
+    if (!shouldRunCommandTemplateConfig(options.handler, values))
+        return undefined;
+    const steps = getCommandTemplateCompositionSteps(options.handler);
     if (steps.length > 0) {
         const startedAt = Date.now();
         let stdout = text;
         for (const [index, step] of steps.entries()) {
+            if (!shouldRunCommandTemplateConfig(step, values))
+                continue;
             try {
                 const result = await runVoiceReplyCommand(`Outbound voice template step ${index + 1}`, step, values, {
                     cwd: options.cwd,
-                    timeout: getVoiceReplyCompositionStepTimeout(options.timeout, step, startedAt),
+                    timeout: getCommandTemplateStepTimeout(options.timeout, step, Date.now() - startedAt),
                     execCommand: options.execCommand,
                     stdin: stdout,
                 });
@@ -243,15 +221,19 @@ function getOutboundTextTemplateValues(text) {
 }
 async function transformTelegramOutboundTextWithHandler(text, options) {
     const values = getOutboundTextTemplateValues(text);
-    const steps = getTelegramVoiceHandlerCompositionSteps(options.handler);
+    if (!shouldRunCommandTemplateConfig(options.handler, values))
+        return text;
+    const steps = getCommandTemplateCompositionSteps(options.handler);
     if (steps.length > 0) {
         const startedAt = Date.now();
         let stdout = text;
         for (const [index, step] of steps.entries()) {
+            if (!shouldRunCommandTemplateConfig(step, values))
+                continue;
             try {
                 const result = await runVoiceReplyCommand(`Outbound text template step ${index + 1}`, step, values, {
                     cwd: options.cwd,
-                    timeout: getVoiceReplyCompositionStepTimeout(getVoiceReplyTimeout(options.handler), step, startedAt),
+                    timeout: getCommandTemplateStepTimeout(getVoiceReplyTimeout(options.handler), step, Date.now() - startedAt),
                     execCommand: options.execCommand,
                     stdin: stdout,
                 });
@@ -328,17 +310,33 @@ async function transformTelegramOutboundTextReply(text, options) {
     return { text: transformedText, ...(replyMarkup ? { replyMarkup } : {}) };
 }
 export function createTelegramOutboundTextReplyRuntime(deps) {
+    const sendTextReply = deps.sendTextReply, sendMarkdownReply = deps.sendMarkdownReply;
     return {
         sendTextReply: async (chatId, replyToMessageId, text, options) => {
+            const capturedOptions = options && {
+                ...options,
+                ...(options.target ? { target: { ...options.target } } : {}),
+            };
+            const assertAuthority = capturedOptions?.assertAuthority;
+            assertTelegramApiCallAuthority(assertAuthority, false);
             const transformed = await transformTelegramOutboundText(text, {
                 handlers: deps.getHandlers?.(),
                 cwd: deps.cwd,
                 execCommand: deps.execCommand,
                 recordRuntimeEvent: deps.recordRuntimeEvent,
             });
-            return deps.sendTextReply(chatId, replyToMessageId, transformed, options);
+            assertTelegramApiCallAuthority(assertAuthority, false);
+            const messageId = await sendTextReply(chatId, replyToMessageId, transformed, capturedOptions);
+            assertTelegramApiCallAuthority(assertAuthority, true);
+            return messageId;
         },
         sendMarkdownReply: async (chatId, replyToMessageId, markdown, options) => {
+            const capturedOptions = options && {
+                ...options,
+                ...(options.target ? { target: { ...options.target } } : {}),
+            };
+            const assertAuthority = capturedOptions?.assertAuthority;
+            assertTelegramApiCallAuthority(assertAuthority, false);
             const deliveryMarkdown = stripTelegramCommentMarkupForDelivery(markdown);
             if (!deliveryMarkdown)
                 return undefined;
@@ -347,14 +345,17 @@ export function createTelegramOutboundTextReplyRuntime(deps) {
                 cwd: deps.cwd,
                 execCommand: deps.execCommand,
                 recordRuntimeEvent: deps.recordRuntimeEvent,
-                replyMarkup: options?.replyMarkup,
+                replyMarkup: capturedOptions?.replyMarkup,
             });
-            return deps.sendMarkdownReply(chatId, replyToMessageId, transformed.text, {
-                ...options,
+            assertTelegramApiCallAuthority(assertAuthority, false);
+            const messageId = await sendMarkdownReply(chatId, replyToMessageId, transformed.text, {
+                ...capturedOptions,
                 ...(transformed.replyMarkup
                     ? { replyMarkup: transformed.replyMarkup }
                     : {}),
             });
+            assertTelegramApiCallAuthority(assertAuthority, true);
+            return messageId;
         },
     };
 }
@@ -378,7 +379,12 @@ export function createTelegramOutboundTextPreviewRuntime(deps) {
         finalizeMarkdownPreview: wrap(deps.finalizeMarkdownPreview),
         preparePreviewDelivery(isDeliveryActive) {
             const prepared = deps.preparePreviewDelivery?.(isDeliveryActive);
-            return prepared ? { ...prepared, finalizeMarkdownPreview: wrap(prepared.finalizeMarkdownPreview) } : undefined;
+            return prepared
+                ? {
+                    ...prepared,
+                    finalizeMarkdownPreview: wrap(prepared.finalizeMarkdownPreview),
+                }
+                : undefined;
         },
     };
 }
@@ -431,14 +437,22 @@ export function createTelegramOutboundReplyPlanner(store, getRenderingMode = ()
 // --- Outbound Reply Artifacts ---
 export function createTelegramOutboundReplyArtifactSender(deps) {
     return async (turn, plan, options) => {
-        const isDeliveryActive = () => deps.isDeliveryActive?.() !== false && options?.isDeliveryActive?.() !== false;
-        const sendVoiceReply = createTelegramVoiceReplySender({ ...deps, isDeliveryActive });
+        const isDeliveryActive = () => deps.isDeliveryActive?.() !== false &&
+            options?.isDeliveryActive?.() !== false;
+        const sendVoiceReply = createTelegramVoiceReplySender({
+            ...deps,
+            isDeliveryActive,
+        });
         // Normalize voice replies: either use explicit voiceReplies array or fall back to voiceText
         const voiceReplies = plan.voiceReplies?.length
             ? plan.voiceReplies
             : plan.voiceText
                 ? [{ text: plan.voiceText, lang: plan.lang, rate: plan.rate }]
                 : [];
+        // A plan without voice content has nothing to deliver; absence of
+        // content is not a synthesis failure.
+        if (voiceReplies.length === 0)
+            return;
         let anyDelivered = false;
         for (const reply of voiceReplies) {
             if (!isDeliveryActive())

package/dist/lib/ownership.js

@@ -52,12 +52,16 @@ export function createTelegramBusMessageOwnershipRuntime(deps) {
             const record = store.get(chatId, messageId);
             if (!record?.ownerGeneration || !record.recipientBindingKey)
                 return record;
-            const follower = deps.listFollowers().find((candidate) => candidate.instanceId === record.instanceId &&
+            const follower = deps
+                .listFollowers()
+                .find((candidate) => candidate.instanceId === record.instanceId &&
                 candidate.registrationGeneration === record.ownerGeneration &&
                 candidate.profileKey === record.recipientBindingKey);
             // Protocol is live registration authority, not message-cache history.
             // Keep an incomplete known owner foreign so the forwarder fails closed.
-            return follower?.protocol?.capabilities.includes(TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION) ? { ...record, protocolIdentity: follower.protocol } : record;
+            return follower?.protocol?.capabilities.includes(TELEGRAM_BUS_CAPABILITY_DURABLE_FOLLOWER_ADMISSION)
+                ? { ...record, protocolIdentity: follower.protocol }
+                : record;
         },
         recordLocal(input) {
             return store.record({ ...input, instanceId: deps.instanceId });

package/dist/lib/paths.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Telegram bridge path resolution for Pi-compatible runtimes
+ * Zones: telemetry paths, filesystem, runtime identity
+ * Owns agent-dir detection and extension-local path derivation
+ */
 export declare const TELEGRAM_DEFAULT_PROFILE_NAME = "default";
 export interface TelegramAgentDirResolutionInput {
     env?: Partial<Pick<NodeJS.ProcessEnv, "PI_CODING_AGENT_DIR">>;

package/dist/lib/paths.js

@@ -2,16 +2,11 @@
  * Telegram bridge path resolution for Pi-compatible runtimes
  * Zones: telemetry paths, filesystem, runtime identity
  * Owns agent-dir detection and extension-local path derivation
- *
- * 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 { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
 export const TELEGRAM_DEFAULT_PROFILE_NAME = "default";
 /**
  * Resolve the agent data directory for the current Pi-compatible runtime.
@@ -41,9 +36,13 @@ export function resolveAgentDir(input = {}) {
  * Equality proves spelling only, not file identity, consumer closure or migration readiness.
  */
 export function requireTelegramStoragePathReference(path, expectedPath) {
-    if (typeof path !== "string" || typeof expectedPath !== "string" ||
-        !isAbsolute(path) || resolve(path) !== path ||
-        !isAbsolute(expectedPath) || resolve(expectedPath) !== expectedPath || path !== expectedPath) {
+    if (typeof path !== "string" ||
+        typeof expectedPath !== "string" ||
+        !isAbsolute(path) ||
+        resolve(path) !== path ||
+        !isAbsolute(expectedPath) ||
+        resolve(expectedPath) !== expectedPath ||
+        path !== expectedPath) {
         throw new Error("Telegram storage reference does not match its approved absolute path.");
     }
     return path;
@@ -55,11 +54,12 @@ export function resolveTelegramConfigPath() {
 /**
  * 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.
+ * Relative input is returned unchanged so callers' exact-absolute-path guards still reject it. On Windows only
+ * drive-letter and UNC paths resolve; resolving a drive-less root would add the current drive.
  */
 function canonicalizeExistingPrefix(path) {
-    if (!isAbsolute(path) || process.platform === "win32")
+    if (!isAbsolute(path) ||
+        (process.platform === "win32" && !/^(?:[a-zA-Z]:[\\/]|\\\\)/u.test(path)))
         return path;
     const absolute = resolve(path);
     const missing = [];
@@ -68,7 +68,8 @@ function canonicalizeExistingPrefix(path) {
             return join(realpathSync(current), ...missing.reverse());
         }
         catch (error) {
-            if (error.code !== "ENOENT" || dirname(current) === current)
+            if (error.code !== "ENOENT" ||
+                dirname(current) === current)
                 return absolute;
             missing.push(basename(current));
         }
@@ -140,7 +141,10 @@ export function getTelegramJournalPublicationPaths(path, runtimeDir) {
     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)) };
+    return {
+        transactionPath: join(runtimeDir, `${basename(path)}.transaction`),
+        temporaryBasePath: join(runtimeDir, basename(path)),
+    };
 }
 /** Durable inactive Thread cleanup work-set journal. */
 export function resolveTelegramThreadCleanupWorkPath(agentDir = resolveAgentDir(), profileName) {
@@ -186,12 +190,17 @@ export function encodeTelegramSessionDirectoryName(sessionId) {
     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")}`;
+        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;
+    return name.length <= TELEGRAM_SESSION_DIRECTORY_MAX_LENGTH
+        ? name
+        : undefined;
 }
 /** Inverse of `encodeTelegramSessionDirectoryName`; undefined unless the name is exactly canonical. */
 export function decodeTelegramSessionDirectoryName(name) {
@@ -210,7 +219,9 @@ export function decodeTelegramSessionDirectoryName(name) {
             bytes.push(name.charCodeAt(index));
     }
     const decoded = Buffer.from(bytes).toString("utf8");
-    return encodeTelegramSessionDirectoryName(decoded) === name ? decoded : undefined;
+    return encodeTelegramSessionDirectoryName(decoded) === name
+        ? decoded
+        : undefined;
 }
 /** Root of every session folder (<agentDir>/tmp/pi-telegram/sessions). */
 export function resolveTelegramSessionsDir(agentDir = resolveAgentDir()) {
@@ -227,7 +238,10 @@ export function resolveTelegramSessionDir(sessionId, agentDir = resolveAgentDir(
 export function getTelegramRecipientJournalHash(recipientBindingKey) {
     if (!recipientBindingKey)
         throw new Error("Telegram session journal binding key is required.");
-    return createHash("sha256").update(recipientBindingKey).digest("hex").slice(0, 16);
+    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, recipientBindingKey, agentDir = resolveAgentDir(), profileName) {
@@ -240,8 +254,10 @@ export function resolveTelegramSessionPollingJournalPath(sessionId, agentDir = r
 /** Accept only a canonical `sessions/<id>/inbox[.<profile>].json` beneath this agent's runtime. */
 export function isTelegramSessionPollingJournalPath(path, agentDir = resolveAgentDir()) {
     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]);
+    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()) {

package/dist/lib/pi.d.ts

@@ -42,6 +42,8 @@ export interface PiSettingsManager {
 }
 export type PiSlashCommandInfo = SlashCommandInfo;
 export type PiRunMode = "tui" | "rpc" | "json" | "print";
+/** Pi rejects a context captured before session replacement with a stale-context error; this is not a domain failure. */
+export declare function isPiStaleContextError(error: unknown): boolean;
 export declare function getExtensionContextMode(ctx: unknown): PiRunMode | undefined;
 export declare function isExtensionContextPassiveRunMode(ctx: unknown): boolean;
 export declare function canStartPollingInExtensionContext(ctx: unknown): boolean;

package/dist/lib/pi.js

@@ -7,6 +7,12 @@ import { SettingsManager, } from "@earendil-works/pi-coding-agent";
 function isPiRunMode(value) {
     return (value === "tui" || value === "rpc" || value === "json" || value === "print");
 }
+/** Pi rejects a context captured before session replacement with a stale-context error; this is not a domain failure. */
+export function isPiStaleContextError(error) {
+    return (error instanceof Error &&
+        (error.message.includes("stale after session") ||
+            error.message.includes("stale ctx")));
+}
 export function getExtensionContextMode(ctx) {
     const mode = typeof ctx === "object" && ctx !== null
         ? ctx.mode
@@ -50,7 +56,8 @@ export function createExtensionApiRuntimePorts(api) {
 function readEnabledModels(value) {
     if (value === undefined)
         return undefined;
-    if (Array.isArray(value) && value.every((entry) => typeof entry === "string")) {
+    if (Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string")) {
         return [...value];
     }
     throw new TypeError("Host settings enabledModels must be a string array or undefined.");

package/dist/lib/polling.d.ts

@@ -225,13 +225,8 @@ export interface TelegramThreadAwarePollingPorts<TContext, TOwner> {
     restoreFollowerWithOwner: (ctx: TContext, owner: TOwner) => Promise<boolean | undefined>;
     stopFollowerRegistration: () => void;
 }
-export interface TelegramThreadAwarePollingDeps<TContext, TOwner> extends TelegramStartupThreadCapabilityProbeDeps {
-    lifecycle?: TelegramThreadCapabilityLifecycle;
-    isBusRuntimeEnabled: () => boolean;
-    isTopicModeUnavailableError: (error: unknown) => boolean;
-    getPollingStartedWithTelegramBus: () => boolean;
-    setPollingStartedWithTelegramBus: (started: boolean) => void;
-    setForceFreshLeaderThreadOnNextStart: (forceFresh: boolean) => void;
+/** Classic/leader polling and follower registration controls that thread-aware polling switches between. */
+export interface TelegramThreadAwarePollingControls<TContext, TOwner> {
     startClassicPolling: (ctx: TContext) => MaybePromise<void>;
     stopClassicPolling: () => Promise<void>;
     startBusLeaderPolling: (ctx: TContext) => Promise<void>;
@@ -242,25 +237,21 @@ export interface TelegramThreadAwarePollingDeps<TContext, TOwner> extends Telegr
     restoreFollowerWithLeader?: (ctx: TContext, owner: TOwner) => Promise<boolean | undefined>;
     hasRememberedWorkspaceBinding?: (ctx: TContext) => boolean;
     stopFollowerRegistration: () => void;
+    isBusRuntimeEnabled: () => boolean;
+    isTopicModeUnavailableError: (error: unknown) => boolean;
 }
-export interface TelegramThreadCapabilityOrchestrationDeps<TContext, TOwner> extends TelegramThreadCapabilityReaderDeps {
+export interface TelegramThreadAwarePollingDeps<TContext, TOwner> extends TelegramStartupThreadCapabilityProbeDeps, TelegramThreadAwarePollingControls<TContext, TOwner> {
+    lifecycle?: TelegramThreadCapabilityLifecycle;
+    getPollingStartedWithTelegramBus: () => boolean;
+    setPollingStartedWithTelegramBus: (started: boolean) => void;
+    setForceFreshLeaderThreadOnNextStart: (forceFresh: boolean) => void;
+}
+export interface TelegramThreadCapabilityOrchestrationDeps<TContext, TOwner> extends TelegramThreadCapabilityReaderDeps, TelegramThreadAwarePollingControls<TContext, TOwner> {
     state: TelegramThreadCapabilityStateRuntime;
     topicTargetStore: TelegramThreadCapabilityStore;
-    isBusRuntimeEnabled: () => boolean;
     ownsLock: (ctx: TContext) => boolean;
     isFollowerRegistered?: () => boolean;
-    startClassicPolling: (ctx: TContext) => MaybePromise<void>;
-    stopClassicPolling: () => Promise<void>;
-    startBusLeaderPolling: (ctx: TContext) => Promise<void>;
-    stopBusLeaderPolling: () => Promise<void>;
-    startLeaderHealth: () => void;
-    stopLeaderHealth: () => void;
-    registerFollowerWithLeader: (ctx: TContext, owner: TOwner) => Promise<boolean | undefined>;
-    restoreFollowerWithLeader?: (ctx: TContext, owner: TOwner) => Promise<boolean | undefined>;
-    hasRememberedWorkspaceBinding?: (ctx: TContext) => boolean;
     suspendLiveThreadTarget?: () => void;
-    stopFollowerRegistration: () => void;
-    isTopicModeUnavailableError: (error: unknown) => boolean;
     updateStatus: (ctx: TContext) => void;
     recordEvent: (category: string, message: unknown, details?: Record<string, unknown>) => void;
 }
@@ -308,10 +299,8 @@ export interface TelegramPollingBatchAdmissionDeps<TUpdate extends TelegramUpdat
     onPhaseChange?: (phase: TelegramPollingWorkPhase, currentUpdateId?: number) => void;
 }
 export declare function admitTelegramPollingUpdateBatch<TUpdate extends TelegramUpdate>(deps: TelegramPollingBatchAdmissionDeps<TUpdate>): Promise<TelegramPollingBatchAdmissionResult>;
-export interface TelegramPollLoopDeps<TUpdate extends TelegramUpdate, TContext = unknown> extends TelegramRuntimeEventRecorderPort {
-    ctx: TContext;
-    signal: AbortSignal;
-    config: TelegramPollingConfig;
+/** Bot API, journal and progress ports shared by one poll loop and its restartable runner. */
+export interface TelegramPollLoopTransportPorts<TUpdate extends TelegramUpdate> extends TelegramRuntimeEventRecorderPort {
     deleteWebhook: (signal: AbortSignal) => Promise<unknown>;
     getUpdates: (body: Record<string, unknown>, signal: AbortSignal) => Promise<TUpdate[]>;
     getUpdatesRequestBudgetMs?: (body: Record<string, unknown>) => number;
@@ -320,26 +309,21 @@ export interface TelegramPollLoopDeps<TUpdate extends TelegramUpdate, TContext =
     getAcceptedThroughUpdateId?: () => number | undefined;
     getJournalEntryCount: () => number;
     signalUpdateWorker: () => void;
+    onPhaseChange?: (phase: TelegramPollingWorkPhase, currentUpdateId?: number) => void;
+    onSuccessfulResponse?: (updateCount: number) => void;
+}
+export interface TelegramPollLoopDeps<TUpdate extends TelegramUpdate, TContext = unknown> extends TelegramPollLoopTransportPorts<TUpdate> {
+    ctx: TContext;
+    signal: AbortSignal;
+    config: TelegramPollingConfig;
     onErrorStatus: (message: string) => void;
     onStatusReset: () => void;
     sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
-    onPhaseChange?: (phase: TelegramPollingWorkPhase, currentUpdateId?: number) => void;
-    onSuccessfulResponse?: (updateCount: number) => void;
 }
-export interface TelegramPollLoopRunnerDeps<TUpdate extends TelegramUpdate, TContext = unknown> extends TelegramRuntimeEventRecorderPort {
+export interface TelegramPollLoopRunnerDeps<TUpdate extends TelegramUpdate, TContext = unknown> extends TelegramPollLoopTransportPorts<TUpdate> {
     getConfig: () => TelegramPollingConfig;
-    deleteWebhook: (signal: AbortSignal) => Promise<unknown>;
-    getUpdates: (body: Record<string, unknown>, signal: AbortSignal) => Promise<TUpdate[]>;
-    getUpdatesRequestBudgetMs?: (body: Record<string, unknown>) => number;
-    persistConfig: (config: TelegramPollingConfig) => Promise<void>;
-    appendUpdateBatch: (updates: readonly TUpdate[], acceptedThroughUpdateId?: number) => MaybePromise<unknown>;
-    getAcceptedThroughUpdateId?: () => number | undefined;
-    getJournalEntryCount: () => number;
-    signalUpdateWorker: () => void;
     updateStatus: (ctx: TContext, message?: string) => void;
     sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
-    onPhaseChange?: (phase: TelegramPollingWorkPhase, currentUpdateId?: number) => void;
-    onSuccessfulResponse?: (updateCount: number) => void;
 }
 export declare function sleepTelegramPollingRetry(ms: number, signal?: AbortSignal): Promise<void>;
 export declare function createTelegramPollLoopRunner<TUpdate extends TelegramUpdate, TContext = unknown>(deps: TelegramPollLoopRunnerDeps<TUpdate, TContext>): (ctx: TContext, signal: AbortSignal) => Promise<void>;