@llblab/pi-telegram 0.48.3 → 0.50.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 the single `/telegram-internal` Pi gateway via `pi.sendUserMessage(..., { expandPromptTemplates: true })`; only a runtime-armed typed action may execute, manual invocation reports that the command cannot be run manually, and the handler receives the real `ExtensionCommandContext` before calling `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.50.0: Internal lifecycle gateway and thinking cadence
+
+- `Internal lifecycle gateway`: Replaces the session-specific technical command with one `/telegram-internal` gateway for runtime-armed typed actions. Manual invocation performs no action and explains that the command cannot be run manually; settled `/new` replacement retains the same lifecycle and terminal-result guarantees.
+- `Thinking cadence`: Thinking now follows the same cadence as answer drafts: it accumulates the opening frame for two seconds, then updates at most once every two seconds while still flushing buffered reasoning when the block completes.
+
+## 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.

package/README.md

@@ -126,7 +126,7 @@ Enable the optional capabilities the bridge needs in the [@BotFather](https://t.
 | Model and thinking | Switch model or thinking level from Telegram through safe continuation flows. | Mobile control can adjust execution strategy without tearing down the current session. |
 | Compaction | Confirm `/compact`, show native active status during compaction, and preserve Telegram-owned turn semantics. | Context maintenance is visible and safe from the phone. |
 | Draft previews | Show Telegram's native `…typing` indicator whenever the connected instance is doing agent work, or enable Rich Draft previews for streamed answer text. | Local prompts, Telegram turns, and autonomous continuations remain visibly active while draft visibility stays independent from final rendering. |
-| Activity | Keep the default `verbose` technical surface, show only `thinking`, show only `tools`, or select `quiet` for answer-only delivery. Every instance reloads this shared file-backed choice before a new agent run; thinking uses a headerless expandable quote, while each tool uses one iconless closed root row containing nested evidence details. | Persistent collapsed technical activity minimizes chat height and stays bounded, redacted, target-fenced, free of URL previews, and visually separate from semantic assistant answers. |
+| Activity | Keep the default `verbose` technical surface, show only `thinking`, show only `tools`, or select `quiet` for answer-only delivery. Every instance reloads this shared file-backed choice before a new agent run; thinking accumulates for two seconds and then updates at most every two seconds in a headerless expandable quote, while each tool uses one iconless closed root row containing nested evidence details. | Persistent collapsed technical activity minimizes chat height and stays bounded, redacted, target-fenced, free of URL previews, and visually separate from semantic assistant answers. |
 | Assistant rendering | Choose Native Rich Markdown or legacy Markdown-to-HTML for final assistant replies. | Renderer compatibility is explicit instead of being conflated with draft previews. |
 | Bridge UI rendering | Render thinking through headerless expandable HTML with inline emphasis/code, render each tool as an iconless native Rich root details tree with immediately visible arguments and collapsed secondary evidence, and keep menus, queue controls, status, settings, diagnostics, and sections on Telegram HTML/plain UI. | Harness-owned surfaces remain operationally predictable and visually distinct from model-authored answers. |
 | Inbound files | Download inbound files to the Pi agent temp directory with size limits. | Screenshots, PDFs, datasets, and artifacts enter Pi as inspectable local files. |
@@ -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-verbosity.d.ts

@@ -11,7 +11,7 @@ export declare const TELEGRAM_ACTIVITY_MESSAGE_MAX_CHARS = 3900;
 export declare const TELEGRAM_ACTIVITY_MESSAGE_MAX_TOOLS = 6;
 export declare const TELEGRAM_REASONING_MESSAGE_MAX_FRAMES = 24;
 export declare const TELEGRAM_REASONING_BUFFER_MAX_CHARS = 1200;
-export declare const TELEGRAM_REASONING_MIN_INTERVAL_MS = 1200;
+export declare const TELEGRAM_REASONING_MIN_INTERVAL_MS = 2000;
 export declare const TELEGRAM_TOOL_UPDATE_MAX_ENTRIES = 4;
 interface ToolActivity {
     id: string;
@@ -41,6 +41,8 @@ export declare function createTelegramActivityVerbosityRuntime<TAuthority>(deps:
     getActivityMode: () => "quiet" | "thinking" | "tools" | "verbose";
     refreshActivityMode?: () => Promise<void>;
     getNowMs?: () => number;
+    setReasoningTimeout?: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+    clearReasoningTimeout?: (timer: ReturnType<typeof setTimeout>) => void;
     resolveTarget: (event: TelegramActivityEvent) => TelegramTarget | undefined;
     captureAuthority: () => TAuthority;
     isAuthorityActive: (authority: TAuthority) => boolean;

package/dist/lib/activity-verbosity.js

@@ -9,7 +9,9 @@ export const TELEGRAM_ACTIVITY_MESSAGE_MAX_CHARS = 3_900;
 export const TELEGRAM_ACTIVITY_MESSAGE_MAX_TOOLS = 6;
 export const TELEGRAM_REASONING_MESSAGE_MAX_FRAMES = 24;
 export const TELEGRAM_REASONING_BUFFER_MAX_CHARS = 1_200;
-export const TELEGRAM_REASONING_MIN_INTERVAL_MS = 1_200;
+// Match native answer drafts: accumulate the opening frame for one full
+// interval, then publish at most one updated frame per interval.
+export const TELEGRAM_REASONING_MIN_INTERVAL_MS = 2_000;
 export const TELEGRAM_TOOL_UPDATE_MAX_ENTRIES = 4;
 function targetEquals(left, right) {
     return left.chatId === right.chatId && left.threadId === right.threadId;
@@ -234,10 +236,18 @@ export function createTelegramActivityVerbosityRuntime(deps) {
     let reasoningMessage;
     let reasoningBlocked = false;
     let lastReasoningPublishMs = 0;
+    let reasoningFlushTimer;
     let toolMessage;
     const tools = new Map();
     const toolOrder = [];
+    const clearReasoningFlushTimer = () => {
+        if (!reasoningFlushTimer)
+            return;
+        (deps.clearReasoningTimeout ?? clearTimeout)(reasoningFlushTimer);
+        reasoningFlushTimer = undefined;
+    };
     const clearActivity = () => {
+        clearReasoningFlushTimer();
         activityId = undefined;
         authority = undefined;
         target = undefined;
@@ -330,6 +340,30 @@ export function createTelegramActivityVerbosityRuntime(deps) {
             deps.recordFailure?.(canEdit ? "reasoning-edit" : "reasoning-send", event, error);
         }
     };
+    const scheduleReasoningPublish = (event, acceptedGeneration) => {
+        if (reasoningFlushTimer || reasoningBlocked)
+            return;
+        const elapsed = reasoningMessageFrames === 0
+            ? 0
+            : getNowMs() - lastReasoningPublishMs;
+        const delayMs = Math.max(0, TELEGRAM_REASONING_MIN_INTERVAL_MS - elapsed);
+        const schedule = deps.setReasoningTimeout ?? setTimeout;
+        reasoningFlushTimer = schedule(() => {
+            reasoningFlushTimer = undefined;
+            const admittedAuthority = authority;
+            const task = async () => {
+                if (!isCurrent(acceptedGeneration, admittedAuthority) ||
+                    reasoningChars <= lastReasoningMessageChars)
+                    return;
+                await publishReasoning(event, acceptedGeneration);
+            };
+            const enqueue = deps.enqueue ?? ((next) => tail.then(next));
+            tail = enqueue(task).catch((error) => {
+                deps.recordFailure?.("reasoning-send", event, error);
+            });
+        }, delayMs);
+        reasoningFlushTimer?.unref?.();
+    };
     const publishTool = async (event, tool, acceptedGeneration) => {
         const admittedAuthority = authority;
         if (!isCurrent(acceptedGeneration, admittedAuthority) || !target) {
@@ -461,12 +495,8 @@ export function createTelegramActivityVerbosityRuntime(deps) {
                 return;
             reasoningChars += event.delta.length;
             reasoningBuffer = `${reasoningBuffer}${event.delta}`.slice(-TELEGRAM_REASONING_BUFFER_MAX_CHARS);
-            if (reasoningMessageFrames < TELEGRAM_REASONING_MESSAGE_MAX_FRAMES &&
-                (reasoningMessageFrames === 0 ||
-                    (getNowMs() - lastReasoningPublishMs >=
-                        TELEGRAM_REASONING_MIN_INTERVAL_MS &&
-                        reasoningChars - lastReasoningMessageChars >= 160))) {
-                await publishReasoning(event, acceptedGeneration);
+            if (reasoningMessageFrames < TELEGRAM_REASONING_MESSAGE_MAX_FRAMES) {
+                scheduleReasoningPublish(event, acceptedGeneration);
             }
             return;
         }
@@ -477,6 +507,7 @@ export function createTelegramActivityVerbosityRuntime(deps) {
                 reasoningChars = event.text.length;
                 reasoningBuffer = event.text.slice(-TELEGRAM_REASONING_BUFFER_MAX_CHARS);
             }
+            clearReasoningFlushTimer();
             if (reasoningChars > 0 &&
                 reasoningChars > lastReasoningMessageChars &&
                 !reasoningBlocked) {
@@ -550,8 +581,8 @@ export function createTelegramActivityVerbosityRuntime(deps) {
             return;
         }
         if (event.type === "agent-end" || event.type === "agent-settled") {
-            if (reasoningMessage &&
-                reasoningChars > lastReasoningMessageChars &&
+            clearReasoningFlushTimer();
+            if (reasoningChars > lastReasoningMessageChars &&
                 !reasoningBlocked) {
                 await publishReasoning(event, acceptedGeneration);
             }

package/dist/lib/bindings.d.ts

@@ -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,
@@ -755,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,101 @@ 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_INTERNAL_COMMAND_NAME = "telegram-internal";
+export declare const TELEGRAM_INTERNAL_COMMAND_DESCRIPTION = "(internal) dispatch one settled Telegram lifecycle action";
+export declare const TELEGRAM_INTERNAL_MANUAL_USE_MESSAGE = "This internal Telegram command cannot be run manually.";
+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 {};