@llblab/pi-telegram 0.56.0 → 0.56.1

package/dist/lib/routing.js

@@ -584,6 +584,20 @@ export function createTelegramLiveRebindCoordinator(input) {
                 }
                 : undefined;
         },
+        /** Observe only an already-issued leader command; never prepares, relocates or executes input. */
+        observeCommandCompletion() {
+            if (!continuationIssued || !leader?.complete)
+                return undefined;
+            if (!current())
+                return "unknown";
+            try {
+                return observeCommandCompletion();
+            }
+            catch (error) {
+                input.recordRuntimeEvent?.("telegram", error, { phase: "live-rebind-command-observation" });
+                return "unknown";
+            }
+        },
         async advance() {
             if (advancing || !current())
                 return "protected";
@@ -3100,7 +3114,7 @@ export function createTelegramInboundRouteRuntime(deps) {
                 Bus.isSameTelegramBusFollowerRegistration(live, follower) &&
                 [
                     ...Bus.TELEGRAM_BUS_LIVE_REBIND_CAPABILITIES,
-                    ...(heldSelected ? Bus.TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES : []),
+                    ...(heldSelected ? Bus.getTelegramBusHeldCommandCapabilities(heldSelected.name) : []),
                 ].every((cap) => Bus.hasTelegramBusCapability(live.protocol, cap)) &&
                 !!live.target &&
                 live.target.chatId === binding.target.chatId &&
@@ -3653,6 +3667,7 @@ export function createTelegramInboundRouteRuntime(deps) {
         return {
             operationId: request.operationId,
             selectedCommandReference: () => coordinator?.selectedCommandReference(),
+            observeCommandCompletion: () => coordinator?.observeCommandCompletion(),
             async advance() {
                 if (!coordinator) {
                     if (!current() || !getRecipient())
@@ -6184,6 +6199,52 @@ export function createTelegramInboundRouteRuntime(deps) {
                 const operationId = selection.coordinator.operationId;
                 if (current())
                     outcome = await selection.coordinator.advance();
+                const completionTimeoutMs = deps.liveRebindCommandCompletionTimeoutMs ?? 0;
+                if (outcome === "unknown" && !selection.commandCompletionWaited && selection.record.owner?.kind === "leader" &&
+                    (selection.helpCommand || selection.menuCommand || selection.abortCommand || selection.nextCommand || selection.stopCommand) &&
+                    Number.isFinite(completionTimeoutMs) && completionTimeoutMs > 0 &&
+                    selection.coordinator.observeCommandCompletion() !== undefined) {
+                    selection.commandCompletionWaited = true;
+                    const coordinator = selection.coordinator;
+                    const signal = Updates.getTelegramUpdateExecutionFence(query)?.signal;
+                    outcome = await new Promise((resolve) => {
+                        let settled = false;
+                        const subscriptions = [];
+                        const finish = (result) => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            clearTimeout(timer);
+                            for (const unsubscribe of subscriptions)
+                                unsubscribe();
+                            signal?.removeEventListener("abort", abort);
+                            resolve(result);
+                        };
+                        const abort = () => finish("unknown");
+                        const observe = () => {
+                            if (settled)
+                                return;
+                            if (!current()) {
+                                finish("unknown");
+                                return;
+                            }
+                            if (coordinator.observeCommandCompletion() === "released")
+                                finish("released");
+                        };
+                        const timer = setTimeout(abort, completionTimeoutMs);
+                        timer.unref?.();
+                        for (const message of selection.messages) {
+                            const unsubscribe = Updates.subscribeTelegramDeferredSourceCompletion(message, observe);
+                            if (unsubscribe)
+                                subscriptions.push(unsubscribe);
+                        }
+                        signal?.addEventListener("abort", abort, { once: true });
+                        if (signal?.aborted || !current())
+                            abort();
+                        else if (coordinator.observeCommandCompletion() === "released")
+                            finish("released");
+                    });
+                }
                 // Cleanup readiness follows the canonical released row, not source disposal: a detached command ACK may
                 // still be pending while every attempt samples current work afresh.
                 const row = outcome === "protected"

package/dist/lib/sync.js

@@ -6,7 +6,7 @@
 import { getTelegramTargetKey } from "./target.js";
 import { getTelegramApiErrorRequestTarget, isTelegramStaleTargetHttpError, } from "./telegram-api.js";
 import * as ThreadReconciler from "./thread-reconciler.js";
-import { commitTelegramWorkspaceProvisionBinding, createTelegramCleanupTargetProtection, getTelegramTargetFromApiBody, getTelegramThreadOwnerKey, isSameTelegramProcessInstance, isTelegramTopicTargetStaleError, provisionOwnBusTopic, } from "./threads.js";
+import { commitTelegramWorkspaceProvisionBinding, createTelegramCleanupTargetProtection, getTelegramTargetFromApiBody, getTelegramThreadOwnerKey, isSameTelegramProcessInstance, isTelegramTopicTargetStaleError, provisionOwnBusTopic, resetTelegramConnectionProvisioning, } from "./threads.js";
 import { createTelegramWorkspaceAdmissionOperationId, runWithTelegramWorkspaceAdmissionsAsync, } from "./workspace-admission.js";
 import { normalizeTelegramWorkspacePath } from "./workspace-identity.js";
 import { TelegramWorkspaceSlotUnavailableError } from "./workspace-slots.js";
@@ -463,11 +463,21 @@ export async function ensureTelegramLeaderThreadBinding(deps) {
         ...(deps.telegramProfile ? { telegramProfile: deps.telegramProfile } : {}),
     };
     const leaderProfileKey = getTelegramThreadOwnerKey(leaderOwner);
+    if (deps.forceFreshUnnamed) {
+        await resetTelegramConnectionProvisioning({
+            store: deps.topicTargetStore, owner: "leader", instanceId: deps.instanceId,
+            profileKey: leaderProfileKey, isCurrent: () => {
+                assertLeaderEpoch("connect-recovery");
+                return true;
+            }, recordEvent: deps.recordEvent,
+        });
+    }
     const legacyLeaderRecord = deps.topicTargetStore.getByProfileKey(leaderProfileKey);
     let capacityUnavailable = false;
     const workspaceIdentity = normalizedLeaderCwd
         ? deps.topicTargetStore.claimWorkspaceIdentity(normalizedLeaderCwd, deps.instanceId, legacyLeaderRecord?.instanceId, {
             sessionId: deps.sessionId,
+            provisionProfileKey: leaderProfileKey,
             onCapacityUnavailable() {
                 capacityUnavailable = true;
             },

package/dist/lib/threads.d.ts

@@ -495,6 +495,7 @@ export interface TelegramTopicTargetStore {
     } | undefined;
     listReservations: () => TelegramThreadReservation[];
     listPendingProvisions: () => TelegramThreadPendingProvision[];
+    resetPendingProvisionForConnect: (expected: TelegramThreadPendingProvision, isCurrent: () => boolean) => Promise<boolean>;
     listPendingCleanups: () => TelegramThreadCleanupIntent[];
     listSyncObservations: () => TelegramTopicSyncObservation[];
     reserveThread: (reservation: TelegramThreadReservation) => void;
@@ -559,6 +560,7 @@ export interface TelegramTopicTargetStore {
     claimWorkspaceIdentity: (cwd: string, instanceId: string, previousInstanceId?: string, options?: {
         existingBindingOnly?: boolean;
         sessionId?: string;
+        provisionProfileKey?: string;
         onCapacityUnavailable?: () => void;
     }) => TelegramWorkspaceBindingIdentity | undefined;
     releaseWorkspaceClaim: (instanceId: string) => boolean;
@@ -957,4 +959,13 @@ export declare function getTelegramTargetFromApiBody(body: unknown): (TelegramTa
 export declare function isTelegramTopicTargetStaleError(error: unknown): boolean;
 export declare function isTelegramTopicModeUnavailableError(error: unknown): boolean;
 export declare function createTelegramTopicTargetRenamer(deps: TelegramTopicTargetRenamerDeps): (request: TelegramTopicTargetRenameRequest) => Promise<TelegramTopicTargetRecord | undefined>;
+/** Caller holds profile Workspace admission; only an explicit connect grants a fresh creation attempt. */
+export declare function resetTelegramConnectionProvisioning(input: {
+    store: TelegramTopicTargetStore;
+    owner: TelegramThreadPendingProvision["owner"];
+    instanceId: string;
+    profileKey: string;
+    isCurrent: () => boolean;
+    recordEvent: (category: string, message: unknown, details?: Record<string, unknown>) => void;
+}): Promise<void>;
 export declare function createTelegramTopicTargetProvisioner(deps: TelegramTopicTargetProvisionerDeps): (request: TelegramTopicTargetProvisionRequest) => Promise<TelegramTopicTargetProvisionResult>;

package/dist/lib/threads.js

@@ -2304,7 +2304,7 @@ export function createTelegramTopicTargetStore(options) {
         }
         return false;
     };
-    const persistSnapshot = (transition, isCurrentPublication) => {
+    const persistSnapshot = (transition, isCurrentPublication, resetProvisions) => {
         const submittedPath = getPath(), submittedProfile = activeProfile();
         const publishWorkspace = workspaceIO?.capturePublication();
         const persist = persistQueue.then(async () => {
@@ -2437,6 +2437,12 @@ export function createTelegramTopicTargetStore(options) {
                     : readStoreSnapshot(path, transition?.kind === "relocate" ||
                         transition?.kind === "live-rebind" ||
                         !!expectedRestore));
+                if (resetProvisions) {
+                    const recoveries = readProvisionRecoveries(path, true);
+                    if (mutationRevision !== persistedRevision || resetProvisions.some(expected => expected.target || Object.hasOwn(recoveries, expected.id) ||
+                        !isDeepStrictEqual(disk.pendingProvisions?.find(value => value.id === expected.id), expected)))
+                        throw new Error("Telegram connection recovery provisioning evidence changed.");
+                }
                 if (!isDeepStrictEqual(disk.workspaceRestore, expectedRestore))
                     throw new Error("Workspace Restore evidence changed before publication.");
                 if (!manualNameMatches(disk) ||
@@ -2471,7 +2477,7 @@ export function createTelegramTopicTargetStore(options) {
                     }
                     : {}),
                 reservations: reservations.map((reservation) => ({ ...reservation })),
-                pendingProvisions: pendingProvisions.map((provision) => ({
+                pendingProvisions: pendingProvisions.filter(provision => !resetProvisions?.some(expected => expected.id === provision.id)).map((provision) => ({
                     ...provision,
                     ...(provision.target ? { target: { ...provision.target } } : {}),
                 })),
@@ -2626,6 +2632,10 @@ export function createTelegramTopicTargetStore(options) {
                 loadedProfile = submittedProfile;
                 loaded = true;
                 observedWorkspaceSemantic = getTelegramStateSemanticSnapshot(wire);
+                if (resetProvisions) {
+                    pendingProvisions = file.pendingProvisions;
+                    mutationRevision += 1;
+                }
                 if (transition) {
                     records = new Map(file.threads.map((record) => {
                         const normalized = normalizeRecord(record);
@@ -2765,6 +2775,11 @@ export function createTelegramTopicTargetStore(options) {
                 return false;
             loadedPath = path;
             loaded = true;
+            if (resetProvisions) {
+                if (mutationRevision !== persistedRevision)
+                    return false;
+                pendingProvisions = file.pendingProvisions;
+            }
             if (mutationRevision === persistedRevision)
                 dirty = false;
             return true;
@@ -4209,6 +4224,12 @@ export function createTelegramTopicTargetStore(options) {
             current.status = "ambiguous";
             return true;
         },
+        resetPendingProvisionForConnect(expected, isCurrent) {
+            // Stage no in-memory deletion: refusal or a stale publication must keep its protective hold.
+            if (expected.target || !isCurrent())
+                return Promise.resolve(false);
+            return persistSnapshot(undefined, isCurrent, [structuredClone(expected)]);
+        },
         removePendingProvision(id) {
             const before = pendingProvisions.length;
             pendingProvisions = pendingProvisions.filter((provision) => provision.id !== id);
@@ -4865,8 +4886,14 @@ export function createTelegramTopicTargetStore(options) {
                     liveRecord.instanceId !== effectivePreviousInstanceId) {
                     return undefined;
                 }
-                const retainedTarget = binding?.target ?? legacyRecord?.target;
-                const retainedSlot = binding?.slot ?? legacyRecord?.slot;
+                const ownedProvisions = pendingProvisions.filter(value => value.workspaceBindingKey === identity.bindingKey &&
+                    (value.instanceId === instanceId || value.instanceId === effectivePreviousInstanceId ||
+                        (options?.provisionProfileKey !== undefined && value.profileKey === options.provisionProfileKey)));
+                if (ownedProvisions.length > 1)
+                    return undefined;
+                const ownProvision = ownedProvisions[0];
+                const retainedTarget = ownProvision?.target ?? binding?.target ?? legacyRecord?.target;
+                const retainedSlot = ownProvision?.slot ?? binding?.slot ?? legacyRecord?.slot;
                 const otherBindings = Array.from(workspaceBindings.values())
                     .filter((other) => other.bindingKey !== identity.bindingKey && other.slot)
                     .map((other) => ({
@@ -4886,7 +4913,8 @@ export function createTelegramTopicTargetStore(options) {
                         reservation.expiresAtMs > nowMs)
                         .map((reservation) => reservation.slot),
                     ...pendingProvisions
-                        .filter((provision) => isPendingProvisionLiveOrTargeted(provision, nowMs))
+                        .filter((provision) => provision !== ownProvision &&
+                        isPendingProvisionLiveOrTargeted(provision, nowMs))
                         .map((provision) => provision.slot),
                     ...externalReservedSlots,
                 ]
@@ -6349,6 +6377,29 @@ export function createTelegramTopicTargetRenamer(deps) {
         return renamed;
     };
 }
+/** Caller holds profile Workspace admission; only an explicit connect grants a fresh creation attempt. */
+export async function resetTelegramConnectionProvisioning(input) {
+    if (!input.isCurrent())
+        throw new Error("Telegram connection recovery authority changed.");
+    const removed = [];
+    for (const pending of input.store.listPendingProvisions()) {
+        if (pending.owner !== input.owner || pending.target ||
+            (pending.profileKey !== input.profileKey && pending.instanceId !== input.instanceId))
+            continue;
+        if (!input.isCurrent())
+            throw new Error("Telegram connection recovery authority changed.");
+        if (!await input.store.resetPendingProvisionForConnect(pending, input.isCurrent))
+            throw new Error("Telegram connection recovery lost publication authority.");
+        if (!input.isCurrent())
+            throw new Error("Telegram connection recovery authority changed.");
+        removed.push(pending);
+    }
+    if (removed.length === 0)
+        return;
+    input.recordEvent("connection", "Explicit connect reset unfinished Thread creation; an unconfirmed Telegram Thread may remain.", {
+        phase: "connect-provision-reset", count: removed.length, owner: input.owner,
+    });
+}
 export function createTelegramTopicTargetProvisioner(deps) {
     const getNowMs = deps.getNowMs ?? (() => 0);
     const getRandom = deps.getRandom;
@@ -6554,7 +6605,7 @@ export function createTelegramTopicTargetProvisioner(deps) {
             }
             displayTitle = buildTelegramTopicName({ ...request, threadName: projectedTitle }, "{threadName}", slot);
         }
-        const pendingId = `provision:${request.instanceId}:${slot}:${nowMs}`;
+        const pendingId = `provision:${request.instanceId}:${slot}:${nowMs}:${randomUUID()}`;
         const pendingOwner = request.owner?.kind === "leader" ? "leader" : "manual-follower";
         assertLeaderEpoch("before-pending-intent");
         const pendingBase = {

package/dist/lib/updates.d.ts

@@ -227,6 +227,7 @@ interface TelegramUpdateAdmissionBinding {
     inspectSource?: () => TelegramDeferredSourceEvidence | undefined;
     inspectSourceSnapshot?: () => TelegramDeferredSourceSnapshot | undefined;
     inspectCompletion?: () => TelegramDeferredSourceEvidence | undefined;
+    subscribeCompletion?: (notify: () => void) => () => void;
     isSourceUnsettled?: () => boolean;
     prepareLiveInput?: (sourceUpdateIds: readonly number[], isCurrent: () => boolean, onTransferred?: () => void) => TelegramLiveDeferredInputPreparation | undefined;
     /** Internal notification after the worker's exact donor-removal ACK; never issues completion itself. */
@@ -242,7 +243,7 @@ interface TelegramUpdateAdmissionBinding {
 export type TelegramQueueAdmissionReceiptLike = TelegramQueueAdmissionReceipt;
 export declare function bindTelegramUpdateAdmissionSource<TUpdate extends TelegramUpdateFlow & {
     update_id: number;
-}>(update: TUpdate, report: TelegramUpdateAdmissionBinding["report"], controls?: Pick<TelegramUpdateAdmissionBinding, "abandon" | "armRoutingInput" | "getRoutingInput" | "acquireRouting" | "inspectSource" | "inspectSourceSnapshot" | "inspectCompletion" | "isSourceUnsettled" | "acknowledgeTransferred" | "prepareLiveInput" | "prepareQueueAdmission" | "prepareSourceCompletion" | "supportsAbandonment" | "inspectAbandoning" | "inspectHistorical" | "isHistorical" | "isHistoricalReviewHeld">): TUpdate;
+}>(update: TUpdate, report: TelegramUpdateAdmissionBinding["report"], controls?: Pick<TelegramUpdateAdmissionBinding, "abandon" | "armRoutingInput" | "getRoutingInput" | "acquireRouting" | "inspectSource" | "inspectSourceSnapshot" | "inspectCompletion" | "subscribeCompletion" | "isSourceUnsettled" | "acknowledgeTransferred" | "prepareLiveInput" | "prepareQueueAdmission" | "prepareSourceCompletion" | "supportsAbandonment" | "inspectAbandoning" | "inspectHistorical" | "isHistorical" | "isHistoricalReviewHeld">): TUpdate;
 /**
  * Conservative read-only census: any retained entry naming this Thread, in any nested Telegram object or state,
  * is unresolved custody, except a lone button tap, which carries no input (the in-flight Cancel itself).
@@ -262,6 +263,8 @@ export declare function inspectTelegramDeferredSource(value: unknown): TelegramD
 export declare function inspectTelegramDeferredSourceSnapshot(value: unknown): TelegramDeferredSourceSnapshot | undefined;
 /** Exact warm removal ACK only; reporting, source absence and a replaced worker cannot supply it. */
 export declare function inspectTelegramDeferredSourceCompletion(value: unknown): TelegramDeferredSourceEvidence | undefined;
+/** Warm ACK notification only; subscribers must independently recheck exact completion and recipient authority. */
+export declare function subscribeTelegramDeferredSourceCompletion(value: unknown, notify: () => void): (() => void) | undefined;
 /** Reuse only live bound deferred originals; raw IDs or cold/adopted input cannot mint this carrier. */
 export declare function prepareTelegramLiveDeferredInput(values: readonly unknown[], isCurrent: () => boolean): TelegramLiveDeferredInputPreparation | undefined;
 /** A route-owned pre-disposition acceptance publisher; wraps only this carrier, never the shared worker binding. */

package/dist/lib/updates.js

@@ -255,6 +255,16 @@ export function inspectTelegramDeferredSourceCompletion(value) {
     const source = getTelegramUpdateAdmissionBinding(value)?.inspectCompletion?.();
     return execution.isCurrent() && source ? { ...source } : undefined;
 }
+/** Warm ACK notification only; subscribers must independently recheck exact completion and recipient authority. */
+export function subscribeTelegramDeferredSourceCompletion(value, notify) {
+    const execution = getTelegramUpdateExecutionFence(value);
+    if (execution?.isCurrent() !== true)
+        return undefined;
+    return getTelegramUpdateAdmissionBinding(value)?.subscribeCompletion?.(() => {
+        if (execution.isCurrent())
+            notify();
+    });
+}
 /** Reuse only live bound deferred originals; raw IDs or cold/adopted input cannot mint this carrier. */
 export function prepareTelegramLiveDeferredInput(values, isCurrent) {
     const carriers = [...values], first = carriers[0], execution = getTelegramUpdateExecutionFence(first);
@@ -5155,6 +5165,7 @@ function createTelegramUpdateSourceAdmissionHandle(deps, capture) {
         let outcome;
         let completionAttempted = false;
         let completedSource;
+        const completionObservers = new Set();
         const boundUpdate = bindTelegramUpdateExecutionFence(bindTelegramUpdateAdmissionSource(update, (next) => {
             if (!execution.isCurrent())
                 return;
@@ -5199,11 +5210,15 @@ function createTelegramUpdateSourceAdmissionHandle(deps, capture) {
                     completion &&
                     execution.isCurrent() &&
                     completion.isCurrent() &&
-                    isDeepStrictEqual(completion.source, expectedSource))
-                    completedSource = {
-                        ...completion,
-                        source: { ...expectedSource },
-                    };
+                    isDeepStrictEqual(completion.source, expectedSource)) {
+                    completedSource = { ...completion, source: { ...expectedSource } };
+                    for (const notify of completionObservers) {
+                        try {
+                            notify();
+                        }
+                        catch { /* Observation cannot invalidate an exact removal ACK. */ }
+                    }
+                }
             })
                 .catch((error) => {
                 try {
@@ -5260,6 +5275,10 @@ function createTelegramUpdateSourceAdmissionHandle(deps, capture) {
                     signal,
                 })
                 : undefined,
+            subscribeCompletion: (notify) => {
+                completionObservers.add(notify);
+                return () => { completionObservers.delete(notify); };
+            },
             inspectCompletion: () => execution.isCurrent() && completedSource?.isCurrent()
                 ? { ...completedSource.source }
                 : undefined,

package/dist/package.json

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

package/docs/architecture.md

@@ -61,6 +61,8 @@ The repository uses a **Flat Domain DAG**:
 
 ### Live-Rebind Module Map
 
+For an already-issued leader menu/control command whose semantics finish before delivery, the original chooser may observe its exact warm source-removal ACK for one window of up to eight seconds before answering. Later taps only reobserve; they do not restart that wait. Naming/confirmation/extension producers whose source completion can depend on later publication keep their independent completion path. Updates notifies subscribers only after its carrier retains that ACK, not at the earlier journal-completion hook. Routing rechecks source, recipient, canonical binding and execution generation; observation cannot issue a second command or turn source absence into confirmation. Menu/reply delivery is not awaited. Timeout, abort or authority loss removes subscriptions and retains uncertainty without replay; old-Thread cleanup remains an independent fenced operation.
+
 Release `0.53.0` adds the [live-rebind channel](./multi-instance-bus.md#live-rebind-channel) and bounded old-Thread cleanup. It advertises live save/apply/settle, command-set and selected-menu-delivery through bus protocol v3, retaining Workspace Restore for legacy continuity. A loaded 0.53.0 build prefers the live path; an instance still running an older build keeps Restore until it is reloaded. Windows runs the same channel and strict reads, exercised by the CI matrix; there is no platform-specific alternate protocol.
 
 The channel reuses existing owners rather than adding a parallel command bus, queue or recovery store:
@@ -575,6 +577,14 @@ Polling and inbound-worker diagnostics remain separate so an executing, deferred
 
 Long-text split recovery remains conservative: only human text at or above the near-limit threshold opens its debounce window. Forward annotation has two semantic layers: the forward owns its source text/caption/media, while an optional separate owner-authored annotation normally precedes it. A bounded one-second pairing window joins that annotation and adjacent forward in either transport order, including a media-only forward without source caption text; the matching opposite-kind message flushes immediately. Same-kind rapid messages, commands, bots, ordinary non-forward captions, media groups, different senders/targets, reversed ids, and distant message ids do not enter this pairing path. Prompt construction always places the owner annotation first, followed by `[forward|from:...]` with the forward's own source text/caption, then source-attributed forwarded attachments, regardless of arrival order.
 
+### Explicit Connection Recovery
+
+An explicit `/telegram-connect` is permission for one fresh connection attempt, not permission to take over a live leader or clear accepted input. Under the existing profile-wide Workspace admission and mutation gate, the leader resets only matching unfinished creation records without a known Thread target before claiming Workspace identity. The reset verifies the exact retained record and refuses sidecar target-recovery evidence; durable publication and current ownership are required before another create. Known targets and other owners' pending records remain intact. A late response is isolated by a fresh provisioning ID, independent of wall-clock resolution.
+
+If Telegram committed the abandoned create without returning its Thread ID, a spare tab may remain. This is the operator-approved availability trade-off: no unknown tab is deleted, and no journal, receipt, live binding or queued prompt is erased. A new API outage can still fail the new attempt; the command does not promise connectivity without a working Telegram transport.
+
+Followers carry this explicit intent only on authenticated `follower.register`, gated by `explicit-connect-recovery-v1` at caller and leader. Automatic heartbeat recovery and `follower.restoreWorkspace` do not reset creation evidence. A matching targeted pending provision contributes its original Workspace key/slot when the exact session is claimed again, so retry can complete known publication rather than allocate a conflicting identity. Cross-session targets never become recovery grants.
+
 ### Queue And Dispatch Safety
 
 The bridge keeps its own Telegram queue. The Pi status bar projects executable waiting work across Normal, Priority, Steer and Control into one warning-yellow `+N` suffix, omitted when zero. It uses Queue's executability filter, so Skip and frozen attempts never contribute; current agent work from Telegram, terminal, or autonomous sources never contributes either. The dispatched Telegram head is subtracted while retained pending `agent_start` consumption.

package/docs/multi-instance-bus.md

@@ -85,6 +85,8 @@ tmp/pi-telegram/state.json / profiles.<profile>.transport -> bus leader identity
 
 Followers do not poll. They register with the leader and receive routed inbound updates from it. Followers still own their local queue, active-turn state, previews, final delivery planning, model switches, and Pi lifecycle. The leader owns only Telegram transport and update fanout. Same-session context refresh preserves bus membership; a changed Pi session ID suspends the old receiver/heartbeat and requires acknowledged successor registration before readiness, without an explicit Thread disconnect. A new follower process also attempts a restore-only registration at session startup when the selected profile's local state contains a Workspace binding for the exact `cwd` and session ID. If an active retained manual-follower record blocks that binding, the leader may transfer its claim only for one exact eligible predecessor: no registered peer owns its runtime or target, and an OS probe proves the actual runtime PID absent. A live, inaccessible, missing or malformed PID proof and ambiguous candidates remain protective; neither elapsed time nor an empty registry alone proves death. This is only claim continuity, not receipt settlement, deletion or a fabricated immediate session handoff. The same binding, non-default instance slot, acknowledged title and journal history survive without provisioning a new Thread. The recent-event log distinguishes missing session bindings, disabled Threaded Mode, leader-side restore refusal, and a restore that returned without connecting; none of these refusals silently provisions a new Thread. The Telegram bus belongs to the local set of cooperating visible Pi instances rather than to the first terminal session forever: if the visible terminal leader exits, a live registered follower can take over leadership.
 
+Explicit connection recovery is capability-gated by `explicit-connect-recovery-v1`. Only a manual `follower.register` may carry `recoverConnection: true`; malformed values and restore-only requests reject it. The leader resets matching untargeted creation metadata under ordinary profile admission before allocation, accepting a possible orphan tab without touching accepted input. Automatic registration never carries this grant. See [Explicit Connection Recovery](./architecture.md#explicit-connection-recovery).
+
 ### Session-Owned Journal Storage
 
 Runtime storage lives under `<agent-dir>/tmp/pi-telegram`. The pre-0.52.0 `tmp/telegram` tree is neither written, migrated nor deleted. A live fresh owner there blocks competing polling as read-only evidence; its endpoint and secret grant no current authority.
@@ -305,7 +307,7 @@ After the recipient confirms the applied rebind and before the source is release
 
 Follower live apply, held-work observation and release-readiness checks use the exact read-only live-rebind Workspace snapshot, including with consolidated storage and no follower publication authority. The captured store/reader identity stays fenced across awaits; a missing or replaced reader refuses without falling back to the publication-backed legacy Restore observer. Profile admission, exact canonical intent/binding and source/custody checks still apply. Observation changes only the follower's local target registration, never leader-owned Workspace evidence; journal reads and receipt settlement remain separate owners.
 
-Every participating peer must negotiate the required capabilities and retain current authentication, registration generation, Pi context/session, journal binding and exact recipient authority. The wire validates syntax; Commands' captured registry decides availability before hold/append. Supported built-ins and registered prompt templates reuse one plan set across compatible leader selections and held followers; extension commands/groups/legacy registrations do not gain follower execution. Continue keeps its control lane, while expanded templates are ordinary default-lane prompts even when their text starts with a slash.
+Every participating peer must negotiate the required capabilities and retain current authentication, registration generation, Pi context/session, journal binding and exact recipient authority. The wire validates syntax; Commands' captured registry decides availability before hold/append. Supported built-ins and registered prompt templates reuse one plan set across compatible leader selections and held followers. Both peers additionally negotiate `held-menu-aliases-v1` for follower `/start` and `/help`: these already-authenticated selections open the restricted main menu using the status plan, never pair a user, bootstrap a Thread or synchronize BotFather commands through ordinary follower transport; extension commands/groups/legacy registrations do not gain follower execution. Continue keeps its control lane, while expanded templates are ordinary default-lane prompts even when their text starts with a slash.
 
 Semantic reports, queued receipts, completion observation and delivery remain separate. Native exact ACK and donor CAS still own source disposition; lost or mismatched evidence retains uncertainty without handler replay, another queue or fallback admission. This section owns the unified command-channel policy; [architecture](./architecture.md#live-rebind-module-map) owns the module map. Existing Workspace Restore receivers/readers and queue-handoff retain their custody contracts; the new loaded root prefers live rebinding rather than using legacy Restore as an uncertain-input fallback. Source-enabled bounded cleanup is not proof of an actual deletion or client acceptance. Supported leader/follower prompts, commands and templates use `saved → binding applied → cleanup decision → input issuance → native admission/execution`. The chooser holds its existing profile admission through the unchanged whole first delay and one fresh cleanup attempt, without nested leader admission or another queue. A negotiated follower reports work through `observe-held` before release; binding readiness is not execution permission. `inputRelease: held/issued/accepted` is independent of cleanup: an issued input is never replayed after a lost admission reply, and a finished cleanup with held input remains active binding/source protection. Confirmed, failed or unknown terminal deletion permits the one native input attempt only on the confirmed binding. Issued and unknown old-target evidence remains canonically protected against reuse and generic cleanup, including response/publication interruption; unknown evidence survives input acceptance and is never capacity-evicted or reissued. If earlier work prevents issuance, input proceeds on the confirmed new target and the existing paced scheduler owns deferred cleanup; no old-target clearance is invented. Detached command producers accept their one input grant independently from exact source ACKs and reply publication; menu/reply authority tolerates only that issued-to-accepted progress, never changed binding, cleanup, recipient or generation. Expanded templates retain their captured content/default lane and Continue its control lane. A session-replacing `/new` producer with earlier protected work records positively unissued cleanup plus durable `oldTargetProtected`; it cannot erase that old-target protection or transfer a delete grant into the successor. Actual replacement still uses the existing post-removal Pi gateway and confirmation, not Restore readiness. Follower command/control completion retains the exact prepared-source/native ACK before donor CAS; queued admission is not completion and cannot dispose the donor. Unsupported producers do not gain arbitrary follower execution. Older peers keep the preceding supported channel. In deferred cleanup, old-tab cleanup waits for the recipient session to be idle, which the moved input itself may keep busy; its paced retries keep a whole first delay so a detached command reply still sees the released, cleanup-free row, but after that a leader's `agent_settled` or drained output barrier wakes a waiting retry at once. Publication/command-work, Activity handlers, per-target companion queues and target/chat API counters capture lifetime-fenced notifications when work starts and emit only after their pending observation clears. The session adapter defers the hint without awaiting cleanup and rechecks its captured context generation, transport/profile and leader epoch/operator authority. Streaming technical events can drain the publication queue without ending the agent run. A delivery hint while SDK idle is false, unavailable or throwing is retained in the existing chain but does not clear its timer or acquire Workspace admission. `agent_settled` remains an unconditional recheck hint; after settlement, actual remaining delivery drains can wake the retry. A running attempt retains one coalesced hint without a concurrent check, then re-enters the same idle filter after releasing its admission. A fresh timer/settlement attempt consumes the previously deferred hint; signals arriving during that await are not lost. Timer retries, including busy-session samples, are unchanged. Terminal outcomes discard hints, including unknown issued deletion. The initial one-second delay, retry/window fallback, follower pacing and negotiated IPC contracts remain unchanged. Each chain also retains its original generation/profile-store/epoch/operator lifetime rather than rebasing to a reused context. The wake only re-samples every gate through fresh admission; it never grants cleanup, clears unconfirmed work, occupies the publication tail or holds Pi settlement for deletion. Windows runs the same strict paths, exercised by the CI matrix; actual Pi/client acceptance and release are not inferred from supplied IPC fixtures.
 
@@ -559,7 +561,7 @@ All files containing routing, chat ids, thread ids, or process details use priva
 - Each unfinished preservation retains one admission operation ID across sequential attempts, so a lost acquisition acknowledgement reuses and releases the exact lease instead of leaking another. A rejected pre-rename write leaves the owner intact; a committed write with lost acknowledgement is recognized without rewriting first inactivity. A liveness interruption is retryable, not successful settlement. Every attempt reacquires profile admission and the shared mutation gate, rechecks authority at rename, and preserves accepted work. Cancellation or scope loss never guesses away an unresolved admission lease; existing exact lease/dead-owner recovery remains authoritative.
 - Followers treat rejected/missing heartbeat acknowledgements as registration loss: retain the last known target locally, clear registered truth, show `reconnecting` instead of a healthy `follower` status, try to re-register with the current leader, wait a short leader-reload grace window, and retry. They promote only after the exact leader lease becomes stale or inactive; a live owner with an unreachable endpoint leaves the follower disconnected/retrying rather than creating a competing poller.
 - Persisted current manual-follower bindings survive abrupt process absence as restoration hints when Thread cleanup is disabled. When enabled, graceful Pi quit requests exact-generation teardown before lifecycle suspension; if that envelope is missed, stale pruning may delete only after the leader's OS confirms the exact registered PID has exited.
-- Fresh registration sends one compact connected notice in the assigned thread. Reusing a retained exact-session target resolves its acknowledged Workspace display title, even if the provisional claim uses another instance slot; a generated dictionary name is only fallback when no acknowledged title exists. An exact immediate session handoff uses a target-scoped `sendChatAction` as its synchronous visibility probe, avoiding a duplicate notice while retaining stale/ambiguous recovery; other cross-session restoration keeps the connected notice as its probe.
+- Fresh registration sends one compact connected notice in the assigned thread. Reusing a retained exact-session target resolves its acknowledged Workspace display title, even if the provisional claim uses another instance slot; a generated dictionary name is only fallback when no acknowledged title exists. Cross-process/session restoration, including an exact immediate handoff, uses that connected message as its visibility probe before publishing registration. Typing is not proof that a retained tab accepts messages. A proven stale target enters existing replacement provisioning; an ambiguous send refuses registration without inventing deletion or retry authority.
 - Registration requires a present generation, and explicit disconnect requires that same exact live generation. Leader-side registration and disconnect mutations serialize per durable follower profile across old and replacement runtime instance IDs, so a replacement registration cannot overtake awaited destructive cleanup and an old disconnect cannot remove its successor's routing authority.
 - Successful forwarded updates and follower-originated API calls refresh liveness, so active followers are not pruned only because the interval heartbeat tick lagged. Each follower lifecycle owns at most one in-flight heartbeat for its exact registration generation; stop/replacement makes late settlement inert, and recovery or diagnostic failure cannot escape as an unhandled interval Promise.
 - Destructive follower thread teardown belongs to confirmed `/telegram-disconnect`, graceful Pi quit, or confirmed reconciliation actions, not generic heartbeat pruning. Manual disconnect retains its destructive confirmation and clears restart ownership; quit deletes the tab without prompting when Thread cleanup is enabled (default) but preserves the owner slot independently so a same-directory restart can reclaim leadership. Confirmed leader/follower teardown first persists an exact target/runtime-generation cleanup intent. The active leader attempts deletion under its current epoch; interruption preserves the intent so that leader or a successor can replay it under current authority, and confirmed deletion removes the binding plus intent in the same persisted state transition. If the graceful request is missed, stale heartbeat plus OS-confirmed absence of the exact registered PID may authorize the same cleanup while enabled; this action serializes ahead of replacement registration. Disabled cleanup, silence, heartbeat expiry alone, IPC/auth failure, and live or unknown process liveness remain non-destructive. Incomplete cleanup preserves durable intent for retry. A promoted leader uses its current owned leader epoch even when the inherited record still carries a historical `manual-follower` owner label.

package/lib/bus-follower.ts

@@ -42,7 +42,6 @@ import {
   sendTelegramBusLocalEnvelope,
   TELEGRAM_BUS_CAPABILITY_DIRECTORY_DISPLAY_FORMAT,
   TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_APPLY,
-  TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_COMMAND_SET,
   TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_SAVE,
   TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_SETTLE,
   TELEGRAM_BUS_CAPABILITY_PRE_DISPATCH_REBIND_EXECUTION,
@@ -52,6 +51,7 @@ import {
   TELEGRAM_BUS_CAPABILITY_WORKSPACE_RESTORE,
   TELEGRAM_BUS_CAPABILITY_WORKSPACE_THREAD_RENAME,
   TELEGRAM_BUS_HELD_COMMAND_CAPABILITIES,
+  getTelegramBusHeldCommandCapabilities,
   TELEGRAM_BUS_LIVE_REBIND_CAPABILITIES,
   TelegramBusLocalAuthorityError,
   type TelegramBusAgentMessage,
@@ -178,6 +178,7 @@ export interface TelegramBusFollowerRegistrationRuntime<TContext> {
       target?: TelegramTarget;
       previousInstanceId?: string;
       restoreWorkspace?: boolean;
+      recoverConnection?: boolean;
     },
   ) => Promise<boolean>;
   setContext: (ctx: TContext) => void | Promise<void>;
@@ -2930,7 +2931,7 @@ export function createTelegramBusFollowerRegistrationRuntime<
         deps.setActiveAuthSecret?.(undefined);
         await deps.stopReceiving?.();
       };
-      const pendingHandoff = options
+      const pendingHandoff = options && !options.recoverConnection
         ? undefined
         : getTelegramFollowerSessionHandoff();
       const pendingHandoffOptions = isTelegramFollowerSessionHandoffFresh(
@@ -2946,8 +2947,9 @@ export function createTelegramBusFollowerRegistrationRuntime<
             target?: TelegramTarget;
             previousInstanceId?: string;
             restoreWorkspace?: boolean;
+            recoverConnection?: boolean;
           }
-        | undefined = options ?? pendingHandoffOptions;
+        | undefined = options ? { ...pendingHandoffOptions, ...options } : pendingHandoffOptions;
       const leaderSocketPath =
         leader.busSocketPath ??
         deps.getLeaderSocketPath?.() ??
@@ -2968,6 +2970,8 @@ export function createTelegramBusFollowerRegistrationRuntime<
           : "follower.register",
         requestId: registrationGeneration,
         auth: activeAuthSecret,
+        ...(registrationOptions?.recoverConnection && !registrationOptions.restoreWorkspace
+          ? { recoverConnection: true as const } : {}),
         registration: {
           instanceId: deps.instanceId,
           ...(registrationOptions?.previousInstanceId
@@ -4546,8 +4550,7 @@ export function createTelegramBusForwardedUpdateReceiverRuntime<TContext>(
             ? [
                 TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_APPLY,
                 TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_SETTLE,
-                TELEGRAM_BUS_CAPABILITY_LIVE_REBIND_COMMAND_SET,
-                TELEGRAM_BUS_CAPABILITY_SELECTED_MENU_DELIVERY,
+                ...getTelegramBusHeldCommandCapabilities(commandInput.name),
               ]
             : []),
         ];