@llblab/pi-telegram 0.48.2 → 0.49.0

package/AGENTS.md

@@ -121,7 +121,7 @@ The detailed map is canonical in [`docs/architecture.md`](./docs/architecture.md
 - Command templates remain compact and shell-free. Use string leaves or ordered `template` arrays; shell operators are not an execution contract. Examples use portable executable placeholders, never machine-local paths.
 - `telegram_attach` is the canonical file path and `telegram_message` the direct Markdown text/buttons path. Both require current direct or registered-follower authority and must not replace the normal active-turn reply.
 - Inbound handlers transform text/media before queueing; outbound handlers precede programmatic/provider fallbacks. Public contracts and ordering live in `docs/inbound.md`, `docs/outbound.md`, and `docs/public-api.md`.
-- Pi integration uses public hooks and APIs. A Telegram `/new` or equivalent session replacement requires a public Pi API that executes the real terminal path.
+- Pi integration uses public hooks and APIs. Telegram `/new` is scheduled against the exact durable update, dispatched only after that update is removed from the journal, and then routed through an internal Pi command via `pi.sendUserMessage(..., { expandPromptTemplates: true })`; the command handler receives the real `ExtensionCommandContext` and calls `ctx.newSession()`. Before replacement, CAS-publish one exact expiring handoff in the profile target snapshot. `workspace-thread` successors re-key the matching Workspace binding; `classic-chat` successors preserve Profile/CWD/session/chat continuity without creating a binding or invoking topic APIs. Both atomically claim the intent before one terminal result, and the old `withSession` path never publishes the same success. Never replace the session while inbound authority is unsettled, store stale command contexts, accept an expired or mismatched handoff, inject terminal input, spawn a shadow Pi process, or mutate session files.
 
 ## 7. Engineering Conventions
 

package/BACKLOG.md

@@ -2,6 +2,7 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
+- [ ] `Unified Telegram /new continuity` (`local-actionable`, current priority; closes [#81](https://github.com/llblab/pi-telegram/issues/81)): The existing one-shot intent now has strict `workspace-thread | classic-chat` continuity. Classic preparation persists exact Profile/CWD/session/chat identity without requiring or fabricating a Workspace binding; its codec round-trip and claim path leave Workspace bindings untouched. Threaded preparation and successor re-key retain the existing slot/name path. Local implementation and docs are complete. Classic preparation-to-successor settlement passes with one terminal send and no Workspace mutation against both the same store instance and a freshly reopened process store; duplicate settlement sends nothing. Threaded re-key, mismatch, expiry, failed-claim, full-suite, invariants, and Domain DAG regressions pass under the discriminated codec. Final `dist` is rebuilt; Classic Settings also hides both Thread-specific controls rather than exposing only cleanup. Remaining: operator-authorized Classic and Threaded live smoke. Do not close or post to #81 before release authority. Both modes delete confirmation before replacement, CAS-claim before terminal send, and preserve at-most-once cross-process result semantics; do not close or post to #81 before release authority.
 - [ ] `Prompt enqueue hotfix` (`optional`, `operator-gated`): Optional nonblocking operator-authorized disposable-follower smoke: overlap delayed voice processing with turn completion and confirm one-time ordered consumption and truthful counts against the [queue contract](./docs/architecture.md#queue-and-dispatch-safety). Separately authorized supported recovery investigation remains open: prevention does not repair an already-wedged in-memory queue; establish the exact recovery path and preservation/discard consequences before mutation, otherwise report the blocker. No journal/ownership edits, replay of settled input, implicit queue clearing, or restart; live activation requires separate operator authorization.
 - [ ] `Channel multimedia posts` (`0.45.1`, live-acceptance-gated): `telegram_message` channel delivery accepts one local `.jpg`/`.jpeg`/`.png`/`.webp` photo or `.mp4` video, uploads it through the multipart transport as `sendPhoto`/`sendVideo` with `text` as the HTML caption, validates kind and size (photo ≤ 10 MiB, video ≤ 50 MiB) plus ≤ 1024 visible caption characters before issuance, and rejects unsupported types and albums instead of downgrading them to links. The channel-post journal binds kind/file name/byte size/SHA-256 and caption, so duplicate requests and lost acknowledgements never re-upload; media-post edits replace the caption through `editMessageCaption`, and Markdown spoilers render as `<tg-spoiler>`. Live image publication passed on `@llb_log`. Regressions cover confirmed publication, duplicate requests, lost ACK, pre-issuance rejection, caption edits, and reconnect replacement. Remaining: operator-authorized disposable-channel acceptance of rejected upload, duplicate request, and caption edit.
 - [ ] `Manual Thread naming` (`gated-but-preparable`, release priority): Local bot-owned `/name Name` and bare `/name` flows avoid model dispatch. One expiring exact-target input dialog immediately accepts the next valid name, always offers cancel, and offers **Reset to automatic** only while a manual override exists; duplicate/stale callbacks cannot repeat mutation. Durable manual override supersedes every automatic display mode, reset is leader/follower generation- and target-fenced, and Letters remains the default without rewriting recovery identity. Local review findings are remediated, including Bot-API-wait target-replacement regressions for leader/follower rename and reset. Remaining: disposable live acceptance for command-menu ordering, dialog, invalid input, duplicate callbacks, leader/follower rename and reset.

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ## Unreleased
 
+## 0.49.0: Unified fresh-session continuity
+
+- `/new`: Classic and Threaded Mode now share one confirmed fresh-session flow. The settled callback deletes its dialog and publishes an expiring exact-target intent; a same- or cross-process successor preserves the classic chat or re-keys the Thread/slot/name, atomically claims once, then sends one terminal result. Identity mismatches fail closed.
+- `Command menus`: Both Telegram command menus now keep the primary sequence `/start`, `/compact`, `/new`, `/continue`, `/next`; the niche `/name` command remains available but moves out of menus into the Thread display Settings guidance.
+- `Classic Settings`: Hides both Thread display and Thread cleanup controls when Threaded Mode is unavailable, rather than exposing only half of the Thread-specific surface.
+- `Thread display`: A current Thread with a manual `/name` override now appears as `custom` on the Settings row and detail heading; choosing any automatic mode clears the current Thread's override, reapplies that projection, and selects it again. Successful interactive rename/reset now settles its source before asynchronously publishing the result, so immediate `/new` cannot replay the consumed name after replacement; cancellation reports only its completed result.
+
+## 0.48.3: Assistant publication identity hotfix
+
+- `Thread restore display identity`: Restoring or reclaiming a Thread now renames the destination from its current Workspace display title when available, rather than leaking the internal baked slot name such as `Moss` into directory-title mode.
+- `Assistant publication identity`: An empty terminal assistant message may recover an earlier preserved answer, but it no longer republishes that text when the same Telegram intermediate output was already admitted; the pre-send turn fence also prevents lost-acknowledgement retries while allowing later turns.
+
 ## 0.48.2: Follower promotion recovery
 
 - `Follower promotion recovery`: A failed follower-to-leader promotion, including unavailable Thread slot authority, is now contained as a retryable bus recovery event instead of escaping a detached heartbeat recovery promise and terminating Pi.

package/README.md

@@ -164,6 +164,7 @@ Use these in the bot DM.
 | --- | --- |
 | `/start` | Pair when needed and open the main operator menu |
 | `/name [Name]` | Set a manual Thread title immediately, or open rename/reset controls when Name is omitted |
+| `/new` | Start a new Pi session in the current classic chat or Thread after confirming the bridge is idle |
 | `/compact` | Confirm and run session compaction when safe |
 | `/next` | Dispatch the next queued turn, aborting first if needed |
 | `/continue` | Enqueue a priority continuation prompt |

package/dist/lib/activity.d.ts

@@ -201,7 +201,9 @@ export interface TelegramActivityPublicationRuntime {
 export declare function createTelegramActivityPublicationRuntime(): TelegramActivityPublicationRuntime;
 export interface TelegramAssistantOutputRuntime {
     start: () => void;
+    beginTurn: () => void;
     accept: (event: TelegramAssistantSegmentEvent) => void;
+    hasAdmittedTelegramIntermediate: (text: string) => boolean;
     waitForIdle: () => Promise<void>;
     stop: () => void;
 }

package/dist/lib/activity.js

@@ -520,6 +520,7 @@ export function createTelegramAssistantOutputRuntime(deps) {
     let running = false;
     let tail = Promise.resolve();
     const admitted = new Set();
+    const admittedTelegramIntermediateText = new Set();
     const isEligibleEvent = (event) => (event.source === "telegram" && event.placement === "intermediate") ||
         event.source === "local" ||
         event.source === "autonomous" ||
@@ -529,8 +530,12 @@ export function createTelegramAssistantOutputRuntime(deps) {
             generation += 1;
             running = true;
             admitted.clear();
+            admittedTelegramIntermediateText.clear();
             tail = Promise.resolve();
         },
+        beginTurn() {
+            admittedTelegramIntermediateText.clear();
+        },
         accept(event) {
             if (!running || !isEligibleEvent(event) || !event.text.trim())
                 return;
@@ -538,6 +543,9 @@ export function createTelegramAssistantOutputRuntime(deps) {
             if (admitted.has(key))
                 return;
             admitted.add(key);
+            if (event.source === "telegram" && event.placement === "intermediate") {
+                admittedTelegramIntermediateText.add(event.text.trim());
+            }
             const admittedGeneration = generation;
             const admittedAuthority = deps.captureAuthority?.();
             const preparation = deps.prepareSend?.(event);
@@ -562,6 +570,9 @@ export function createTelegramAssistantOutputRuntime(deps) {
                 }
             }).finally(() => preparation?.settle());
         },
+        hasAdmittedTelegramIntermediate(text) {
+            return admittedTelegramIntermediateText.has(text.trim());
+        },
         waitForIdle() {
             return tail;
         },
@@ -569,6 +580,7 @@ export function createTelegramAssistantOutputRuntime(deps) {
             generation += 1;
             running = false;
             admitted.clear();
+            admittedTelegramIntermediateText.clear();
         },
     };
 }

package/dist/lib/bindings.d.ts

@@ -202,7 +202,7 @@ interface TelegramLifecycleBindingDeps {
     publicationRuntime: TelegramBridgePublicationRuntime;
     activityRuntime: Activity.TelegramActivityRuntime;
     activityVerbosityRuntime?: ActivityVerbosity.TelegramActivityVerbosityRuntime;
-    assistantOutputRuntime: Pick<Activity.TelegramAssistantOutputRuntime, "start" | "waitForIdle" | "stop">;
+    assistantOutputRuntime: Pick<Activity.TelegramAssistantOutputRuntime, "start" | "beginTurn" | "hasAdmittedTelegramIntermediate" | "waitForIdle" | "stop">;
     sessionLifecycleRuntime: Pick<Lifecycle.TelegramLifecycleRegistrationDeps, "onSessionStart" | "onSessionShutdown" | "onModelSelect">;
     configStore: Pick<Config.TelegramConfigStore, "get" | "getOutboundHandlers" | "hasBotToken" | "load">;
     abort: Runtime.TelegramRuntimeAbortPort;
@@ -216,6 +216,7 @@ interface TelegramLifecycleBindingDeps {
     deferredQueueDispatchRuntime: Queue.TelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>;
     modelContextAvailabilityRuntime: Prompts.TelegramModelContextAvailabilityRuntime;
     disconnectOnQuit?: () => Promise<unknown>;
+    onSessionStarted?: (event: Pi.SessionStartEvent, ctx: Pi.ExtensionContext) => void;
     shutdownGenerativeAppLiveSurfaces?: () => void;
     resolveAutomaticThreadCleanupEnabled?: () => boolean | Promise<boolean>;
     buttonActionStore: OutboundHandlers.TelegramButtonActionStore;
@@ -246,5 +247,5 @@ interface TelegramLifecycleBindingDeps {
     updateStatus: TelegramBridgeStatusUpdater;
     recordRuntimeEvent: TelegramRuntimeEventRecorder;
 }
-export declare function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive, isTurnTransportActive, updateStatus, recordRuntimeEvent, }: TelegramLifecycleBindingDeps): void;
+export declare function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive, isTurnTransportActive, updateStatus, recordRuntimeEvent, }: TelegramLifecycleBindingDeps): void;
 export {};

package/dist/lib/bindings.js

@@ -499,7 +499,7 @@ export function registerTelegramCommandsAndTools({ pi, agentDir, configStore, pe
         },
     });
 }
-export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive = () => true, isTurnTransportActive, updateStatus, recordRuntimeEvent, }) {
+export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime, activityRuntime, activityVerbosityRuntime, assistantOutputRuntime, sessionLifecycleRuntime, configStore, abort, typing, lifecycle, activeTurnRuntime, telegramQueueStore, modelSwitchController, previewRuntime, promptDispatchRuntime, deferredQueueDispatchRuntime, modelContextAvailabilityRuntime, disconnectOnQuit, onSessionStarted, shutdownGenerativeAppLiveSurfaces, resolveAutomaticThreadCleanupEnabled, buttonActionStore, callMultipart, sendChatAction, sendRecordVoiceAction, sendMarkdownReply, sendTextReply, dispatchNextQueuedTelegramTurn, onPromptHandedOff, answerGuestQuery, deleteMessage, sendGuestReply, editGuestReply, stopGuestPlaceholder, preparePreviewDelivery, finalizeMarkdownPreview, proactivePushTargetGetter, getAssistantRenderingMode, recordMessageOwnership, canSendAgentActivity, isSessionContextActive = () => true, isTurnTransportActive, updateStatus, recordRuntimeEvent, }) {
     const agentEndResetter = Runtime.createTelegramAgentEndResetter({
         abort,
         typing,
@@ -615,7 +615,10 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
         clearDispatchPending: lifecycle.clearDispatchPending,
         setFoldQueuedPromptsIntoHistory: lifecycle.setFoldQueuedPromptsIntoHistory,
         setActiveTurn: activeTurnRuntime.set,
-        onPromptHandedOff,
+        onPromptHandedOff: (turn, ctx) => {
+            assistantOutputRuntime.beginTurn();
+            onPromptHandedOff?.(turn, ctx);
+        },
         createPreviewState: previewRuntime.resetState,
         startTypingLoop: (ctx) => {
             const turn = activeTurnRuntime.get();
@@ -627,6 +630,7 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
         getActiveTurn: activeTurnRuntime.get,
         loadConfig: configStore.load,
         extractAssistant: Replies.extractRunAssistantMessage,
+        isRecoveredAssistantAlreadyPublished: (assistant) => !!assistant.text && assistantOutputRuntime.hasAdmittedTelegramIntermediate(assistant.text),
         getFoldQueuedPromptsIntoHistory: lifecycle.shouldFoldQueuedPromptsIntoHistory,
         resetRuntimeState: agentEndResetter,
         isSessionActive: isSessionContextActive,
@@ -751,6 +755,7 @@ export function registerTelegramLifecycleRuntimeHooks({ pi, publicationRuntime,
             activityVerbosityRuntime?.reset();
             modelContextAvailabilityRuntime.reconcile();
             await sessionLifecycleRuntime.onSessionStart(event, ctx);
+            onSessionStarted?.(event, ctx);
         },
         async onSessionShutdown(event, ctx) {
             if (!isSessionContextActive(ctx))

package/dist/lib/commands.d.ts

@@ -1,11 +1,13 @@
 /**
  * Telegram command routing helpers
  * Zones: telegram controls, pi agent commands, queue controls
- * Owns Telegram slash-command normalization, bot command metadata, and pi-side command registration behind runtime ports
+ * Owns Telegram slash-command normalization, bot command metadata, pi-side command registration, and command-initiated session replacement orchestration behind runtime ports
  */
 import { type TelegramConfigStore } from "./config.ts";
+import type * as Pi from "./pi.ts";
 import type { ExtensionAPI, ExtensionCommandContext } from "./pi.ts";
 import type { TelegramBridgeStatusLineOptions } from "./status.ts";
+import type { TelegramSessionReplacementIntent } from "./threads.ts";
 import { type PendingTelegramControlItem, type TelegramQueueAdmissionReceipt } from "./queue.ts";
 export interface ParsedTelegramCommand {
     name: string;
@@ -60,6 +62,7 @@ export declare const TELEGRAM_COMMAND_EMOJI: {
     readonly abort: "⏹️";
     readonly stop: "🟥";
     readonly name: "🏷️";
+    readonly new: "🆕";
 };
 export type TelegramCommandEmojiName = keyof typeof TELEGRAM_COMMAND_EMOJI;
 export declare function getTelegramCommandEmoji(command: TelegramCommandEmojiName): string;
@@ -144,7 +147,7 @@ export declare function createTelegramThreadDisplayNameRenameBinding(): {
 };
 export declare function parseTelegramRequestedThreadName(args: string): string | undefined;
 export declare function registerTelegramBridgeCommands(pi: ExtensionAPI, deps: TelegramBridgeCommandRegistrationDeps): void;
-export declare const TELEGRAM_RESERVED_COMMAND_NAMES: readonly ["stop", "name", "abort", "next", "continue", "status", "queue", "compact", "model", "thinking", "settings", "help", "start"];
+export declare const TELEGRAM_RESERVED_COMMAND_NAMES: readonly ["stop", "name", "new", "abort", "next", "continue", "status", "queue", "compact", "model", "thinking", "settings", "help", "start"];
 export type TelegramReservedCommandName = (typeof TELEGRAM_RESERVED_COMMAND_NAMES)[number];
 export declare function isTelegramReservedCommandName(commandName: string | undefined): commandName is TelegramReservedCommandName;
 export type TelegramCommandAction = {
@@ -156,6 +159,9 @@ export type TelegramCommandAction = {
 } | {
     kind: "name";
     executionMode: "immediate";
+} | {
+    kind: "new";
+    executionMode: "immediate";
 } | {
     kind: "abort";
     executionMode: "immediate";
@@ -192,6 +198,7 @@ export type TelegramCommandExecutionMode = "ignored" | "immediate";
 export interface TelegramCommandActionDeps<TMessage, TContext> {
     handleStop: (message: TMessage, ctx: TContext) => Promise<void>;
     handleName: (message: TMessage, ctx: TContext, name: string) => Promise<void>;
+    handleNew: (message: TMessage, ctx: TContext) => Promise<void>;
     handleAbort: (message: TMessage, ctx: TContext) => Promise<void>;
     handleNext: (message: TMessage, ctx: TContext) => Promise<void>;
     handleContinue: (message: TMessage, ctx: TContext) => Promise<void>;
@@ -264,6 +271,13 @@ export interface TelegramCompactConfirmationCallbackQuery {
         message_thread_id?: number;
     };
 }
+export interface TelegramNewConfirmationCallbackDeps<TContext> {
+    ctx: TContext;
+    answerCallbackQuery: (callbackQueryId: string, text?: string) => Promise<void>;
+    editInteractiveMessage: (chatId: number, messageId: number, text: string, mode: "markdown" | "html" | "plain", replyMarkup: TelegramCompactConfirmationReplyMarkup) => Promise<void>;
+    deleteMessage: (chatId: number, messageId: number) => Promise<void>;
+    runNew: (ctx: TContext) => Promise<void>;
+}
 export interface TelegramCompactConfirmationCallbackDeps<TContext> {
     ctx: TContext;
     answerCallbackQuery: (callbackQueryId: string, text?: string) => Promise<void>;
@@ -390,6 +404,7 @@ export interface TelegramCommandRuntimeDeps<TMessage extends TelegramCommandRunt
     }) => void;
     stopTypingLoop?: () => void;
     enqueueContinueTurn: (message: TMessage, ctx: TContext) => Promise<void>;
+    requestNewSession?: (message: TMessage) => void;
     compact: (ctx: TContext, callbacks: {
         onComplete: () => void;
         onError: (error: unknown) => void;
@@ -434,6 +449,10 @@ export declare const TELEGRAM_COMMAND_ACTIONS: {
         readonly kind: "name";
         readonly executionMode: "immediate";
     };
+    readonly new: {
+        readonly kind: "new";
+        readonly executionMode: "immediate";
+    };
     readonly abort: {
         readonly kind: "abort";
         readonly executionMode: "immediate";
@@ -515,10 +534,27 @@ export declare function handleTelegramNextCommand(deps: {
 export declare function handleTelegramContinueCommand<TMessage, TContext>(message: TMessage, ctx: TContext, deps: {
     enqueueContinueTurn: (message: TMessage, ctx: TContext) => Promise<void>;
 }): Promise<void>;
+export declare function buildTelegramNewConfirmationReplyMarkup(): TelegramCompactConfirmationReplyMarkup;
+export declare function getTelegramNewConfirmationHtml(): string;
+export declare function openTelegramNewConfirmation(target: TelegramCommandMessageTarget, deps: TelegramCompactConfirmationDeps): Promise<void>;
+export declare function handleTelegramNewConfirmationCallback<TContext>(query: TelegramCompactConfirmationCallbackQuery, deps: TelegramNewConfirmationCallbackDeps<TContext>): Promise<boolean>;
 export declare function buildTelegramCompactConfirmationReplyMarkup(): TelegramCompactConfirmationReplyMarkup;
 export declare function getTelegramCompactConfirmationHtml(): string;
 export declare function openTelegramCompactConfirmation(target: TelegramCommandMessageTarget, deps: TelegramCompactConfirmationDeps): Promise<void>;
 export declare function handleTelegramCompactConfirmationCallback<TContext>(query: TelegramCompactConfirmationCallbackQuery, deps: TelegramCompactConfirmationCallbackDeps<TContext>): Promise<boolean>;
+export interface TelegramNewCommandDeps extends TelegramRuntimeEventRecorderPort {
+    isIdle: () => boolean;
+    hasPendingMessages: () => boolean;
+    hasActiveTelegramTurn: () => boolean;
+    hasDispatchPending: () => boolean;
+    hasQueuedTelegramItems: () => boolean;
+    isCompactionInProgress: () => boolean;
+    requestNewSession?: () => void;
+    sendTextReply: (text: string, options?: {
+        parseMode?: "HTML";
+    }) => Promise<void>;
+}
+export declare function handleTelegramNewCommand(deps: TelegramNewCommandDeps): Promise<void>;
 export declare function handleTelegramCompactCommand(deps: TelegramCompactCommandDeps): Promise<void>;
 export declare function handleTelegramStatusCommand<TContext>(deps: {
     ctx: TContext;
@@ -538,4 +574,100 @@ export declare function createTelegramCommandHandler<TMessage extends TelegramCo
 export declare function createTelegramCommandOrPromptRuntime<TMessage, TContext>(deps: TelegramCommandOrPromptRuntimeDeps<TMessage, TContext>): {
     dispatchMessages: (messages: TMessage[], ctx: TContext) => Promise<void>;
 };
+export declare const TELEGRAM_SESSION_ACTION_COMMAND_NAME = "telegram-session-action";
+export declare const TELEGRAM_SESSION_ACTION_COMMAND_DESCRIPTION = "(internal) replace the current Pi session after Telegram settlement";
+export declare function delayTelegramSessionAction(delayMs: number): Promise<void>;
+export interface TelegramSessionActionRuntimeDeps {
+    registerCommand: Pi.ExtensionAPI["registerCommand"];
+    sendUserMessage: Pi.ExtensionAPI["sendUserMessage"];
+    notifyResult: (target: {
+        chatId: number;
+        threadId?: number;
+        messageId: number;
+    }, result: "success" | "cancelled" | "failure") => Promise<void>;
+    prepareReplacement?: (ctx: Pi.ExtensionCommandContext, updateId: number, target: {
+        chatId: number;
+        threadId?: number;
+        messageId: number;
+    }) => Promise<void>;
+    recordRuntimeEvent?: (category: string, error: unknown) => void;
+}
+export interface TelegramSessionReplacementSettlementDeps {
+    getIntent: () => Promise<TelegramSessionReplacementIntent | undefined>;
+    hasSuccessorContinuity: (intent: TelegramSessionReplacementIntent) => boolean;
+    editSuccess: (intent: TelegramSessionReplacementIntent) => Promise<{
+        ok: boolean;
+        retryable?: boolean;
+        message?: string;
+    }>;
+    clearIntent: (intent: TelegramSessionReplacementIntent) => Promise<boolean>;
+    profileName: string | undefined;
+    cwd: string;
+    sessionId: string;
+    now?: () => number;
+    sleep?: (delayMs: number) => Promise<void>;
+    isCurrent?: () => boolean;
+}
+export declare function settleTelegramSessionReplacement(deps: TelegramSessionReplacementSettlementDeps): Promise<"none" | "settled" | "expired" | "failed" | "stale">;
+export declare function createTelegramSessionReplacementSettlementRuntime<TContext>(deps: {
+    resolve: (ctx: TContext) => TelegramSessionReplacementSettlementDeps | undefined;
+    onResult?: (result: "none" | "settled" | "expired" | "failed" | "stale") => void;
+    onError?: (error: unknown) => void;
+}): {
+    onSessionStart: (ctx: TContext) => void;
+};
+export interface TelegramSessionActionAssemblyDeps {
+    registerCommand: Pi.ExtensionAPI["registerCommand"];
+    sendUserMessage: Pi.ExtensionAPI["sendUserMessage"];
+    store: {
+        load: () => Promise<void>;
+        refresh?: () => Promise<void>;
+        getWorkspaceBindingByTarget: (target: {
+            chatId: number;
+            threadId?: number;
+        }, sessionId?: string) => {
+            cwd: string;
+            sessionId?: string;
+            slot?: string;
+            threadName?: string;
+            manualThreadName?: string;
+            target: {
+                chatId: number;
+                threadId: number;
+            };
+        } | undefined;
+        getSessionReplacementIntent: () => TelegramSessionReplacementIntent | undefined;
+        commitSessionReplacementIntent: (intent: TelegramSessionReplacementIntent, isCurrent: () => boolean) => Promise<boolean>;
+        removeSessionReplacementIntent: (intent: TelegramSessionReplacementIntent, isCurrent: () => boolean) => Promise<boolean>;
+    };
+    getProfileName: () => string | undefined;
+    ownsPersistence: () => boolean;
+    sendResult: (target: {
+        chatId: number;
+        threadId?: number;
+    }, html: string) => Promise<{
+        ok: boolean;
+        retryable?: boolean;
+    }>;
+    handoffTtlMs: number;
+    now?: () => number;
+    recordRuntimeEvent?: (category: string, error: unknown) => void;
+}
+export declare function createTelegramSessionActionAssembly(deps: TelegramSessionActionAssemblyDeps): {
+    action: TelegramSessionActionRuntime;
+    settlement: {
+        onSessionStart: (ctx: Pi.ExtensionContext) => void;
+    };
+};
+export interface TelegramSessionActionRuntime {
+    register: () => void;
+    scheduleAfterUpdate: (updateId: number, target: {
+        chatId: number;
+        threadId?: number;
+        messageId: number;
+    }) => boolean;
+    onUpdateCompleted: (updateId: number) => void;
+    hasPending: () => boolean;
+}
+export declare function createTelegramSessionActionRuntime(deps: TelegramSessionActionRuntimeDeps): TelegramSessionActionRuntime;
 export {};