@llblab/pi-telegram 0.16.1 → 0.16.3

package/CHANGELOG.md

@@ -1,8 +1,16 @@
 # Changelog
 
-## Unreleased
+## 0.16.3: Ownership And Shutdown Hotfix
 
-No open changes.
+- `[Ownership]` Lock-gated proactive local/headless final-result push so only the current `/telegram-connect` owner can send non-Telegram agent-end replies to the paired chat, while accepted Telegram turns and queued work still finalize session-locally after polling ownership moves away. Impact: child/headless/non-owner instances no longer leak unrelated local results into Telegram.
+- `[Shutdown]` Made polling retry sleep abort-aware, `unref()`ed non-critical Telegram housekeeping timers, and routed registered session shutdown through the composed lifecycle runtime so session context cleanup runs with queue and polling cleanup. Impact: shutdown and print/headless runs are less likely to stay alive on retry/debounce/typing/preview timers, and direct-delivery ownership context is cleared at the session boundary.
+- `[Tests]` Added regressions for inherited child lock refusal, child-process no-poll ownership, child-process direct-tool non-owner refusal, proactive owner/non-owner/stale/off states, queued dispatch after lock movement, abort-during-retry polling sleep, process-level session shutdown, and real `pi -p` exit/no-leak paths with a local custom provider. Impact: the cross-instance ownership, queue, and shutdown contracts are pinned from unit coverage through CLI smoke coverage.
+- `[Status]` Changed `/telegram-status` bot identity fallback from `not configured` to `unknown` when a bot token exists but the bot username is absent. Impact: live sessions that are paired and polling no longer look unconfigured only because identity metadata is missing.
+- `[Docs]` Documented ownership, proactive-push, timer/shutdown, and multi-extension prompt-boundary contracts in README and `/docs`. Impact: companion extensions get clearer boundaries without adding a core question/prompt-mirroring API.
+
+## 0.16.2: Screenshot Refresh Hotfix
+
+- `[Docs]` Refreshed the package screenshot. Impact: npm and repository previews show the current Telegram bridge UI without changing runtime behavior.
 
 ## 0.16.1: Disconnected Queue Status Hotfix
 

package/README.md

@@ -47,7 +47,7 @@ Paste your bot token when prompted. If a bot token is already saved in `~/.pi/ag
 /telegram-connect
 ```
 
-The adapter is session-local: only one π instance polls Telegram at a time. `/telegram-connect` records only external control/polling ownership in `~/.pi/agent/locks.json`; live ownership moves require confirmation, while `/new` and same-`cwd` restarts resume automatically. Local queue and reply state stay per Pi instance, so an instance that loses Telegram control still finishes work it already accepted.
+The adapter is session-local: only one π instance polls Telegram at a time. `/telegram-connect` records only external control/polling ownership in `~/.pi/agent/locks.json`; live ownership moves require confirmation, inherited child sessions do not start polling unless they take ownership, and `/new` plus same-`cwd` restarts resume automatically. Local queue and reply state stay per Pi instance, so an instance that loses Telegram control still finishes work it already accepted.
 
 ### 4. Pair your Telegram account
 
@@ -215,7 +215,7 @@ Import `registerTelegramSection()` from `@llblab/pi-telegram/sections` and retur
 
 ### Proactive push
 
-`telegram.json` can set `proactivePush: true` to send successful local non-Telegram final replies to the paired Telegram chat when no Telegram turn is active. Local prompt text is not mirrored because the bot does not own terminal user messages. The mode is off by default and can be toggled from settings.
+`telegram.json` can set `proactivePush: true` to send successful local non-Telegram final replies to the paired Telegram chat when no Telegram turn is active and this π instance currently owns `/telegram-connect`. Non-owners skip proactive delivery instead of pushing unrelated local/headless results through a bot they no longer control. Local prompt text is not mirrored because the bot does not own terminal user messages. The mode is off by default and can be toggled from settings.
 
 ### Time context
 

package/docs/architecture.md

@@ -88,10 +88,12 @@ Telegram configuration lives in `~/.pi/agent/telegram.json`. Polling ownership l
 - `/telegram-connect` acquires or moves singleton polling ownership before polling starts.
 - `/telegram-disconnect` stops polling and releases ownership.
 - Session start resumes polling only when the existing lock already points at the current `pid`/`cwd`, or when a stale same-`cwd` lock can be safely replaced after process restart.
+- Inherited child sessions that see the same `telegram.json` but do not own the `pid`/`cwd` lock must not auto-start polling or call `getUpdates` unless the operator force-takes ownership.
 - Session replacement suspends polling/watchers without releasing ownership so the next session-start hook in the same process can resume.
 - Live polling owners require explicit takeover confirmation.
 - Long-lived polling timers use snapshotted ownership context and stop local polling when the lock no longer points at their own process.
 - `locks.json` owns only external Telegram control/polling. Local extension and queue state are per Pi instance: losing the lock stops live Telegram control here, but does not drain or silence this instance's accepted queue, previews, final delivery, or dispatch.
+- Proactive local/headless final-result push is not accepted-turn delivery. It is allowed only when proactive push is enabled and this instance currently owns the Telegram lock.
 
 Deleting `locks.json` resets runtime ownership without deleting Telegram configuration.
 
@@ -159,7 +161,7 @@ Queued controls:
 - Prompt-template commands expand Telegram-safe π template aliases before entering the prompt queue.
 - Model-switch continuation uses the control lane when an in-flight Telegram-owned run must be stopped and resumed.
 
-UI label, navigation, tab, toggle, card, and dialog rules are defined in [UI Style](./ui-style.md). Callback prefix ownership is defined in [Callback Namespaces](./callback-namespaces.md).
+Queue and menu mutations are reachable through Telegram updates handled by the current polling owner. After ownership moves, the old instance keeps processing its accepted local queue, but it no longer receives new menu callbacks or control updates for remote mutation. UI label, navigation, tab, toggle, card, and dialog rules are defined in [UI Style](./ui-style.md). Callback prefix ownership is defined in [Callback Namespaces](./callback-namespaces.md).
 
 ### Compaction And Typing Status
 
@@ -215,6 +217,8 @@ Unknown callback data outside owned prefixes is forwarded as `[callback] <data>`
 
 Extension callbacks must avoid `pi-telegram` owned prefixes such as `compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, and `section:`. Workflow-specific Telegram slash commands should use the public command registry instead of becoming new core built-ins unless they are bridge lifecycle, transport ownership, queue safety, or essential operator controls.
 
+The bridge does not mirror arbitrary `ctx.ui.confirm/input/select/custom` prompts from other extensions into Telegram. Companion extensions that need Telegram operation should expose a Telegram-native command, section, settings row, callback, status line, inbound/update handler, or assistant action-markup path instead of relying on hidden TUI-only prompts.
+
 ## Diagnostics And Operational Behavior
 
 Status rendering distinguishes connected, active, dispatching, queued, tool-running, model-switching, and compacting states. If a queue mutation removes the last waiting item while Telegram-owned work still has running tools, status remains active instead of degrading to connected.
@@ -223,7 +227,7 @@ Queue reactions are shortcut controls for waiting turns. Promotion reactions (`
 
 `/telegram-status` records grouped diagnostics for transport/API, polling/update, prompt dispatch, controls, typing, compaction, setup, session lifecycle, attachment queue/delivery, and recent redacted runtime events. Expected preview noise such as unchanged edit responses is filtered out.
 
-When proactive push is enabled, successful local non-Telegram final replies are sent to the paired chat. Local prompt text is not mirrored because the bot does not own terminal user messages.
+When proactive push is enabled and this instance owns the Telegram lock, successful local non-Telegram final replies are sent to the paired chat. Non-owners skip proactive delivery and record a runtime diagnostic. Local prompt text is not mirrored because the bot does not own terminal user messages.
 
 Telegram prompt guidance asks assistants to keep dense mobile-visible text around 37 display cells where possible, because emoji and wide Unicode make raw character counts misleading.
 
@@ -238,6 +242,14 @@ When `/model` is used during an active Telegram-owned run, the bridge can emulat
 
 This is limited to Telegram-owned runs. If π is busy with non-Telegram work, the bridge refuses the switch instead of hijacking unrelated activity.
 
+## Shutdown And Timer Lifecycle
+
+`session_shutdown` is the hard boundary for session-bound runtime work. It suspends Telegram polling through the locked polling runtime, aborts the poll controller, stops native typing, unbinds deferred queue dispatch, clears pending media/text-group input, clears preview state, clears active turns, and drops the active abort handler.
+
+Non-critical timers are `unref()`ed so print/headless processes are not kept alive only by Telegram housekeeping. This includes typing keepalive intervals, bounded typing-idle waits, deferred queue dispatch, media/text-group debounce windows, preview flush timers, and polling retry sleeps. Polling retry sleep is abort-aware, so shutdown does not wait for the normal retry delay after a polling error.
+
+Non-interactive `pi -p` runs must remain passive unless π provides a live Telegram session lifecycle. Loading the extension with `telegram.json`, proactive push settings, or existing lock state must not by itself keep the print-mode process alive or let a non-owner send proactive Telegram output.
+
 ## Related
 
 - [README.md](../README.md)

package/docs/locks.md

@@ -123,7 +123,7 @@ Avoid repeating the extension name in the body. Color is encouraged: extension t
 
 The previous owner may use `fs.watch`, mtime polling, or an existing status/timer tick. Long-lived watchers should compare against a snapshotted `pid`/`cwd` identity rather than a live pi context object, because session replacement such as `/new` makes captured contexts stale. The important contract is graceful singleton-runtime shutdown after ownership mismatch while session-local state that does not require polling remains owned by its original instance.
 
-For `pi-telegram`, direct local/TUI delivery tools (`telegram_message` and no-active-turn `telegram_attach`) are singleton-controlled and require current `/telegram-connect` ownership. They must fail when the lock is inactive or active elsewhere. Already accepted Telegram-turn reply delivery, previews, queued attachments, and queue finalization remain session-local and may complete after polling ownership moves away.
+For `pi-telegram`, direct local/TUI delivery tools (`telegram_message` and no-active-turn `telegram_attach`) and proactive local/headless final-result push are singleton-controlled and require current `/telegram-connect` ownership. They must fail or skip delivery when the lock is inactive or active elsewhere. Already accepted Telegram-turn reply delivery, previews, queued attachments, and queue finalization remain session-local and may complete after polling ownership moves away.
 
 ## Reset
 

package/index.ts

@@ -452,7 +452,6 @@ export default function (pi: Pi.ExtensionAPI) {
       ...sessionLifecycleRuntime,
       onModelSelect: currentModelRuntime.onModelSelect,
     },
-    queueSessionLifecycle,
     configStore,
     abort,
     typing,

package/lib/bindings.ts

@@ -113,10 +113,6 @@ interface TelegramLifecycleBindingDeps {
     Lifecycle.TelegramLifecycleRegistrationDeps,
     "onSessionStart" | "onSessionShutdown" | "onModelSelect"
   >;
-  queueSessionLifecycle: Pick<
-    Lifecycle.TelegramLifecycleRegistrationDeps,
-    "onSessionShutdown"
-  >;
   configStore: Pick<Config.TelegramConfigStore, "getOutboundHandlers">;
   abort: Runtime.TelegramRuntimeAbortPort;
   typing: Runtime.TelegramRuntimeTypingPort;
@@ -190,7 +186,6 @@ interface TelegramLifecycleBindingDeps {
 export function registerTelegramLifecycleRuntimeHooks({
   pi,
   sessionLifecycleRuntime,
-  queueSessionLifecycle,
   configStore,
   abort,
   typing,
@@ -283,6 +278,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     sendOutboundReplyArtifacts: outboundReplyArtifactSender,
     getDefaultChatId: proactivePushChatIdGetter,
     isProactivePushEnabled,
+    canSendProactivePush: lockOwnershipGuard.ownsContext,
     recordRuntimeEvent,
     getActiveToolExecutions: lifecycle.getActiveToolExecutions,
     setActiveToolExecutions: lifecycle.setActiveToolExecutions,
@@ -315,7 +311,7 @@ export function registerTelegramLifecycleRuntimeHooks({
     ...agentLifecycleHooks,
     async onSessionShutdown(event, ctx) {
       compactionObserver.onSessionShutdown();
-      await queueSessionLifecycle.onSessionShutdown(event, ctx);
+      await sessionLifecycleRuntime.onSessionShutdown(event, ctx);
     },
     onSessionBeforeCompact: compactionObserver.onSessionBeforeCompact,
     onSessionCompact: compactionObserver.onSessionCompact,

package/lib/media.ts

@@ -299,6 +299,7 @@ export function queueTelegramMediaGroupMessage<
     if (!state) return;
     options.dispatchMessages(state.messages, state.context);
   }, options.debounceMs);
+  existing.flushTimer.unref?.();
   options.groups.set(key, existing);
   return true;
 }

package/lib/polling.ts

@@ -261,7 +261,7 @@ export interface TelegramPollLoopDeps<
   handleUpdate: (update: TUpdate, ctx: TContext) => Promise<void>;
   onErrorStatus: (message: string) => void;
   onStatusReset: () => void;
-  sleep: (ms: number) => Promise<void>;
+  sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
   maxUpdateFailures?: number;
 }
 
@@ -278,22 +278,42 @@ export interface TelegramPollLoopRunnerDeps<
   persistConfig: () => Promise<void>;
   handleUpdate: (update: TUpdate, ctx: TContext) => Promise<void>;
   updateStatus: (ctx: TContext, message?: string) => void;
-  sleep?: (ms: number) => Promise<void>;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
   maxUpdateFailures?: number;
 }
 
+export function sleepTelegramPollingRetry(
+  ms: number,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (ms <= 0 || signal?.aborted) return Promise.resolve();
+  return new Promise<void>((resolve) => {
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout>;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    };
+    const onAbort = () => {
+      clearTimeout(timer);
+      finish();
+    };
+    timer = setTimeout(finish, ms);
+    timer.unref?.();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+  });
+}
+
 export function createTelegramPollLoopRunner<
   TUpdate extends TelegramUpdate,
   TContext = unknown,
 >(
   deps: TelegramPollLoopRunnerDeps<TUpdate, TContext>,
 ): (ctx: TContext, signal: AbortSignal) => Promise<void> {
-  const sleep =
-    deps.sleep ??
-    ((ms: number) =>
-      new Promise<void>((resolve) => {
-        setTimeout(resolve, ms);
-      }));
+  const sleep = deps.sleep ?? sleepTelegramPollingRetry;
   return (ctx, signal) =>
     runTelegramPollLoop({
       ctx,
@@ -393,7 +413,8 @@ export async function runTelegramPollLoop<
         deps.recordRuntimeEvent?.("polling", error, { phase: "loop" });
       }
       deps.onErrorStatus(getTelegramPollingErrorMessage(error));
-      await deps.sleep(3000);
+      await deps.sleep(3000, deps.signal);
+      if (deps.signal.aborted) return;
       deps.onStatusReset();
     }
   }

package/lib/preview.ts

@@ -467,6 +467,7 @@ export function createTelegramPreviewController<
       state.flushTimer = setTimer(() => {
         void flushTelegramPreview(chatId, getRuntimeDeps());
       }, throttleMs);
+      state.flushTimer.unref?.();
     },
     finalize: (chatId, replyToMessageId) =>
       finalizeTelegramPreview(chatId, getRuntimeDeps(replyToMessageId)),

package/lib/queue.ts

@@ -842,6 +842,7 @@ export interface TelegramAgentEndRuntimeDeps<
   ) => Promise<void>;
   getDefaultChatId?: () => number | undefined;
   isProactivePushEnabled?: () => boolean;
+  canSendProactivePush?: () => boolean;
   recordRuntimeEvent?: (
     category: string,
     error: unknown,
@@ -888,6 +889,7 @@ export interface TelegramAgentEndHookRuntimeDeps<
   sendOutboundReplyArtifacts?: TelegramAgentEndRuntimeDeps<TTurn>["sendOutboundReplyArtifacts"];
   getDefaultChatId?: TelegramAgentEndRuntimeDeps<TTurn>["getDefaultChatId"];
   isProactivePushEnabled?: TelegramAgentEndRuntimeDeps<TTurn>["isProactivePushEnabled"];
+  canSendProactivePush?: (ctx: TContext) => boolean;
   recordRuntimeEvent?: TelegramAgentEndRuntimeDeps<TTurn>["recordRuntimeEvent"];
 }
 
@@ -980,6 +982,7 @@ export function createTelegramAgentEndHook<
   ): Promise<void> {
     const turn = deps.getActiveTurn();
     const proactiveEnabled = deps.isProactivePushEnabled?.() ?? false;
+    const canProactivePush = deps.canSendProactivePush?.(ctx) ?? false;
     await handleTelegramAgentEndRuntime({
       turn,
       assistant:
@@ -1005,6 +1008,7 @@ export function createTelegramAgentEndHook<
       sendOutboundReplyArtifacts: deps.sendOutboundReplyArtifacts,
       getDefaultChatId: deps.getDefaultChatId,
       isProactivePushEnabled: deps.isProactivePushEnabled,
+      canSendProactivePush: () => canProactivePush,
       recordRuntimeEvent: deps.recordRuntimeEvent,
     });
   };
@@ -1057,20 +1061,26 @@ export async function handleTelegramAgentEndRuntime<
     foldQueuedPromptsIntoHistory: deps.foldQueuedPromptsIntoHistory,
   });
   if (!turn) {
-    if (
-      deps.isProactivePushEnabled?.() &&
-      finalText &&
-      !assistant.errorMessage
-    ) {
-      const defaultChatId = deps.getDefaultChatId?.();
-      if (defaultChatId !== undefined) {
-        try {
-          await deps.sendMarkdownReply(defaultChatId, undefined, finalText);
-        } catch (error) {
-          deps.recordRuntimeEvent?.("proactive-push", error, {
-            chatId: defaultChatId,
-          });
+    const proactiveEnabled = deps.isProactivePushEnabled?.() ?? false;
+    const canProactivePush = deps.canSendProactivePush?.() ?? false;
+    if (proactiveEnabled && finalText && !assistant.errorMessage) {
+      if (canProactivePush) {
+        const defaultChatId = deps.getDefaultChatId?.();
+        if (defaultChatId !== undefined) {
+          try {
+            await deps.sendMarkdownReply(defaultChatId, undefined, finalText);
+          } catch (error) {
+            deps.recordRuntimeEvent?.("proactive-push", error, {
+              chatId: defaultChatId,
+            });
+          }
         }
+      } else {
+        deps.recordRuntimeEvent?.(
+          "proactive-push",
+          new Error("Proactive push skipped because this instance does not own Telegram polling."),
+          { phase: "ownership" },
+        );
       }
     }
     if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
@@ -1802,6 +1812,7 @@ export function createTelegramDeferredQueueDispatchRuntime<TContext = unknown>(
           return;
         dispatchNextQueuedTelegramTurn(boundContext);
       }, delayMs);
+      timer.unref?.();
       timers.add(timer);
     },
   };

package/lib/runtime.ts

@@ -406,6 +406,7 @@ export function startTelegramTypingLoop(
   };
   sendTyping();
   state.typingInterval = setInterval(sendTyping, deps.intervalMs);
+  state.typingInterval.unref?.();
   return true;
 }
 
@@ -431,7 +432,8 @@ export async function waitForTelegramTypingLoopIdle(
   await Promise.race([
     inFlight,
     new Promise<void>((resolve) => {
-      setTimeout(resolve, timeoutMs);
+      const timer = setTimeout(resolve, timeoutMs);
+      timer.unref?.();
     }),
   ]);
 }

package/lib/status.ts

@@ -104,6 +104,7 @@ export interface TelegramRuntimeEventRecorderOptions {
 }
 
 export interface TelegramBridgeStatusLineState {
+  hasBotToken?: boolean;
   botUsername?: string;
   allowedUserId?: number;
   lockState?: string;
@@ -488,6 +489,7 @@ export function createTelegramBridgeStatusRuntime<
     getBridgeStatusLineState: () => {
       const config = deps.getConfig();
       return {
+        hasBotToken: Boolean(config.botToken),
         botUsername: config.botUsername,
         allowedUserId: config.allowedUserId,
         lockState: deps.getRuntimeLockState?.(),
@@ -552,6 +554,13 @@ export function buildTelegramStatusBarText(
   return `${label} ${theme.fg("success", "connected")}`;
 }
 
+function formatTelegramBridgeBotStatus(
+  state: Pick<TelegramBridgeStatusLineState, "hasBotToken" | "botUsername">,
+): string {
+  if (state.botUsername) return `@${state.botUsername}`;
+  return state.hasBotToken ? "unknown" : "not configured";
+}
+
 export function buildTelegramBridgeStatusLines(
   state: TelegramBridgeStatusLineState,
 ): string[] {
@@ -566,7 +575,7 @@ export function buildTelegramBridgeStatusLines(
   ).length;
   return [
     "connection:",
-    `- bot: ${state.botUsername ? `@${state.botUsername}` : "not configured"}`,
+    `- bot: ${formatTelegramBridgeBotStatus(state)}`,
     `- allowed user: ${state.allowedUserId ?? "not paired"}`,
     ...(state.lockState ? [`- owner: ${state.lockState}`] : []),
     "",

package/lib/text-groups.ts

@@ -132,6 +132,7 @@ export function queueTelegramTextGroupMessage<
     if (!queued || queued.context === undefined) return;
     options.dispatchMessages(queued.messages, queued.context);
   }, options.debounceMs);
+  state.flushTimer.unref?.();
   options.groups.set(key, state);
   return true;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "private": false,
   "publishConfig": {
     "access": "public"