@llblab/pi-kit 0.35.1 → 0.35.3

package/node_modules/@llblab/pi-telegram/dist/lib/logging.js

@@ -8,6 +8,82 @@ import { basename, dirname, join } from "node:path";
 import { withTelegramFileTransaction } from "./locks.js";
 import { resolveAgentDir, resolveTelegramPreviousSharedRuntimeLogPath, resolveTelegramProfileTempFilePath, resolveTelegramRuntimeLogPath, } from "./paths.js";
 import * as Status from "./status.js";
+/** Stable identity of one failure kind: errno when present, otherwise the failure text. */
+export function getTelegramFailureSignature(error) {
+    const code = error?.code;
+    if (typeof code === "string" && code)
+        return code;
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Consecutive identical failure runs for one diagnostic phase: a repeat extends the run instead of logging again,
+ * and a closing success or reset emits at most one outcome record. This never gates detection or recovery.
+ */
+export function createTelegramFailureRunLog(input) {
+    const getNowMs = input.getNowMs ?? Date.now;
+    let run;
+    const emit = (errorOrMessage, details) => {
+        try {
+            input.record?.(input.category, errorOrMessage, {
+                ...(input.context?.() ?? {}),
+                ...details,
+            });
+        }
+        catch {
+            // A diagnostic sink never converts a recorded failure into another failure.
+        }
+    };
+    return {
+        record(error, details) {
+            const signature = getTelegramFailureSignature(error);
+            const admitted = { ...(details ?? {}) };
+            if (run?.signature === signature) {
+                run.suppressed += 1;
+                Object.assign(run.details, admitted);
+                return false;
+            }
+            const previous = run;
+            run = { signature, suppressed: 0, startedAtMs: getNowMs(), details: admitted };
+            emit(error, {
+                ...admitted,
+                phase: input.failurePhase,
+                failureSignature: signature,
+                ...(previous
+                    ? {
+                        previousFailureSignature: previous.signature,
+                        previousFailedAttempts: previous.suppressed + 1,
+                        previousFailedForMs: getNowMs() - previous.startedAtMs,
+                    }
+                    : {}),
+            });
+            return true;
+        },
+        settled() {
+            const closed = run;
+            if (!closed)
+                return undefined;
+            run = undefined;
+            const summary = {
+                signature: closed.signature,
+                failedAttempts: closed.suppressed + 1,
+                suppressedFailures: closed.suppressed,
+                failedForMs: getNowMs() - closed.startedAtMs,
+            };
+            emit(`Telegram ${input.label} recovered after ${summary.failedAttempts} failed attempts.`, {
+                ...closed.details,
+                phase: input.outcomePhase,
+                failureSignature: summary.signature,
+                failedAttempts: summary.failedAttempts,
+                suppressedFailures: summary.suppressedFailures,
+                failedForMs: summary.failedForMs,
+            });
+            return summary;
+        },
+        reset() {
+            run = undefined;
+        },
+    };
+}
 const DEFAULT_MAX_LOG_BYTES = 5 * 1024 * 1024;
 export function getTelegramRuntimeLogPath(agentDir = resolveAgentDir(), profileName) {
     return resolveTelegramProfileTempFilePath("logs", "jsonl", agentDir, profileName);
@@ -333,6 +409,10 @@ export function createTelegramRuntimeDiagnosticsRuntime(options = {}) {
     };
     return {
         events,
+        createFailureLog: (input) => createTelegramFailureRunLog({
+            ...input,
+            record: (category, errorOrMessage, details) => recordRuntimeEvent(category, errorOrMessage, details),
+        }),
         recordRuntimeEvent,
         bindStorage(ports) {
             getBotToken = ports.getBotToken;

package/node_modules/@llblab/pi-telegram/dist/lib/paths.d.ts

@@ -43,7 +43,8 @@ export declare function resolveLegacyTelegramOwnersPath(agentDir?: string): stri
 export declare function resolveTelegramOwnersPath(): string;
 export declare function getTelegramProfilePathSuffix(profileName?: string): string;
 export declare function resolveTelegramProfileTempFilePath(baseName: string, extension: string, agentDir?: string, profileName?: string): string;
-export declare function getTelegramDiagnosticsDisplayPaths(_profileName?: string): {
+/** Shared state/log paths for every profile, under the resolved agent dir (honors `PI_CODING_AGENT_DIR`). */
+export declare function getTelegramDiagnosticsDisplayPaths(_profileName?: string, agentDir?: string): {
     state: string;
     logs: string;
 };

package/node_modules/@llblab/pi-telegram/dist/lib/paths.js

@@ -111,10 +111,25 @@ export function getTelegramProfilePathSuffix(profileName) {
 export function resolveTelegramProfileTempFilePath(baseName, extension, agentDir = resolveAgentDir(), profileName) {
     return join(resolveTelegramTempDir(agentDir), `${baseName}${getTelegramProfilePathSuffix(profileName)}.${extension}`);
 }
-export function getTelegramDiagnosticsDisplayPaths(_profileName) {
+/** Shared state/log paths for every profile, under the resolved agent dir (honors `PI_CODING_AGENT_DIR`). */
+export function getTelegramDiagnosticsDisplayPaths(_profileName, agentDir = resolveAgentDir()) {
+    // Storage paths are canonical, so also match a canonical home (e.g. /home -> /var/home).
+    const homes = [homedir()];
+    try {
+        homes.push(realpathSync(homes[0]));
+    }
+    catch {
+        /* An unreadable home only loses the ~ abbreviation. */
+    }
+    const display = (path) => {
+        const home = homes.find((candidate) => path === candidate || path.startsWith(`${candidate}${sep}`));
+        return home
+            ? `~${path.slice(home.length).split(sep).join("/")}`
+            : path;
+    };
     return {
-        state: "~/.pi/agent/tmp/pi-telegram/state.json",
-        logs: "~/.pi/agent/tmp/pi-telegram/logs.jsonl",
+        state: display(resolveTelegramStatePath(agentDir)),
+        logs: display(resolveTelegramRuntimeLogPath(agentDir)),
     };
 }
 /** Durable Workspace admission ledger (<agentDir>/tmp/pi-telegram/workspace-admission[.<profile>].json). */

package/node_modules/@llblab/pi-telegram/dist/lib/polling.d.ts

@@ -4,6 +4,15 @@
  * Owns polling request builders, stop conditions, and the long-poll loop runtime for Telegram updates
  */
 type MaybePromise<T> = T | Promise<T>;
+/**
+ * Structural port for run-collapsing diagnostics: a repeated identical failure extends its run instead of logging
+ * again, and the closing success records one outcome. The composition root owns the collapsed implementation.
+ */
+export interface TelegramRepeatedFailureLogPort {
+    record: (error: unknown, details?: Record<string, unknown>) => void;
+    settled: () => void;
+    reset: () => void;
+}
 export interface TelegramPollingConfig {
     botToken?: string;
 }
@@ -174,6 +183,8 @@ export interface TelegramStartupThreadCapabilityProbeDeps extends TelegramThread
     getNowMs?: () => number;
 }
 export interface TelegramThreadCapabilityRuntimeDeps<TContext> extends TelegramThreadCapabilityReaderDeps {
+    /** Collapses one sustained probe failure run; the caller supplies its owner. */
+    failureLog: TelegramRepeatedFailureLogPort;
     lifecycle?: TelegramThreadCapabilityLifecycle;
     topicTargetStore: TelegramThreadCapabilityStore;
     ownsLock: (ctx: TContext) => boolean;
@@ -251,6 +262,8 @@ export interface TelegramThreadAwarePollingDeps<TContext, TOwner> extends Telegr
     setForceFreshLeaderThreadOnNextStart: (forceFresh: boolean) => void;
 }
 export interface TelegramThreadCapabilityOrchestrationDeps<TContext, TOwner> extends TelegramThreadCapabilityReaderDeps, TelegramThreadAwarePollingControls<TContext, TOwner> {
+    /** Collapses one sustained probe failure run; the composition root supplies its owner. */
+    failureLog: TelegramRepeatedFailureLogPort;
     state: TelegramThreadCapabilityStateRuntime;
     topicTargetStore: TelegramThreadCapabilityStore;
     ownsLock: (ctx: TContext) => boolean;

package/node_modules/@llblab/pi-telegram/dist/lib/polling.js

@@ -471,6 +471,7 @@ export function createTelegramThreadCapabilityOrchestration(deps) {
         isTopicModeUnavailableError: deps.isTopicModeUnavailableError,
         updateStatus: deps.updateStatus,
         recordEvent: deps.recordEvent,
+        failureLog: deps.failureLog,
     };
     return {
         monitor: createTelegramThreadCapabilityMonitor(capabilityDeps),
@@ -813,8 +814,37 @@ export function createTelegramThreadCapabilityMonitor(deps) {
     let generation = 0;
     let transitionPromise;
     let consecutiveDisabledProbes = 0;
+    // An absent leader endpoint repeats one identical probe failure every interval; the port collapses the run.
+    // Running it through one guard keeps a faulty diagnostics port from breaking probes or the interval callback.
+    const capabilityFailureLog = {
+        record(error, details) {
+            try {
+                deps.failureLog.record(error, details);
+            }
+            catch {
+                // Monitor diagnostics cannot create an uncaught interval exception.
+            }
+        },
+        settled() {
+            try {
+                deps.failureLog.settled();
+            }
+            catch {
+                // Monitor diagnostics cannot fail a completed probe.
+            }
+        },
+        reset() {
+            try {
+                deps.failureLog.reset();
+            }
+            catch {
+                // Monitor diagnostics cannot fail a monitor stop.
+            }
+        },
+    };
     const stop = () => {
         generation += 1;
+        capabilityFailureLog.reset();
         if (interval)
             clearInterval(interval);
         interval = undefined;
@@ -832,6 +862,7 @@ export function createTelegramThreadCapabilityMonitor(deps) {
             .then(async (threadModeEnabled) => {
             if (!isCurrent())
                 return;
+            capabilityFailureLog.settled();
             if (threadModeEnabled === undefined) {
                 if (deps.topicTargetStore.getBotState().threadMode !== "enabled" &&
                     !deps.getPollingStartedWithTelegramBus() &&
@@ -879,12 +910,7 @@ export function createTelegramThreadCapabilityMonitor(deps) {
             .catch((error) => {
             if (!isCurrent())
                 return;
-            try {
-                deps.recordEvent("bus", error, { phase: "capability-monitor" });
-            }
-            catch {
-                // Monitor diagnostics cannot create an unhandled interval rejection.
-            }
+            capabilityFailureLog.record(error);
         })
             .finally(() => {
             if (transitionPromise === tracked)
@@ -911,12 +937,7 @@ export function createTelegramThreadCapabilityMonitor(deps) {
                     catch {
                         /* Timer shutdown must not escape the callback. */
                     }
-                    try {
-                        deps.recordEvent("bus", error, { phase: "capability-monitor" });
-                    }
-                    catch {
-                        // Monitor diagnostics cannot create an uncaught interval exception.
-                    }
+                    capabilityFailureLog.record(error);
                 }
             }, intervalMs);
             interval.unref?.();

package/node_modules/@llblab/pi-telegram/dist/lib/runtime.d.ts

@@ -4,6 +4,15 @@
  * Owns small session-local runtime primitives that are shared by orchestration but are not specific to queueing, rendering, polling, or Telegram transport
  */
 import * as Machine from "./machine.ts";
+/**
+ * Structural port for run-collapsing diagnostics: a repeated identical failure extends its run instead of logging
+ * again, and the closing success records one outcome. The composition root owns the collapsed implementation.
+ */
+export interface TelegramRepeatedFailureLogPort {
+    record: (error: unknown, details?: Record<string, unknown>) => void;
+    settled: () => void;
+    reset: () => void;
+}
 export interface TelegramRuntimeQueueCounters {
     nextQueuedTelegramItemOrder: number;
     nextQueuedTelegramControlOrder: number;
@@ -103,6 +112,8 @@ export interface TelegramRuntimeEventRecorderPort {
     recordRuntimeEvent?: (category: string, error: unknown, details?: Record<string, unknown>) => void;
 }
 export interface TelegramTypingLoopStarterDeps<TContext> extends TelegramRuntimeEventRecorderPort {
+    /** Collapses one sustained presence failure run; the caller supplies its owner. */
+    failureLog: TelegramRepeatedFailureLogPort;
     typing: TelegramRuntimeTypingPort;
     getDefaultChatId: () => number | undefined;
     sendTypingAction: (chatId: number, options?: {

package/node_modules/@llblab/pi-telegram/dist/lib/runtime.js

@@ -162,6 +162,34 @@ function updateTelegramRuntimeStatusSafely(updateStatus, ctx, options) {
 }
 export function createTelegramTypingLoopStarter(deps) {
     let currentOwner;
+    // An unreachable transport repeats one identical presence failure every tick; the port collapses the run.
+    // Running it through one guard keeps a faulty diagnostics port from escaping the in-flight action owner.
+    const typingFailureLog = {
+        record(error, details) {
+            try {
+                deps.failureLog.record(error, details);
+            }
+            catch {
+                // Typing diagnostics cannot escape the in-flight action owner.
+            }
+        },
+        settled() {
+            try {
+                deps.failureLog.settled();
+            }
+            catch {
+                // A successful presence outranks its own diagnostic.
+            }
+        },
+        reset() {
+            try {
+                deps.failureLog.reset();
+            }
+            catch {
+                // Typing diagnostics cannot fail a loop stop.
+            }
+        },
+    };
     return (ctx, chatId, options) => {
         const sessionGeneration = deps.getSessionGeneration?.();
         const transportAuthority = deps.getTransportAuthority?.();
@@ -214,6 +242,7 @@ export function createTelegramTypingLoopStarter(deps) {
                                 throw new Error("Typing context authority changed.");
                         },
                     });
+                    typingFailureLog.settled();
                 }
                 catch (error) {
                     if (!active)
@@ -222,19 +251,13 @@ export function createTelegramTypingLoopStarter(deps) {
                         deps.typing.stop();
                         return;
                     }
-                    try {
-                        deps.recordRuntimeEvent?.("typing", error, {
-                            chatId: targetChatId,
-                        });
-                    }
-                    catch {
-                        // Typing diagnostics cannot escape the in-flight action owner.
-                    }
+                    typingFailureLog.record(error, { chatId: targetChatId });
                 }
             },
             shouldContinue: canContinue,
             onStopped: () => {
                 active = false;
+                typingFailureLog.reset();
                 if (currentOwner === owner)
                     currentOwner = undefined;
             },

package/node_modules/@llblab/pi-telegram/dist/lib/telegram-api.d.ts

@@ -299,6 +299,8 @@ export interface TelegramApiCallOptions {
     sleep?: (ms: number) => Promise<void>;
     /** Observability hook fired before a 429 retry wait, never for 5xx waits. */
     onRetryWait?: (wait: TelegramApiRetryWait) => void;
+    /** Caller-owned expected failure: still thrown, but the caller records the outcome instead of the API log. */
+    isExpectedError?: (error: unknown) => boolean;
 }
 export declare class TelegramApiAuthorityError extends Error {
     readonly requestIssued: boolean;

package/node_modules/@llblab/pi-telegram/dist/lib/telegram-api.js

@@ -1134,7 +1134,8 @@ export function createTelegramBridgeApiRuntime(deps) {
                     "Telegram API deleteMessage failed: HTTP 400: Bad Request: message to delete not found") {
                 return true;
             }
-            deps.recordRuntimeEvent("api", error, withTelegramTransportDiagnostics(error, { method }));
+            if (!options?.isExpectedError?.(error))
+                deps.recordRuntimeEvent("api", error, withTelegramTransportDiagnostics(error, { method }));
             throw error;
         }
     };

package/node_modules/@llblab/pi-telegram/dist/lib/thread-reconciler.js

@@ -339,7 +339,11 @@ export async function applyThreadReconciliationPlan(plan, ports) {
             }
             let deleteConfirmed = false;
             let superseded = false;
-            for (const method of ports.skipCloseBeforeDelete
+            // Private-chat topics (positive chat ids) cannot be closed; Telegram only supports closeForumTopic in forums.
+            const skipClose = ports.skipCloseBeforeDelete ||
+                (action.kind === "close-delete-graceful-shutdown-topic" &&
+                    action.target.chatId > 0);
+            for (const method of skipClose
                 ? ["deleteForumTopic"]
                 : ["closeForumTopic", "deleteForumTopic"]) {
                 if (ports.isCleanupTargetProtected?.(action.target, action)) {

package/node_modules/@llblab/pi-telegram/dist/lib/threads.d.ts

@@ -157,6 +157,10 @@ export interface TelegramWorkspaceExternalProtectionEvidence {
     acceptedWork: TelegramWorkspaceProtectionState;
     deliveryAuthority: TelegramWorkspaceProtectionState;
 }
+/** Per-binding probe; `withSnapshot` lets one occupancy capture share binding-independent evidence reads. */
+export type TelegramWorkspaceExternalProtectionCapture = ((binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceExternalProtectionEvidence) & {
+    withSnapshot?: <T>(capture: () => T) => T;
+};
 export interface TelegramWorkspaceSlotOccupancySnapshot {
     bindings: TelegramWorkspaceSlotOccupancy[];
     reservedSlots: string[];
@@ -549,7 +553,7 @@ export interface TelegramTopicTargetStore {
         bindingUpdatedAtMs: number;
     }, isCurrent: () => boolean) => Promise<boolean>;
     /** Caller must separately prove no external live owner, accepted work, or delivery authority. */
-    captureWorkspaceSlotOccupancy: (getExternalProtection: (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceExternalProtectionEvidence, options?: {
+    captureWorkspaceSlotOccupancy: (getExternalProtection: TelegramWorkspaceExternalProtectionCapture, options?: {
         expectedRetirement?: TelegramWorkspaceRetirementIntent;
     }) => TelegramWorkspaceSlotOccupancySnapshot;
     hasWorkspaceBinding: (cwd: string, sessionId?: string) => boolean;

package/node_modules/@llblab/pi-telegram/dist/lib/threads.js

@@ -4681,7 +4681,8 @@ export function createTelegramTopicTargetStore(options) {
         },
         captureWorkspaceSlotOccupancy(getExternalProtection, options) {
             const nowMs = getNowMs();
-            const bindings = Array.from(workspaceBindings.values()).map((binding) => {
+            const inSnapshot = getExternalProtection.withSnapshot ?? ((capture) => capture());
+            const bindings = inSnapshot(() => Array.from(workspaceBindings.values()).map((binding) => {
                 const slot = binding.slot?.toLowerCase() ?? "";
                 const locallyProtected = isWorkspaceBindingLocallyProtected(binding, nowMs, {
                     requireBindingSlot: true,
@@ -4711,7 +4712,7 @@ export function createTelegramTopicTargetStore(options) {
                         : {}),
                     protection,
                 };
-            });
+            }));
             const localReservedSlots = [
                 ...Array.from(workspaceClaims.values()).map((claim) => claim.identity.slot),
                 ...Array.from(records.values())

package/node_modules/@llblab/pi-telegram/dist/lib/workspace-retirement.d.ts

@@ -57,6 +57,8 @@ export declare function captureTelegramWorkspaceJournalProtectionSources(input:
         complete: boolean;
         createResolver: (path: string) => () => TelegramWorkspaceJournalReader | undefined;
     };
+    /** Snapshot-scoped reuse of binding-independent (shared/discovered) source reads. */
+    sharedSourceReads?: Map<string, TelegramWorkspaceJournalProtectionSource>;
 }): TelegramWorkspaceJournalProtectionCapture;
 export type TelegramWorkspaceJournalProtectionSource = {
     kind: "available";
@@ -158,9 +160,11 @@ interface TelegramWorkspaceProtectionObserverDeps {
     getDeliveryAuthorityProtection?: (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceProtectionState;
 }
 export interface TelegramWorkspaceProtectionObserver {
-    capture: (binding: TelegramWorkspaceThreadBinding, options?: {
+    capture: ((binding: TelegramWorkspaceThreadBinding, options?: {
         requireBindingProvenance?: boolean;
-    }) => TelegramWorkspaceExternalProtectionEvidence;
+    }) => TelegramWorkspaceExternalProtectionEvidence) & {
+        withSnapshot?: <T>(capture: () => T) => T;
+    };
     captureJournalSources: (binding: TelegramWorkspaceThreadBinding) => TelegramWorkspaceJournalProtectionCapture;
     getJournalWriterProtection: (journalBindingKey: string) => TelegramWorkspaceProtectionState;
 }

package/node_modules/@llblab/pi-telegram/dist/lib/workspace-retirement.js

@@ -46,27 +46,41 @@ export function captureTelegramWorkspaceJournalProtectionSources(input) {
     let complete = input.binding.journalBindingsComplete === true ||
         input.discovery?.complete === true;
     const capture = (scope, resolve) => {
+        const sharedKey = scope.kind === "shared"
+            ? "shared"
+            : scope.kind === "discovered"
+                ? `discovered:${scope.path}`
+                : undefined;
+        let source = sharedKey === undefined
+            ? undefined
+            : input.sharedSourceReads?.get(sharedKey);
+        if (!source) {
+            source = readSource(scope, resolve);
+            if (sharedKey !== undefined)
+                input.sharedSourceReads?.set(sharedKey, source);
+        }
+        if (source.kind === "unknown")
+            complete = false;
+        sources.push(source);
+    };
+    const readSource = (scope, resolve) => {
         try {
             const binding = resolve();
-            if (!binding) {
-                complete = false;
-                sources.push({ kind: "unknown", scope });
-                return;
-            }
+            if (!binding)
+                return { kind: "unknown", scope };
             const read = binding.readForProtection ?? binding.journal.read;
             const snapshot = input.withJournalReference
                 ? input.withJournalReference(binding, read)
                 : read();
-            sources.push({
+            return {
                 kind: "available",
                 scope,
                 entries: snapshot.entries,
                 ...(snapshot.exists === undefined ? {} : { exists: snapshot.exists }),
-            });
+            };
         }
         catch {
-            complete = false;
-            sources.push({ kind: "unknown", scope });
+            return { kind: "unknown", scope };
         }
     };
     capture({ kind: "shared" }, input.resolveLeader);
@@ -292,8 +306,38 @@ export function captureTelegramWorkspaceExternalProtection(input) {
 }
 /** Shared read-only observer: protection and metadata pruning use the same scoped evidence path. */
 export function createTelegramWorkspaceProtectionObserver(deps) {
+    // One occupancy snapshot probes every binding synchronously; namespace and shared/discovered
+    // journal reads are binding-independent, so read them once per snapshot instead of per binding.
+    // Never widen this beyond one synchronous capture: post-fence rechecks need fresh evidence.
+    let snapshot;
+    const inspectNamespace = () => {
+        if (!snapshot)
+            return deps.inspectJournalNamespace?.();
+        if (!snapshot.namespace) {
+            try {
+                snapshot.namespace = { value: deps.inspectJournalNamespace?.() };
+            }
+            catch (error) {
+                snapshot.namespace = { error };
+            }
+        }
+        if ("error" in snapshot.namespace)
+            throw snapshot.namespace.error;
+        return snapshot.namespace.value;
+    };
+    const withSnapshot = (run) => {
+        if (snapshot)
+            return run();
+        snapshot = { reads: new Map() };
+        try {
+            return run();
+        }
+        finally {
+            snapshot = undefined;
+        }
+    };
     const captureJournalSources = (candidate) => {
-        const namespace = deps.inspectJournalNamespace?.();
+        const namespace = inspectNamespace();
         if (deps.inspectJournalNamespace &&
             (!namespace ||
                 namespace.sources.filter((source) => source.role === "polling")
@@ -332,9 +376,10 @@ export function createTelegramWorkspaceProtectionObserver(deps) {
                     },
                 }
                 : {}),
+            ...(snapshot ? { sharedSourceReads: snapshot.reads } : {}),
         });
     };
-    const capture = function (binding, options) {
+    const captureOne = function (binding, options) {
         return captureTelegramWorkspaceExternalProtection({
             binding,
             requireBindingProvenance: options?.requireBindingProvenance,
@@ -384,7 +429,7 @@ export function createTelegramWorkspaceProtectionObserver(deps) {
         });
     };
     return {
-        capture,
+        capture: Object.assign(captureOne, { withSnapshot }),
         captureJournalSources,
         getJournalWriterProtection: deps.getJournalWriterProtection ?? (() => "unknown"),
     };

package/node_modules/@llblab/pi-telegram/dist/package.json

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

package/node_modules/@llblab/pi-telegram/docs/multi-instance-bus.md

@@ -128,7 +128,7 @@ This operator-approved disposable-session policy is not Thread deletion, receipt
 
 ### Follower Registration And Session Readiness
 
-Manual Connect may carry a Pi command-context object distinct from the receiver's canonical session context. Binding preparation uses that canonical object only after both contexts prove the same current, leader-acknowledged session ID and session generation; a distinct object requires explicit active-context and generation ports. Readiness captures the canonical object and rechecks its identity after preparation and on every read. Missing, inactive, foreign or replaced canonical contexts grant no inbound authority. Same-session command-context refresh preserves the prepared worker and held input; generation, session or registration replacement still invalidates readiness. Worker context equality and exact journal/custody checks remain unchanged.
+Manual Connect may carry a Pi command-context object distinct from the receiver's canonical session context. Binding preparation uses that canonical object only after both contexts prove the same current, leader-acknowledged session ID and session generation; a distinct object requires explicit active-context and generation ports. Readiness captures the canonical object and rechecks its identity after preparation and on every read. Missing, inactive, foreign or replaced canonical contexts grant no inbound authority. Same-session command-context refresh preserves the prepared worker and held input; generation, session or registration replacement still invalidates readiness. Worker context equality and exact journal/custody checks remain unchanged. That distinction is a readiness guard only: promotion and every other post-online behavior use the canonical live session context, so a fresh Pi context object for the same session never blocks or changes them, and a replaced session generation or ID revokes them.
 
 Same-target registration distinguishes the provisional Workspace claim from the binding actually returned by commit. A reused target may retain its existing slot while changing binding key; before persistence and registration publication, the leader aligns that target's owner record and registration result with the committed slot. The final exact binding/slot/target check and leader epoch/profile/operator fences remain mandatory; drift refuses publication rather than weakening the guard. Re-keying preserves retained historical journal keys and exact session/recipient source tuples, and cannot turn unknown retained coverage into a completeness proof. Independent bindings and their slots/history remain untouched.
 
@@ -271,6 +271,8 @@ Leader election is liveness-proof-gated and lock-backed. Since 0.54 the leader w
 
 Followers first try to re-register after leader reload or unknown-heartbeat responses, carrying their last known target, slot, and thread name so the new leader can reuse the same binding. Follower Bot API calls already admitted by the active Pi turn wait for that bounded re-registration and capture its new exact generation before entering transport; they do not fail merely because recovery temporarily cleared local registration, and they never replay after an ambiguous transport commit. After the grace window followers promote only when the exact observed leader lease has become stale or inactive; an unavailable IPC endpoint never authorizes replacing a still-live owner. If the exact carried target is absent from persisted bindings, the leader first runs the same synchronous visibility probe: success recovers it instead of creating another Telegram thread, explicit stale evidence provisions a replacement, and ambiguous failure rejects registration. An ambiguous absent-target probe persists only non-routable `probe-required` restoration evidence, so targetless retries, successor follower processes with the same exact Workspace claim, and leader reloads probe that exact target again instead of activating it or provisioning a speculative replacement. A carried slot survives only when that slot remains free. Every successful reuse refreshes the binding timestamp. The leader never restores persisted followers into the live registry speculatively. Absent follower records remain durable restart hints until explicit stale, deleted, offline, or reconciliation evidence invalidates them; only fresh authenticated registration creates live routing authority. This preserves real thread bindings through reload and process-absence gaps without allowing historical records or competing pollers to masquerade as live state.
 
+Participation is a property of live registered state alone: eligibility, deferral, and promotion depend on the acknowledged slot, the authenticated registration generation, and the current session, never on how that instance came online. A fresh Pi context object for the same session carries the same authority, and only a replaced session generation or ID revokes it.
+
 ## Leader/Follower Communication
 
 ### Protocol identity and compatibility