@llblab/pi-kit 0.33.0 → 0.34.0

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

@@ -18,6 +18,7 @@ import {
   isSameTelegramProcessInstance,
   isTelegramTopicTargetStaleError,
   provisionOwnBusTopic,
+  resetTelegramConnectionProvisioning,
   type TelegramOwnTopicProvisionResult,
   type TelegramTopicTargetStore,
   type TelegramWorkspaceDisplayBinding,
@@ -826,6 +827,15 @@ export async function ensureTelegramLeaderThreadBinding(
     ...(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;
@@ -836,6 +846,7 @@ export async function ensureTelegramLeaderThreadBinding(
         legacyLeaderRecord?.instanceId,
         {
           sessionId: deps.sessionId,
+          provisionProfileKey: leaderProfileKey,
           onCapacityUnavailable() {
             capacityUnavailable = true;
           },

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

@@ -783,6 +783,7 @@ export interface TelegramTopicTargetStore {
   ) => { slot?: string; threadName?: string } | undefined;
   listReservations: () => TelegramThreadReservation[];
   listPendingProvisions: () => TelegramThreadPendingProvision[];
+  resetPendingProvisionForConnect: (expected: TelegramThreadPendingProvision, isCurrent: () => boolean) => Promise<boolean>;
   listPendingCleanups: () => TelegramThreadCleanupIntent[];
   listSyncObservations: () => TelegramTopicSyncObservation[];
   reserveThread: (reservation: TelegramThreadReservation) => void;
@@ -902,6 +903,7 @@ export interface TelegramTopicTargetStore {
     options?: {
       existingBindingOnly?: boolean;
       sessionId?: string;
+      provisionProfileKey?: string;
       onCapacityUnavailable?: () => void;
     },
   ) => TelegramWorkspaceBindingIdentity | undefined;
@@ -4168,6 +4170,7 @@ export function createTelegramTopicTargetStore(
         }
     ),
     isCurrentPublication?: () => boolean,
+    resetProvisions?: readonly TelegramThreadPendingProvision[],
   ): Promise<boolean> => {
     const submittedPath = getPath(),
       submittedProfile = activeProfile();
@@ -4367,6 +4370,13 @@ export function createTelegramTopicTargetStore(
                   !!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.",
@@ -4429,7 +4439,7 @@ export function createTelegramTopicTargetStore(
             }
           : {}),
         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 } } : {}),
         })),
@@ -4636,6 +4646,7 @@ export function createTelegramTopicTargetStore(
         loadedProfile = submittedProfile;
         loaded = true;
         observedWorkspaceSemantic = getTelegramStateSemanticSnapshot(wire);
+        if (resetProvisions) { pendingProvisions = file.pendingProvisions; mutationRevision += 1; }
         if (transition) {
           records = new Map(
             file.threads.map((record) => {
@@ -4808,6 +4819,10 @@ export function createTelegramTopicTargetStore(
       if (isCurrentPublication?.() === false) return false;
       loadedPath = path;
       loaded = true;
+      if (resetProvisions) {
+        if (mutationRevision !== persistedRevision) return false;
+        pendingProvisions = file.pendingProvisions;
+      }
       if (mutationRevision === persistedRevision) dirty = false;
       return true;
     });
@@ -6814,6 +6829,11 @@ export function createTelegramTopicTargetStore(
       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(
@@ -7608,8 +7628,14 @@ export function createTelegramTopicTargetStore(
         ) {
           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,
@@ -7641,7 +7667,7 @@ export function createTelegramTopicTargetStore(
             )
             .map((reservation) => reservation.slot),
           ...pendingProvisions
-            .filter((provision) =>
+            .filter((provision) => provision !== ownProvision &&
               isPendingProvisionLiveOrTargeted(provision, nowMs),
             )
             .map((provision) => provision.slot),
@@ -9661,6 +9687,32 @@ export function createTelegramTopicTargetRenamer(
   };
 }
 
+/** Caller holds profile Workspace admission; only an explicit connect grants a fresh creation attempt. */
+export async 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> {
+  if (!input.isCurrent()) throw new Error("Telegram connection recovery authority changed.");
+  const removed: TelegramThreadPendingProvision[] = [];
+  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: TelegramTopicTargetProvisionerDeps,
 ): (
@@ -9923,7 +9975,7 @@ export function createTelegramTopicTargetProvisioner(
         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");

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

@@ -51,6 +51,13 @@ export function withoutTelegramTurnReplyAnchor<TMessage extends object>(message:
   return { ...message, [REPLY_ANCHOR_SUPPRESSED]: true };
 }
 
+/** A confirmed same-target copy may replace the former-tab suppression on a warm input projection. */
+export function withTelegramTurnReplyAnchor<TMessage extends { message_id: number }>(message: TMessage): TMessage {
+  if (!Number.isSafeInteger(message.message_id) || message.message_id <= 0)
+    throw new Error("Telegram reply anchor requires a positive message ID.");
+  return { ...message, [REPLY_ANCHOR_SUPPRESSED]: false };
+}
+
 export const TELEGRAM_GUEST_TURN_NOTE =
   "[guest] delivery: answer quickly with one concise, self-contained reply";
 

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

@@ -108,11 +108,10 @@ export type TelegramReactionType =
 
 export const TELEGRAM_PRIORITY_REACTIONS = [
   { id: 10, name: "like", emoji: "👍" },
-  { id: 11, name: "lightning", emoji: "⚡" },
   { id: 12, name: "heart", emoji: "❤" },
   { id: 13, name: "dove", emoji: "🕊" },
-  { id: 14, name: "fire", emoji: "🔥" },
 ] as const;
+export const TELEGRAM_STEER_REACTIONS = [{ id: 14, name: "fire", emoji: "🔥" }] as const;
 export const TELEGRAM_REMOVAL_REACTIONS = [
   { id: 20, name: "dislike", emoji: "👎" },
   { id: 21, name: "ghost", emoji: "👻" },
@@ -160,14 +159,10 @@ function getTelegramQueueReactionTransition(
 ): TelegramQueueReactionDisposition | undefined {
   const oldEmojis = collectTelegramReactionEmojis(oldReactions);
   const newEmojis = collectTelegramReactionEmojis(newReactions);
-  const oldPriorityEmoji = getTelegramReactionEmoji(
-    oldEmojis,
-    TELEGRAM_PRIORITY_REACTION_EMOJIS,
-  );
-  const newPriorityEmoji = getTelegramReactionEmoji(
-    newEmojis,
-    TELEGRAM_PRIORITY_REACTION_EMOJIS,
-  );
+  // Fire is effective Steer intent; weaker positive aliases under it do not reorder the lane.
+  const steerEmoji = TELEGRAM_STEER_REACTIONS[0].emoji;
+  const oldPriorityEmoji = oldEmojis.has(steerEmoji) ? steerEmoji : getTelegramReactionEmoji(oldEmojis, TELEGRAM_PRIORITY_REACTION_EMOJIS);
+  const newPriorityEmoji = newEmojis.has(steerEmoji) ? steerEmoji : getTelegramReactionEmoji(newEmojis, TELEGRAM_PRIORITY_REACTION_EMOJIS);
   const oldSuppressionEmoji = getTelegramReactionEmoji(
     oldEmojis,
     TELEGRAM_REMOVAL_REACTION_EMOJIS,
@@ -188,6 +183,7 @@ function getTelegramQueueReactionTransition(
   > = { kind: "reaction-transition" };
   if (oldPriorityEmoji !== newPriorityEmoji) {
     transition.priorityEmoji = newPriorityEmoji ?? null;
+    if (newPriorityEmoji === steerEmoji) transition.promptLane = "steer";
   }
   if (oldSuppressionEmoji !== newSuppressionEmoji) {
     transition.suppressionEmoji = newSuppressionEmoji ?? null;
@@ -374,6 +370,8 @@ export interface TelegramForeignOwnedUpdateForwarder<
     message: TMessage;
     ownership: TelegramTargetOwnershipView;
     ctx: TContext;
+    /** Local issuance/ACK fence; implementations must not serialize it into payloads. */
+    assertAuthority?: () => void;
   }) =>
     | Promise<TelegramBusForeignUpdateSettlement>
     | TelegramBusForeignUpdateSettlement;
@@ -549,6 +547,7 @@ interface TelegramUpdateAdmissionBinding {
   inspectSource?: () => TelegramDeferredSourceEvidence | undefined;
   inspectSourceSnapshot?: () => TelegramDeferredSourceSnapshot | undefined;
   inspectCompletion?: () => TelegramDeferredSourceEvidence | undefined;
+  subscribeCompletion?: (notify: () => void) => () => void;
   isSourceUnsettled?: () => boolean;
   prepareLiveInput?: (
     sourceUpdateIds: readonly number[],
@@ -617,6 +616,7 @@ export function bindTelegramUpdateAdmissionSource<
     | "inspectSource"
     | "inspectSourceSnapshot"
     | "inspectCompletion"
+    | "subscribeCompletion"
     | "isSourceUnsettled"
     | "acknowledgeTransferred"
     | "prepareLiveInput"
@@ -745,6 +745,15 @@ export function inspectTelegramDeferredSourceCompletion(
   return execution.isCurrent() && source ? { ...source } : undefined;
 }
 
+/** Warm ACK notification only; subscribers must independently recheck exact completion and recipient authority. */
+export function subscribeTelegramDeferredSourceCompletion(value: unknown, notify: () => void): (() => void) | undefined {
+  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: readonly unknown[],
@@ -8723,6 +8732,7 @@ function createTelegramUpdateSourceAdmissionHandle<
     let outcome: TelegramUpdateAdmissionOutcome | undefined;
     let completionAttempted = false;
     let completedSource: TelegramDeferredSourceCompletion | undefined;
+    const completionObservers = new Set<() => void>();
     const boundUpdate = bindTelegramUpdateExecutionFence(
       bindTelegramUpdateAdmissionSource(
         update,
@@ -8779,11 +8789,12 @@ function createTelegramUpdateSourceAdmissionHandle<
                 execution.isCurrent() &&
                 completion.isCurrent() &&
                 isDeepStrictEqual(completion.source, expectedSource)
-              )
-                completedSource = {
-                  ...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 {
@@ -8844,6 +8855,10 @@ function createTelegramUpdateSourceAdmissionHandle<
                   signal,
                 })
               : undefined,
+          subscribeCompletion: (notify) => {
+            completionObservers.add(notify);
+            return () => { completionObservers.delete(notify); };
+          },
           inspectCompletion: () =>
             execution.isCurrent() && completedSource?.isCurrent()
               ? { ...completedSource.source }
@@ -9320,6 +9335,7 @@ export function createTelegramQueueHandoffControlExecutionFactory<TContext>(
 
 export interface TelegramQueueHandoffCoordinatorInput<TContext> {
   item: TelegramQueueItem<TContext>;
+  steerSupported?: boolean;
   expectedOwner: TelegramUpdateJournalQueueOwner;
   recipientOwner: TelegramUpdateJournalQueueOwnerIdentity;
   handoffToken: string;
@@ -9375,6 +9391,7 @@ export async function coordinateTelegramQueueHandoff<TContext>(
   const handoff = createTelegramQueueHandoff({
     handoffToken: input.handoffToken,
     item: input.item,
+    steerSupported: input.steerSupported,
   });
   const receipt = handoff.payload.admissionReceipts[0];
   if (!receipt || handoff.payload.admissionReceipts.length !== 1) {
@@ -9551,6 +9568,8 @@ export function createTelegramQueueHandoffRecipientRuntime<TContext>(
 }
 
 export interface TelegramQueueHandoffReconcilerDeps<TContext> {
+  canHandoffSteerWithRecipient?: (recipient: TelegramBusFollowerView) => boolean;
+  hasPendingDispatch?: () => boolean;
   ownsDirect: () => boolean;
   isFollowerRegistered: () => boolean;
   isBusEnabled: () => boolean;
@@ -9589,6 +9608,8 @@ export interface TelegramQueueHandoffReconcilerDeps<TContext> {
 export interface TelegramQueueHandoffReconciliationRuntimeAssemblyDeps<
   TContext,
 > {
+  canHandoffSteerWithRecipient?: (recipient: TelegramBusFollowerView) => boolean;
+  hasPendingDispatch?: () => boolean;
   ownsDirect: () => boolean;
   isFollowerRegistered: () => boolean;
   isBusEnabled: () => boolean;
@@ -9628,6 +9649,8 @@ export function createTelegramQueueHandoffReconciliationRuntimeAssembly<
   deps: TelegramQueueHandoffReconciliationRuntimeAssemblyDeps<TContext>,
 ): (ctx: TContext) => Promise<void> {
   return createTelegramQueueHandoffReconciler({
+    canHandoffSteerWithRecipient: deps.canHandoffSteerWithRecipient,
+    hasPendingDispatch: deps.hasPendingDispatch,
     ownsDirect: deps.ownsDirect,
     isFollowerRegistered: deps.isFollowerRegistered,
     isBusEnabled: deps.isBusEnabled,
@@ -9704,6 +9727,8 @@ export function createTelegramQueueHandoffReconciler<TContext>(
       .filter((follower) => follower.instanceId !== deps.donorInstanceId);
     if (followers.length === 0) return;
     for (const item of [...deps.getQueuedItems()]) {
+      if ((deps.hasPendingDispatch?.() && deps.getQueuedItems()[0] === item) ||
+          (item.kind === "prompt" && (item.steerAttempted || item.steerPacketTail !== undefined || item.steerPacketSourceOrders !== undefined))) continue;
       const target = item.target;
       const recipient = target
         ? followers.find(
@@ -9713,6 +9738,8 @@ export function createTelegramQueueHandoffReconciler<TContext>(
           )
         : undefined;
       if (!recipient) continue;
+      const steerSupported = item.queueLane === "steer" && deps.canHandoffSteerWithRecipient?.(recipient) === true;
+      if (item.queueLane === "steer" && !steerSupported) continue;
       const receipt = item.admissionReceipts?.[0];
       if (!receipt || item.admissionReceipts?.length !== 1) continue;
       if (
@@ -9739,6 +9766,7 @@ export function createTelegramQueueHandoffReconciler<TContext>(
       const handoffToken = deps.createHandoffToken();
       const result = await coordinateTelegramQueueHandoff({
         item,
+        steerSupported,
         expectedOwner,
         recipientOwner: {
           instanceId: recipient.instanceId,
@@ -9749,6 +9777,9 @@ export function createTelegramQueueHandoffReconciler<TContext>(
         handoffToken,
         lifecycle,
         stageRemote: async ({ payload: sourcePayload }) => {
+          if (sourcePayload.queueLane === "steer" && deps.canHandoffSteerWithRecipient?.(recipient) !== true) {
+            throw new Error("Steer queue handoff capability changed before staging.");
+          }
           const payload = {
             ...sourcePayload,
             admissionReceipts: [

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -47,7 +47,7 @@
     "@llblab/pi-codex-usage": "0.13.0",
     "@llblab/pi-grow-loop": "0.9.0",
     "@llblab/pi-state-flow": "0.26.4",
-    "@llblab/pi-telegram": "0.55.0",
+    "@llblab/pi-telegram": "0.56.1",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [