@llblab/pi-kit 0.34.3 → 0.35.1

package/node_modules/@llblab/pi-telegram/lib/routing.ts

@@ -1568,6 +1568,13 @@ export interface TelegramInboundRouteRuntimeDeps<
     requiredJournalBindingKeys: readonly string[],
     ownInputs?: readonly Threads.TelegramTemporaryThreadInput[],
   ) => readonly number[] | undefined;
+  /** Explicit cleanup-only recovery; never called by a read-only protection observer. */
+  recoverTemporaryThreadDeadQueueOwners?: (
+    target: Queue.TelegramQueueTarget,
+    requiredJournalBindingKeys: readonly string[],
+    ownInputs: readonly Threads.TelegramTemporaryThreadInput[],
+    isCurrent: () => boolean,
+  ) => number;
   /** Quiet period after the last cancelled input before one cleanup attempt; defaults to 0 ms. */
   temporaryThreadCleanupDelayMs?: number;
   /** Live-rebind cleanup attempt pacing; the bounded window ends in `not-issued`, never a time-based deletion. */
@@ -6837,6 +6844,93 @@ export function createTelegramInboundRouteRuntime<
     }
     await promptEnqueue(messages, ctx);
   };
+  /** Local menu acceptance owns a one-shot effect; source removal and cleanup precede its release, never its replay. */
+  const stageTemporaryRerouteMenu = async (
+    pending: PendingUnboundReroute,
+    command: Commands.ParsedTelegramCommand,
+    messages: TMessage[],
+    ctx: TContext,
+    assertRecipientCurrent: () => void,
+    completion: NonNullable<ReturnType<typeof Updates.prepareTelegramDeferredSourceCompletion>>,
+  ): Promise<(() => Promise<void>) | undefined> => {
+    const original = pending.messages[0];
+    const cap = captureTemporaryThreadAuthority(ctx);
+    const temporary = pending.temporaryThread ?? findCreatedTemporaryThread(pending.sourceTarget);
+    if (!cap?.isCurrent() || !temporary) return undefined;
+    let accept!: (value: boolean) => void, resume!: (value: boolean) => void;
+    const accepted = new Promise<boolean>(resolve => { accept = resolve; });
+    const released = new Promise<boolean>(resolve => { resume = resolve; });
+    const admission: Commands.TelegramSelectedCommandAdmission = {
+      assertSourceCurrent() {
+        if (!completion.isCurrent()) throw new Error("Rerouted menu source authority changed.");
+      },
+      assertRecipientCurrent,
+      reportCompleted() {
+        const result = completion.reportCompleted();
+        accept(result);
+        return result;
+      },
+      async beforeEffects() {
+        if (!(await released)) throw new Error("Rerouted menu execution was not released.");
+      },
+    };
+    const prepare = command.name === "start" ? commandHandler.prepareSelectedStartCommand
+      : command.name === "help" ? commandHandler.prepareSelectedHelpCommand : commandHandler.prepareSelectedMenuCommand;
+    const dispatch = prepare(command, messages, ctx, admission);
+    if (!dispatch) return undefined;
+    const execution = dispatch().catch(error => {
+      deps.recordRuntimeEvent?.("routing", error, { phase: "reroute-menu-execution" });
+      return false;
+    });
+    if (!(await Promise.race([accepted, execution.then(() => false)]))) {
+      resume(false);
+      await execution;
+      return undefined;
+    }
+    return async () => {
+      let allowEffects = false;
+      try {
+        const confirmed = await new Promise<boolean>(resolve => {
+          let done = false, unsubscribe: (() => void) | undefined;
+          const signal = Updates.getTelegramUpdateExecutionFence(original)?.signal;
+          const finish = (result: boolean) => {
+            if (done) return;
+            done = true;
+            clearTimeout(timer);
+            unsubscribe?.();
+            signal?.removeEventListener("abort", abort);
+            resolve(result);
+          };
+          const abort = () => finish(false);
+          const observe = () => {
+            if (!cap.isCurrent() || !completion.isCurrent()) finish(false);
+            else if (completion.inspectCompletion()) finish(true);
+          };
+          const timer = setTimeout(abort, deps.liveRebindCommandCompletionTimeoutMs ?? 8_000);
+          timer.unref?.();
+          unsubscribe = Updates.subscribeTelegramDeferredSourceCompletion(original, observe);
+          signal?.addEventListener("abort", abort, { once: true });
+          if (signal?.aborted) abort(); else observe();
+        });
+        if (!confirmed) throw new Error("Rerouted menu source removal is unconfirmed; execution remains suppressed.");
+        assertRecipientCurrent();
+        cancelTemporaryThreadCleanup(temporary.token);
+        try {
+          await runTemporaryThreadCleanup(temporary.token, cap, false);
+        } catch (error) {
+          // Cleanup uncertainty retains its canonical grant, not command execution authority or a retry license.
+          deps.recordRuntimeEvent?.("routing", error, { phase: "reroute-menu-cleanup" });
+        }
+        assertRecipientCurrent();
+        allowEffects = true;
+      } catch (error) {
+        deps.recordRuntimeEvent?.("routing", error, { phase: "reroute-menu-release" });
+      } finally {
+        resume(allowEffects);
+        await execution;
+      }
+    };
+  };
   const finalizePendingReroute = async (
     rerouteId: string,
     pending: PendingUnboundReroute,
@@ -7258,12 +7352,20 @@ export function createTelegramInboundRouteRuntime<
           });
         if (!cancelledCurrent()) return;
         entry = cap.adopt(entry);
-        if (
-          !entry ||
-          !cap.isCurrent() ||
-          isRerouteTargetProtected(target, undefined, entry)
-        )
-          return;
+        if (!entry || !cap.isCurrent()) return;
+        if (isRerouteTargetProtected(target, undefined, entry) && deps.recoverTemporaryThreadDeadQueueOwners &&
+            store.inspectTemporaryThreadTarget(entry, cap.authority)?.kind === "temporary") {
+          const inputs = Threads.getTelegramTemporaryThreadInputs(entry);
+          const removed = deps.recoverTemporaryThreadDeadQueueOwners(
+            target, [cap.journalBindingKey, ...inputs.map(input => input.journalBindingKey)],
+            inputs, cap.isCurrent,
+          );
+          if (removed > 0) deps.recordRuntimeEvent?.("routing",
+            "Discarded historical queue receipts from confirmed-dead owners before temporary Thread cleanup.",
+            { phase: "temporary-thread-dead-owner-recovery", removedUpdateCount: removed });
+        }
+        // Recovery is not deletion authority: recapture every ordinary protection after the journal CAS.
+        if (!cap.isCurrent() || isRerouteTargetProtected(target, undefined, entry)) return;
         const issued = store.issueTemporaryThreadCleanup(entry, cap.authority);
         if (!issued || !cap.isCurrent()) return;
         entry = issued.entry;
@@ -8658,6 +8760,7 @@ export function createTelegramInboundRouteRuntime<
   const executeUnboundRerouteCallbackOperation = async (
     query: TCallbackQuery,
     ctx: TContext,
+    afterAdmission: (release: () => Promise<void>) => void,
   ): Promise<boolean> => {
     const parsed = parseTelegramUnboundRerouteCallbackData(query.data);
     if (!parsed) return false;
@@ -9349,7 +9452,20 @@ export function createTelegramInboundRouteRuntime<
     const localMessages = pending.rerouteCopies
       ? cloneTelegramMessagesForThread(pending.messages, parsed.threadId, pending.rerouteCopies.bySourceUpdateId)
       : reroutedMessages;
-    await dispatchPendingRerouteMessages(pending, localMessages, ctx);
+    const command = pending.dispatchKind === "command"
+      ? getLiveRebindMenu(localMessages) ?? getLiveRebindHelp(localMessages) : undefined;
+    const completion = pending.rerouteCopies && command
+      ? Updates.prepareTelegramDeferredSourceCompletion(pending.messages[0]) : undefined;
+    if (command && completion) {
+      const release = await stageTemporaryRerouteMenu(pending, command, localMessages, ctx, assertRerouteCurrent, completion);
+      if (!release) {
+        await deps.answerCallbackQuery(query.id, "Command acceptance unconfirmed; not resending");
+        return true;
+      }
+      afterAdmission(release);
+    } else {
+      await dispatchPendingRerouteMessages(pending, localMessages, ctx);
+    }
     assertRerouteCurrent();
     pending.messages = [];
     return completeRoutedReroute();
@@ -9360,17 +9476,23 @@ export function createTelegramInboundRouteRuntime<
   ): Promise<boolean> => {
     const parsed = parseTelegramUnboundRerouteCallbackData(query.data);
     if (!parsed) return false;
-    return withPendingRerouteSelection(parsed.rerouteId, query, () => {
-      if (!deps.runWorkspaceOperation)
-        return executeUnboundRerouteCallbackOperation(query, ctx);
-      return deps.runWorkspaceOperation(
-        {
-          operationId: `workspace-reroute:${query.id}`,
-          operationKind: "workspace.route-unbound-thread",
-          scopes: [{ kind: "profile" }],
-        },
-        () => executeUnboundRerouteCallbackOperation(query, ctx),
-      );
+    return withPendingRerouteSelection(parsed.rerouteId, query, async () => {
+      let release: (() => Promise<void>) | undefined;
+      const operation = () => executeUnboundRerouteCallbackOperation(query, ctx, value => { release = value; });
+      try {
+        if (!deps.runWorkspaceOperation) return await operation();
+        return await deps.runWorkspaceOperation(
+          {
+            operationId: `workspace-reroute:${query.id}`,
+            operationKind: "workspace.route-unbound-thread",
+            scopes: [{ kind: "profile" }],
+          },
+          operation,
+        );
+      } finally {
+        // Keep the exact source references, but release the non-reentrant Workspace gate before cleanup.
+        await release?.();
+      }
     });
   };
   const handleUnboundRerouteCallback = async (

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

@@ -473,6 +473,8 @@ export interface TelegramAnswerGuestQueryOptions {
 }
 
 export interface TelegramEditGuestInlineMessageContent {
+  /** Cached media only: inline edits cannot upload a new local file. */
+  media?: { type: "photo" | "document" | "audio"; media: string; caption?: string };
   text?: string;
   richMessage?: TelegramInputRichMessage;
   parseMode?: "HTML";
@@ -917,10 +919,9 @@ export interface TelegramBridgeApiRuntime extends Pick<
     options?: TelegramAnswerGuestQueryOptions,
   ) => Promise<void>;
   /**
-   * Temporary Guest Mode ACK experiment: answers the guest query and returns
-   * the sent inline message id so the final answer can edit that early reply.
-   * Requires direct transport ownership; Telegram does not document editing
-   * guest answers, so this exists only to falsify that behavior live.
+   * Answers the guest query and retains the sent inline message id for final
+   * text or cached-media replacement. Requires direct transport ownership;
+   * actual guest-media rendering remains live-client gated.
    */
   answerGuestQueryForInlineMessage: (
     guestQueryId: string,
@@ -930,6 +931,7 @@ export interface TelegramBridgeApiRuntime extends Pick<
   editGuestInlineMessage: (
     inlineMessageId: string,
     content: TelegramEditGuestInlineMessageContent,
+    options?: Pick<TelegramApiCallOptions, "assertAuthority">,
   ) => Promise<void>;
   deleteMessage: (chatId: number, messageId: number) => Promise<void>;
   prepareTempDir: () => Promise<number>;
@@ -2404,14 +2406,29 @@ export function createTelegramBridgeApiRuntime(
     editGuestInlineMessage: async (
       inlineMessageId: string,
       content: TelegramEditGuestInlineMessageContent,
+      options?: Pick<TelegramApiCallOptions, "assertAuthority">,
     ) => {
+      if (content.media) {
+        try {
+          const result = await callRecorded("editMessageMedia", {
+            inline_message_id: inlineMessageId,
+            media: content.media,
+          }, { ...options, maxAttempts: 1, retryRateLimit: false });
+          if (result !== true) throw new Error("Missing inline edit acknowledgement.");
+        } catch (error) {
+          // Only a parsed rejection permits replacing this attempt with a failure notice.
+          if (isTelegramApiRequestRejected(error, "editMessageMedia")) throw error;
+          throw new TelegramApiCommitUnknownError("editMessageMedia", error);
+        }
+        return;
+      }
       await callRecorded("editMessageText", {
         inline_message_id: inlineMessageId,
         ...(content.richMessage
           ? { rich_message: content.richMessage }
           : { text: content.text }),
         ...(content.parseMode ? { parse_mode: content.parseMode } : {}),
-      });
+      }, options);
     },
     prepareTempDir: () =>
       prepareTelegramTempDir(deps.tempDir, deps.tempFileMaxAgeMs),

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

@@ -904,6 +904,8 @@ export interface TelegramTopicTargetStore {
       existingBindingOnly?: boolean;
       sessionId?: string;
       provisionProfileKey?: string;
+      /** Explicit same-process session handoff from `previousInstanceId`; never inferred. */
+      sessionHandoff?: boolean;
       onCapacityUnavailable?: () => void;
     },
   ) => TelegramWorkspaceBindingIdentity | undefined;
@@ -2721,10 +2723,16 @@ function liveRebindOldTargetUnknown(value: TelegramWorkspaceLiveRebindIntent): b
 function retainLiveRebind(value: TelegramWorkspaceLiveRebindIntent): boolean {
   return liveRebindActive(value) || liveRebindOldTargetUnknown(value) || value.oldTargetProtected === true;
 }
-function protectedLiveRebindOldTargets(snapshot: TelegramWorkspaceRestoreSnapshot | undefined): TelegramTarget[] {
+function provisioningProtectionIntents(snapshot: TelegramWorkspaceRestoreSnapshot): readonly Pick<TelegramWorkspaceRestoreIntent, "request">[] {
+  return [...snapshot.operations, ...(snapshot.liveRebindings ?? []).filter(retainLiveRebind)];
+}
+function protectedLiveRebindOldTargetIntents(snapshot: TelegramWorkspaceRestoreSnapshot | undefined): TelegramWorkspaceLiveRebindIntent[] {
   return (snapshot?.liveRebindings ?? []).filter(value =>
     value.oldTargetProtected === true || liveRebindOldTargetUnknown(value) || value.inputRelease !== undefined && value.cleanup === "issued",
-  ).map(value => ({ ...value.request.binding.target }));
+  );
+}
+function protectedLiveRebindOldTargets(snapshot: TelegramWorkspaceRestoreSnapshot | undefined): TelegramTarget[] {
+  return protectedLiveRebindOldTargetIntents(snapshot).map(value => ({ ...value.request.binding.target }));
 }
 function pendingWorkspaceRelocationRequests(
   snapshot: TelegramWorkspaceRestoreSnapshot | undefined,
@@ -2819,10 +2827,11 @@ function assertWorkspaceRestoreBindingProtection(
       throw new Error("Protected Workspace Restore owner target changed.");
     }
   }
-  for (const old of protectedLiveRebindOldTargets(file.workspaceRestore)) {
+  for (const { request } of protectedLiveRebindOldTargetIntents(file.workspaceRestore)) {
+    const old = request.binding.target;
     if (file.workspaceBindings?.some(value => targetMatches(value.target, old)) ||
       file.threads?.some(value => targetMatches(value.target, old) && ["active", "starting", "pending", "probe-required"].includes(value.status)) ||
-      file.pendingProvisions?.some(value => !value.target || targetMatches(value.target, old)) ||
+      file.pendingProvisions?.some(value => conflictsWithWorkspaceRestoreProvision(request, value)) ||
       file.reservations?.some(value => targetMatches(value.target, old)))
       throw new Error("Unknown live cleanup target remains protected.");
   }
@@ -3838,7 +3847,7 @@ export function createTelegramTopicTargetStore(
   };
   const assertRestoreRecoveryProtection = (
     path: string,
-    operations: readonly TelegramWorkspaceRestoreIntent[],
+    operations: readonly Pick<TelegramWorkspaceRestoreIntent, "request">[],
     provisions: readonly TelegramThreadPendingProvision[],
     requireKnownTargets = false,
     recoveryEvidence?: TelegramProvisionRecoveryFile,
@@ -5059,7 +5068,7 @@ export function createTelegramTopicTargetStore(
       assertWorkspaceRestoreBindingProtection(file);
       assertRestoreRecoveryProtection(
         path,
-        file.workspaceRestore!.operations,
+        provisioningProtectionIntents(file.workspaceRestore!),
         file.pendingProvisions ?? [],
       );
       observe({
@@ -5115,7 +5124,7 @@ export function createTelegramTopicTargetStore(
         assertWorkspaceRestoreBindingProtection(file);
         assertRestoreRecoveryProtection(
           path,
-          file.workspaceRestore!.operations,
+          provisioningProtectionIntents(file.workspaceRestore!),
           file.pendingProvisions ?? [],
         );
         const canonical = file.workspaceBindings ?? [],
@@ -5173,9 +5182,9 @@ export function createTelegramTopicTargetStore(
             (row) => currentRow(row) && targetMatches(row.target, old),
           ) ||
           reserved.some((value) => targetMatches(value.target, old)) ||
-          provisions.some(
-            (value) => !value.target || targetMatches(value.target, old),
-          ) ||
+          // Use the same binding/slot/owner/target conflicts as rebind admission. An unrelated unlocated
+          // create must not globally veto cleanup of this exact former binding (nor its issued marker).
+          provisions.some((value) => conflictsWithWorkspaceRestoreProvision(request, value)) ||
           cleanups.some((value) => targetMatches(value.target, old));
         if (
           protectedTarget(
@@ -5388,8 +5397,11 @@ export function createTelegramTopicTargetStore(
           file.reservations?.some((value) =>
             targetMatches(value.target, target),
           ) ||
+          // This exact created frame already proves a separately created routing tab (API ACK or authenticated
+          // implicit creation). An unlocated Workspace create is not its owner; keep that intent unresolved,
+          // but veto a concrete target collision. Generic unknown-target/Restore cleanup keeps its own guards.
           file.pendingProvisions?.some(
-            (value) => !value.target || targetMatches(value.target, target),
+            (value) => !!value.target && targetMatches(value.target, target),
           ) ||
           file.pendingCleanups?.some((value) =>
             targetMatches(value.target, target),
@@ -5555,7 +5567,7 @@ export function createTelegramTopicTargetStore(
                 parseTopicTargetFile(before.file).pendingProvisions ?? [];
               assertRestoreRecoveryProtection(
                 path,
-                before.state.operations,
+                provisioningProtectionIntents(before.state),
                 provisions,
               );
               const after = { ...before.file, workspaceRestore: next };
@@ -5571,7 +5583,7 @@ export function createTelegramTopicTargetStore(
                   return false;
                 assertRestoreRecoveryProtection(
                   path,
-                  [...before.state.operations, ...next.operations],
+                  [...provisioningProtectionIntents(before.state), ...provisioningProtectionIntents(next)],
                   provisions,
                 );
                 committedBefore = before;
@@ -5596,7 +5608,7 @@ export function createTelegramTopicTargetStore(
                     );
                   assertRestoreRecoveryProtection(
                     path,
-                    [...before.state.operations, ...next.operations],
+                    [...provisioningProtectionIntents(before.state), ...provisioningProtectionIntents(next)],
                     provisions,
                   );
                   if (!currentScope() || !isCurrent()) return;
@@ -6773,7 +6785,7 @@ export function createTelegramTopicTargetStore(
           conflictsWithWorkspaceRestoreProvision(request, provision),
         ) ||
         conflictsWithTemporaryThread(workspaceRestore, provision.target) ||
-        protectedLiveRebindOldTargets(workspaceRestore).some(old => !provision.target || targetMatches(old, provision.target))
+        protectedLiveRebindOldTargetIntents(workspaceRestore).some(({ request }) => conflictsWithWorkspaceRestoreProvision(request, provision))
       ) {
         throw new Error("Protected Workspace Restore provisioning conflict.");
       }
@@ -7634,11 +7646,35 @@ export function createTelegramTopicTargetStore(
             (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;
+        // A same-cwd session handoff keeps its predecessor's Thread slot; the Workspace commit re-keys that binding.
+        const handoffBindings =
+          binding ||
+          ownProvision ||
+          !options?.sessionHandoff ||
+          !previousInstanceId ||
+          !isSameTelegramProcessInstance(previousInstanceId, instanceId)
+            ? []
+            : Array.from(workspaceBindings.values()).filter(
+                (candidate) =>
+                  candidate.cwd === identity.cwd &&
+                  candidate.sessionId !== identity.sessionId &&
+                  Array.from(records.values()).some(
+                    (record) =>
+                      record.instanceId === previousInstanceId &&
+                      record.status === "active" &&
+                      targetMatches(record.target, candidate.target),
+                  ),
+              );
+        const handoffBinding =
+          handoffBindings.length === 1 ? handoffBindings[0] : undefined;
+        const retainedTarget = ownProvision?.target ?? binding?.target ?? handoffBinding?.target ?? legacyRecord?.target;
+        const retainedSlot = ownProvision?.slot ?? binding?.slot ?? handoffBinding?.slot ?? legacyRecord?.slot;
         const otherBindings = Array.from(workspaceBindings.values())
           .filter(
-            (other) => other.bindingKey !== identity.bindingKey && other.slot,
+            (other) =>
+              other.bindingKey !== identity.bindingKey &&
+              other.bindingKey !== handoffBinding?.bindingKey &&
+              other.slot,
           )
           .map((other) => ({
             bindingKey: other.bindingKey,

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.34.3",
+  "version": "0.35.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -47,7 +47,7 @@
     "@llblab/pi-codex-usage": "0.13.1",
     "@llblab/pi-grow-loop": "0.9.0",
     "@llblab/pi-state-flow": "0.26.4",
-    "@llblab/pi-telegram": "0.56.4",
+    "@llblab/pi-telegram": "0.57.1",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [