@llblab/pi-kit 0.35.0 → 0.35.2

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

@@ -1667,7 +1667,7 @@ export function createTelegramCommandHandler(deps) {
         const captured = { ...deps }, parsed = { ...command }, message = parsed.name === "status"
             ? copySelectedMenuCarrier(original)
             : copySelectedReplyAnchor(original);
-        const assertRecipientCurrent = admission.assertRecipientCurrent, report = admission.reportCompleted;
+        const assertRecipientCurrent = admission.assertRecipientCurrent, report = admission.reportCompleted, beforeEffects = admission.beforeEffects;
         const effects = parsed.name === "status"
             ? undefined
             : {
@@ -1693,8 +1693,13 @@ export function createTelegramCommandHandler(deps) {
                 throw new Error(`Selected ${parsed.name} plan owner is unavailable.`);
         };
         return issueSelectedOnce(assertCurrent, async () => {
-            if (plan.completion === "before-effect" && !report.call(admission))
-                return false;
+            if (plan.completion === "before-effect") {
+                if (!report.call(admission))
+                    return false;
+                if (beforeEffects)
+                    await beforeEffects();
+                assertRecipientCurrent();
+            }
             return prepared.run({
                 message,
                 command: parsed,
@@ -1720,7 +1725,7 @@ export function createTelegramCommandHandler(deps) {
             ...copySelectedReplyAnchor(original),
             from: { ...original.from },
         };
-        const assertRecipientCurrent = admission.assertRecipientCurrent, reportCompleted = admission.reportCompleted;
+        const assertRecipientCurrent = admission.assertRecipientCurrent, reportCompleted = admission.reportCompleted, beforeEffects = admission.beforeEffects;
         const assertAdmissionCurrent = createSelectedSemanticGuard(admission, () => captured.assertExecutionCurrent?.(original), false);
         const assertSemanticCurrent = () => {
             assertAdmissionCurrent();
@@ -1732,7 +1737,7 @@ export function createTelegramCommandHandler(deps) {
             persistAllowedUserId: async () => {
                 throw new Error(`Selected ${name} cannot acquire pairing authority.`);
             },
-        }, { assertSemanticCurrent, assertRecipientCurrent, reportCompleted }));
+        }, { assertSemanticCurrent, assertRecipientCurrent, reportCompleted, beforeEffects }));
     };
     const prepareSelectedConfirmation = (name) => (command, messages, ctx, admission) => {
         const original = messages[0], captured = { ...deps };
@@ -2036,7 +2041,7 @@ export function createTelegramCommandHandler(deps) {
                 typeof admission.reportCompleted !== "function")
                 return undefined;
             const assertSourceCurrent = admission.assertSourceCurrent, assertRecipientCurrent = admission.assertRecipientCurrent;
-            const reportCompleted = admission.reportCompleted, assertExecutionCurrent = deps.assertExecutionCurrent;
+            const reportCompleted = admission.reportCompleted, beforeEffects = admission.beforeEffects, assertExecutionCurrent = deps.assertExecutionCurrent;
             const assertIssuanceCurrent = () => {
                 assertSourceCurrent.call(admission);
                 assertExecutionCurrent?.call(deps, original);
@@ -2060,8 +2065,14 @@ export function createTelegramCommandHandler(deps) {
                 openSettingsMenu: menuDeps.openSettingsMenu &&
                     ((value, context) => menuDeps.openSettingsMenu(value, context, recipientOptions)),
             };
-            return issueSelectedOnce(assertIssuanceCurrent, async () => reportCompleted.call(admission) &&
-                handleTelegramCommandRuntime(name, message, ctx, recipientDeps, args));
+            return issueSelectedOnce(assertIssuanceCurrent, async () => {
+                if (!reportCompleted.call(admission))
+                    return false;
+                if (beforeEffects)
+                    await beforeEffects();
+                assertRecipientCurrent();
+                return handleTelegramCommandRuntime(name, message, ctx, recipientDeps, args);
+            });
         },
     });
 }
@@ -2157,6 +2168,8 @@ async function handleTelegramHelpCommand(commandName, message, ctx, deps, admiss
         assertSemanticCurrent();
         if (!admission.reportCompleted())
             return false;
+        if (admission.beforeEffects)
+            await admission.beforeEffects();
         admission.assertRecipientCurrent();
     }
     const assertEffectCurrent = admission?.assertRecipientCurrent ??

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

@@ -658,6 +658,12 @@ export default function (pi) {
     const promptDispatchRuntime = Runtime.createTelegramPromptDispatchRuntime({
         lifecycle,
         typing,
+        failureLog: runtimeDiagnostics.createFailureLog({
+            category: "typing",
+            failurePhase: "typing-presence",
+            outcomePhase: "typing-presence-recovered",
+            label: "typing presence",
+        }),
         getDefaultChatId: proactivePushChatIdGetter,
         isThreadedMode() {
             return deliveryTargetPolicyRuntime.getTargetPolicyView().threaded === true;
@@ -1033,6 +1039,29 @@ export default function (pi) {
         delivery: deliveryLifecycleRuntime,
         api: telegramApiTargetActivityRuntime,
     });
+    const prepareTemporaryThreadJournalInspection = function (target, requiredJournalBindingKeys, ownInputs) {
+        const binding = resolveTelegramUpdateJournalBinding();
+        const botToken = configStore.getBotToken();
+        if (!binding || !botToken)
+            return undefined;
+        const profile = configStore.getActiveProfileName() ?? "default";
+        const botIdentity = Journal.createTelegramUpdateJournalBotIdentity({ botToken, botId: getTelegramBotId() });
+        return {
+            directory: Paths.resolveTelegramTempDir(), profile, botIdentity,
+            pollingPath: telegramLeaderJournalPath.resolve(configStore.getActiveProfileName()),
+            requiredJournalBindingKeys: [binding.recoveryKey, ...requiredJournalBindingKeys],
+            ...(target.threadId !== undefined && ownInputs
+                ? { cleanup: { target: { chatId: target.chatId, threadId: target.threadId }, ownInputs } } : {}),
+            limits: { maxDirectoryEntries: 10_000, maxFiles: 4096, maxBytes: 64 * 1024 * 1024,
+                maxEntries: 10_000, maxWork: 100_000 },
+            withSourceReference(path, operation) {
+                return telegramJournalReferenceRegistry.withReference({
+                    referenceClass: "operator-disposition",
+                    recoveryKey: Journal.createTelegramUpdateJournalBindingKey({ path, profileName: profile, botIdentity }),
+                }, operation);
+            },
+        };
+    };
     const inboundRouteRuntime = Routing.createTelegramInboundRouteRuntime({
         configStore,
         callApi: callTelegramApi,
@@ -1112,53 +1141,24 @@ export default function (pi) {
             });
         },
         inspectTemporaryThreadSources(target, requiredJournalBindingKeys, ownInputs) {
-            const binding = resolveTelegramUpdateJournalBinding();
-            const botToken = configStore.getBotToken();
-            if (!binding || !botToken)
+            const input = prepareTemporaryThreadJournalInspection(target, requiredJournalBindingKeys, ownInputs);
+            if (!input)
                 return undefined;
-            const profile = configStore.getActiveProfileName() ?? "default";
-            const botIdentity = Journal.createTelegramUpdateJournalBotIdentity({
-                botToken,
-                botId: getTelegramBotId(),
-            });
             return withTelegramJournalSourceSerialization(function () {
-                return Journal.isTelegramThreadCleanupJournalNamespaceClear({
-                    directory: Paths.resolveTelegramTempDir(),
-                    profile,
-                    botIdentity,
-                    pollingPath: telegramLeaderJournalPath.resolve(configStore.getActiveProfileName()),
-                    requiredJournalBindingKeys: [
-                        binding.recoveryKey,
-                        ...requiredJournalBindingKeys,
-                    ],
-                    ...(target.threadId !== undefined && ownInputs
-                        ? {
-                            cleanup: {
-                                target: { chatId: target.chatId, threadId: target.threadId },
-                                ownInputs,
-                            },
-                        }
-                        : {}),
-                    limits: {
-                        maxDirectoryEntries: 10_000,
-                        maxFiles: 4096,
-                        maxBytes: 64 * 1024 * 1024,
-                        maxEntries: 10_000,
-                        maxWork: 100_000,
-                    },
-                    withSourceReference(path, operation) {
-                        return telegramJournalReferenceRegistry.withReference({
-                            referenceClass: "operator-disposition",
-                            recoveryKey: Journal.createTelegramUpdateJournalBindingKey({
-                                path,
-                                profileName: profile,
-                                botIdentity,
-                            }),
-                        }, operation);
-                    },
-                })
-                    ? []
-                    : undefined;
+                return Journal.isTelegramThreadCleanupJournalNamespaceClear(input) ? [] : undefined;
+            });
+        },
+        recoverTemporaryThreadDeadQueueOwners(target, requiredJournalBindingKeys, ownInputs, isCurrent) {
+            const input = prepareTemporaryThreadJournalInspection(target, requiredJournalBindingKeys, ownInputs);
+            if (!input || !isCurrent())
+                return 0;
+            return Journal.recoverTelegramThreadCleanupDeadQueueOwners({
+                ...input, isCurrent, withSourceSerialization: withTelegramJournalSourceSerialization,
+                recoveryOwner: {
+                    instanceId: telegramInstanceId, processId: telegramProcessId,
+                    processBirthId: telegramQueueProcessBirthId,
+                    sessionGeneration: telegramSessionContextStore.getGeneration(),
+                },
             });
         },
         hasWorkspaceRestoreAuthority() {
@@ -1252,12 +1252,14 @@ export default function (pi) {
             if (telegramBusFollowerRegistrationState.isRegistered() ||
                 target.threadId === undefined)
                 return undefined;
+            // Pi creates a fresh context object per event and command, so authority follows the session, not the object.
+            const sessionGeneration = telegramSessionContextStore.getGeneration();
             return Threads.createTelegramWorkspaceThreadRenameRecipient({
                 store: threadStore,
                 instanceId: telegramInstanceId,
                 target,
                 assertAuthority() {
-                    if (telegramSessionContextStore.get() !== ctx)
+                    if (!telegramSessionContextStore.isCurrent(ctx, sessionGeneration))
                         throw new Error("Telegram Thread name dialog lost Pi context.");
                 },
                 getAuthority: threadNameRecipientAuthority.getAuthority,
@@ -1571,6 +1573,12 @@ export default function (pi) {
     });
     const telegramBusFollowerAssembly = BusFollower.createTelegramBusFollowerRuntimeAssembly({
         instanceId: telegramInstanceId,
+        failureLog: runtimeDiagnostics.createFailureLog({
+            category: "bus",
+            failurePhase: "follower-heartbeat",
+            outcomePhase: "follower-heartbeat-recovered",
+            label: "follower heartbeat",
+        }),
         registrationState: telegramBusFollowerRegistrationState,
         recordRuntimeEvent,
         receiver: {
@@ -1900,6 +1908,12 @@ export default function (pi) {
     });
     const telegramThreadCapabilityRuntime = Polling.createTelegramThreadCapabilityOrchestration({
         state: telegramThreadCapabilityState,
+        failureLog: runtimeDiagnostics.createFailureLog({
+            category: "bus",
+            failurePhase: "capability-monitor",
+            outcomePhase: "capability-monitor-recovered",
+            label: "Threaded Mode capability probe",
+        }),
         getAllowedUserId: configStore.getAllowedUserId,
         callApi: callTelegramApi,
         topicTargetStore: threadStore,
@@ -2485,6 +2499,7 @@ export default function (pi) {
         deleteMessage: deleteTelegramMessage,
         sendGuestReply,
         editGuestReply,
+        editGuestInlineMessage: telegramApiRuntime.editGuestInlineMessage,
         stopGuestPlaceholder: guestPlaceholderRuntime.stop,
         finalizeMarkdownPreview,
         preparePreviewDelivery,

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

@@ -751,6 +751,13 @@ export declare function isTelegramThreadCleanupJournalNamespaceClear(input: Tele
         }[];
     };
 }): boolean;
+/** Demand-driven recovery only; caller holds temporary-cleanup admission. Never a deletion grant. */
+export declare function recoverTelegramThreadCleanupDeadQueueOwners(input: Parameters<typeof isTelegramThreadCleanupJournalNamespaceClear>[0] & {
+    recoveryOwner: TelegramUpdateJournalQueueOwnerIdentity;
+    isCurrent: () => boolean;
+    withSourceSerialization: NonNullable<TelegramUpdateJournalStoreOptions["withSourceSerialization"]>;
+    getQueueProcessLiveness?: TelegramUpdateJournalStoreOptions["getQueueProcessLiveness"];
+}): number;
 export declare function publishTelegramUpdateJournalSegment(path: string, segment: TelegramUpdateJournalSegment): TelegramUpdateJournalSegmentPublicationResult;
 export declare function createTelegramUpdateQueueHandoffToken(): string;
 export declare function createTelegramUpdateJournalBotIdentity(input: {

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

@@ -1988,6 +1988,86 @@ export function isTelegramThreadCleanupJournalNamespaceClear(input) {
     return namespace.sources.every((source) => source.evidence.kind === "absent" ||
         source.evidence.file.entries.every((entry) => isUnrelatedPlainInput(entry, source.path)));
 }
+/** Demand-driven recovery only; caller holds temporary-cleanup admission. Never a deletion grant. */
+export function recoverTelegramThreadCleanupDeadQueueOwners(input) {
+    return input.withSourceSerialization(() => {
+        const assertCurrent = () => {
+            if (!input.isCurrent())
+                throw new Error("Temporary cleanup queue recovery lost authority.");
+        };
+        assertCurrent();
+        if (!input.cleanup)
+            return 0;
+        // Validate exact references and complete namespace coverage before considering any mutation.
+        if (isTelegramThreadCleanupJournalNamespaceClear(input))
+            return 0;
+        const namespace = inspectTelegramSessionJournalNamespace(input);
+        if (namespace.retainedInputs?.some(value => value.state !== "committed") ||
+            input.requiredJournalBindingKeys.some(key => !namespace.sources.some(source => source.path === getTelegramUpdateJournalBindingPath(key) && source.evidence.kind === "present")))
+            return 0;
+        const plans = [];
+        for (const source of namespace.sources) {
+            if (source.evidence.kind !== "present")
+                continue;
+            const file = source.evidence.file;
+            if (file.version !== TELEGRAM_UPDATE_JOURNAL_VERSION)
+                continue;
+            const groups = new Map();
+            for (const entry of file.entries) {
+                if (!entry.queueReceiptId)
+                    continue;
+                const group = groups.get(entry.queueReceiptId) ?? [];
+                group.push(entry);
+                groups.set(entry.queueReceiptId, group);
+            }
+            for (const group of groups.values()) {
+                const entry = group[0];
+                if (entry.state !== "queued" || !entry.queueReceiptId || !entry.queueOwner ||
+                    !entry.queueKind || entry.queueHandoff || entry.inputClaim)
+                    continue;
+                if (group.some(value => value.state !== "queued" || value.queueHandoff || value.inputClaim ||
+                    value.queueKind !== entry.queueKind || !isDeepStrictEqual(value.queueOwner, entry.queueOwner)))
+                    continue;
+                plans.push({ path: source.path, recovery: {
+                        queueKind: entry.queueKind, receiptId: entry.queueReceiptId,
+                        sourceUpdateIds: group.map(value => value.updateId).sort((a, b) => a - b),
+                        deadOwner: cloneJournalQueueOwner(entry.queueOwner), recoveryOwner: { ...input.recoveryOwner },
+                    } });
+            }
+        }
+        const liveness = input.getQueueProcessLiveness ?? getTelegramProcessLiveness;
+        const dead = plans.filter(plan => {
+            assertCurrent();
+            const result = liveness(plan.recovery.deadOwner);
+            assertCurrent();
+            return result === "dead";
+        });
+        let removed = 0;
+        for (const plan of dead) {
+            assertCurrent();
+            removed += input.withSourceReference(plan.path, () => {
+                const journal = createTelegramUpdateJournalStore({
+                    path: plan.path, profileName: input.profile, botIdentity: input.botIdentity,
+                    queueRuntimeIdentity: input.recoveryOwner,
+                    // This private synchronous store stays inside the cross-family serializer already held above.
+                    withSourceSerialization(operation) { assertCurrent(); return operation(); },
+                    sourceAccess: { directory: dirname(plan.path), limits: input.limits },
+                    getQueueProcessLiveness(owner) {
+                        assertCurrent();
+                        const result = liveness(owner);
+                        assertCurrent();
+                        return result;
+                    },
+                    withWriterAdmission(operation) { assertCurrent(); return operation(); },
+                });
+                // The journal transaction rechecks whole-group identity, absence of handoff and fresh process-death proof.
+                return journal.recoverDeadQueueOwner(plan.recovery).recoveredUpdateIds.length;
+            });
+        }
+        assertCurrent();
+        return removed;
+    });
+}
 function cloneEntry(entry) {
     return {
         ...entry,

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

@@ -4,6 +4,40 @@
  * Owns bounded JSONL runtime evidence files, previous-log preservation, and profile-aware log paths without becoming routing state
  */
 import * as Status from "./status.ts";
+/** Sink shape shared with the runtime event recorder this domain already owns. */
+export type TelegramFailureRecordSink = (category: string, errorOrMessage: unknown, details: Record<string, unknown>) => void;
+export interface TelegramFailureRunSummary {
+    signature: string;
+    failedAttempts: number;
+    suppressedFailures: number;
+    failedForMs: number;
+}
+export interface TelegramFailureRunLog {
+    /** Records one failure; a repeated identical failure only extends the current run and returns false. */
+    record: (error: unknown, details?: Record<string, unknown>) => boolean;
+    /** Closes the run after a success, emitting its single outcome record. */
+    settled: () => TelegramFailureRunSummary | undefined;
+    /** Ends the run without an outcome record, for a stop or replacement that reports its own outcome. */
+    reset: () => void;
+}
+export interface TelegramFailureRunLogInput {
+    category: string;
+    failurePhase: string;
+    outcomePhase: string;
+    /** Human-readable subject for the outcome record, e.g. `follower heartbeat`. */
+    label: string;
+    record?: TelegramFailureRecordSink;
+    /** Static context reapplied to every record of this phase, e.g. a session or profile key. */
+    context?: () => Record<string, unknown>;
+    getNowMs?: () => number;
+}
+/** Stable identity of one failure kind: errno when present, otherwise the failure text. */
+export declare function getTelegramFailureSignature(error: unknown): string;
+/**
+ * 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 declare function createTelegramFailureRunLog(input: TelegramFailureRunLogInput): TelegramFailureRunLog;
 type TelegramLogPathInput = string | (() => string);
 interface TelegramRuntimeJsonlEvent {
     at: number;
@@ -47,6 +81,8 @@ interface TelegramRuntimeDiagnosticsStatusPorts<TContext> {
 interface TelegramRuntimeDiagnosticsRuntime<TContext> {
     events: Status.TelegramRuntimeEventRecorder;
     recordRuntimeEvent(category: string, error: unknown, details?: Record<string, unknown>): void;
+    /** A phase-scoped failure log whose records travel through this runtime's own event pipeline. */
+    createFailureLog(input: Omit<TelegramFailureRunLogInput, "record">): TelegramFailureRunLog;
     bindStorage(ports: {
         getBotToken(): string | undefined;
         getProfileName(): string | undefined;

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/outbound-attachments.d.ts

@@ -73,6 +73,7 @@ export interface TelegramQueuedOutboundAttachmentView {
 export interface TelegramOutboundAttachmentQueueTargetView {
     queuedAttachments: TelegramQueuedOutboundAttachmentView[];
     guestQueryId?: string;
+    guestInlineMessageId?: string;
 }
 export interface TelegramQueuedOutboundAttachmentTurnView extends TelegramOutboundAttachmentQueueTargetView {
     chatId: number;
@@ -161,6 +162,17 @@ export declare function queueTelegramOutboundAttachments(options: {
 }): Promise<TelegramOutboundAttachmentToolResult>;
 export declare function deliverTelegramGuestCachedAttachment(options: {
     guestQueryId: string;
+    guestInlineMessageId?: string;
+    editGuestInlineMessage?: (inlineMessageId: string, content: {
+        media: {
+            type: "photo" | "document" | "audio";
+            media: string;
+            caption?: string;
+        };
+    }, options: {
+        assertAuthority: () => void;
+    }) => Promise<void>;
+    isDeliveryActive?: () => boolean;
     stagingChatId: number;
     stagingTarget?: TelegramTarget;
     attachment: TelegramQueuedOutboundAttachmentView;

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

@@ -375,6 +375,9 @@ export async function queueTelegramOutboundAttachments(options) {
         maxAttachmentSizeBytes: options.maxAttachmentSizeBytes,
         statPath: options.statPath,
     });
+    if (options.activeTurn.guestInlineMessageId && pendingAttachments.some((attachment) => getTelegramGuestAttachmentTransport(attachment.path).fileField === "voice")) {
+        throw new Error("Telegram Guest Mode cannot replace an inline placeholder with a voice note; no attachment was queued. Use MP3 audio or a normal bot chat.");
+    }
     options.activeTurn.queuedAttachments.push(...pendingAttachments);
     const added = pendingAttachments.map((attachment) => attachment.path);
     return {
@@ -389,6 +392,16 @@ export async function queueTelegramOutboundAttachments(options) {
 }
 export async function deliverTelegramGuestCachedAttachment(options) {
     const transport = getTelegramGuestAttachmentTransport(options.attachment.path);
+    const isActive = () => options.isDeliveryActive?.() !== false;
+    const assertActive = () => {
+        if (!isActive())
+            throw new Error("Guest attachment delivery lost authority.");
+    };
+    if (!isActive())
+        return;
+    if (options.guestInlineMessageId && (!options.editGuestInlineMessage || transport.fileField === "voice")) {
+        throw new Error("Guest inline attachment editing is unavailable for this media.");
+    }
     let stagingMessageId;
     let answerAttempted = false;
     try {
@@ -397,6 +410,8 @@ export async function deliverTelegramGuestCachedAttachment(options) {
             ...getTelegramMultipartTargetFields(options.stagingTarget),
         }, transport.fileField, options.attachment.path, options.attachment.fileName));
         stagingMessageId = message.message_id;
+        if (!isActive())
+            return;
         const caption = options.caption
             ? Array.from(options.caption).slice(0, 1024).join("")
             : undefined;
@@ -446,11 +461,26 @@ export async function deliverTelegramGuestCachedAttachment(options) {
                 ...(caption ? { caption } : {}),
             };
         }
+        if (!isActive())
+            return;
         answerAttempted = true;
-        await options.answerGuestQuery(options.guestQueryId, result);
+        if (options.guestInlineMessageId && options.editGuestInlineMessage) {
+            if (result.type === "voice")
+                throw new Error("Voice notes cannot replace inline placeholders.");
+            const media = result.type === "photo" ? result.photo_file_id
+                : result.type === "audio" ? result.audio_file_id : result.document_file_id;
+            await options.editGuestInlineMessage(options.guestInlineMessageId, {
+                media: { type: result.type, media, ...(caption ? { caption } : {}) },
+            }, { assertAuthority: assertActive });
+        }
+        else {
+            await options.answerGuestQuery(options.guestQueryId, result);
+        }
     }
     catch (error) {
-        if (!answerAttempted && options.answerGuestText && options.fallbackText) {
+        if (!isActive())
+            return;
+        if (!options.guestInlineMessageId && !answerAttempted && options.answerGuestText && options.fallbackText) {
             answerAttempted = true;
             await options.answerGuestText(options.guestQueryId, options.fallbackText);
         }
@@ -459,7 +489,7 @@ export async function deliverTelegramGuestCachedAttachment(options) {
         }
     }
     finally {
-        if (stagingMessageId !== undefined) {
+        if (stagingMessageId !== undefined && isActive()) {
             try {
                 await options.deleteMessage(options.stagingChatId, stagingMessageId);
             }

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;