@llblab/pi-kit 0.36.1 → 0.36.3

package/node_modules/@llblab/pi-telegram/lib/thread-cleanup-manager.ts

@@ -22,7 +22,14 @@ import type {
   TelegramWorkspaceDeletionPermit,
   TelegramWorkspaceDestructiveFence,
   TelegramWorkspaceRetirementFence,
+  TelegramWorkspaceAdmissionLedger,
+  TelegramWorkspaceAdmissionOwner,
 } from "./workspace-admission.ts";
+import { isTelegramWorkspaceRetirementFence } from "./workspace-admission.ts";
+import type { TelegramTopicTargetStore, TelegramWorkspaceThreadBinding } from "./threads.ts";
+import type { TelegramWorkspaceOperationRunner } from "./workspace-retirement.ts";
+import type { TelegramWorkspaceThreadDeletionTransport } from "./telegram-api.ts";
+import type { TelegramProcessLiveness } from "./process-identity.ts";
 
 export interface TelegramThreadCleanupBindingSnapshot {
   cwd: string;
@@ -56,7 +63,8 @@ export interface TelegramThreadCleanupCandidate {
   sessionId?: string;
   sessionKey?: string;
   instanceSlot: string;
-  slot: string;
+  /** Null is explicit absence in reviewed work; it never denotes a reusable letter. */
+  slot: string | null;
   target: { chatId: number; threadId: number };
   inactiveSinceMs: number;
   bindingUpdatedAtMs: number;
@@ -116,8 +124,7 @@ export function planTelegramInactiveThreadCleanup(input: {
       !binding.cwd ||
       !binding.workspaceKey ||
       !binding.instanceSlot ||
-      typeof slot !== "string" ||
-      !slot ||
+      (slot !== undefined && (typeof slot !== "string" || !/^[A-Z]$/u.test(slot))) ||
       !validSessionIdentity(binding) ||
       !validTarget(binding.target) ||
       bindingKeys.has(binding.bindingKey) ||
@@ -152,8 +159,6 @@ export function planTelegramInactiveThreadCleanup(input: {
     const inactiveSinceMs = binding.inactiveSinceMs;
     const slot = binding.slot;
     if (
-      typeof slot !== "string" ||
-      !slot ||
       !Number.isSafeInteger(inactiveSinceMs) ||
       inactiveSinceMs === undefined ||
       inactiveSinceMs < 0 ||
@@ -180,7 +185,7 @@ export function planTelegramInactiveThreadCleanup(input: {
         ? { sessionId: binding.sessionId, sessionKey: binding.sessionKey }
         : {}),
       instanceSlot: binding.instanceSlot,
-      slot,
+      slot: slot ?? null,
       target: { ...binding.target },
       inactiveSinceMs,
       bindingUpdatedAtMs: binding.updatedAtMs,
@@ -409,8 +414,7 @@ function validateWorkSet(
       !validSessionIdentity(raw) ||
       typeof raw.instanceSlot !== "string" ||
       !raw.instanceSlot ||
-      typeof raw.slot !== "string" ||
-      !raw.slot ||
+      (raw.slot !== null && (typeof raw.slot !== "string" || !/^[A-Z]$/u.test(raw.slot))) ||
       !isObject(raw.target) ||
       !onlyKeys(raw.target, ["chatId", "threadId"]) ||
       !validTarget(
@@ -509,7 +513,11 @@ function sameCandidates(
   left: readonly TelegramThreadCleanupCandidate[],
   right: readonly TelegramThreadCleanupCandidate[],
 ): boolean {
-  return JSON.stringify(left) === JSON.stringify(right);
+  const keys = ["profileName", "bindingKey", "cwd", "workspaceKey", "sessionId", "sessionKey", "instanceSlot", "slot", "inactiveSinceMs", "bindingUpdatedAtMs"] as const;
+  return left.length === right.length && left.every((candidate, index) => {
+    const other = right[index]!;
+    return keys.every(key => candidate[key] === other[key]) && targetKey(candidate.target) === targetKey(other.target);
+  });
 }
 
 function parseTelegramThreadCleanupWorkFile(
@@ -544,6 +552,8 @@ export function createTelegramThreadCleanupWorkStore(options: {
   runtimeDir?: string;
   profileName: string;
   tokenSha256: string;
+  /** Exact captured ledger identity; standalone fixtures may use the plain profile identity. */
+  admissionProfileKey?: string;
   maxWorkSets?: number;
   maxBytes?: number;
   getNowMs?: () => number;
@@ -680,12 +690,12 @@ export function createTelegramThreadCleanupWorkStore(options: {
           !entry ||
           entry.bindingUpdatedAtMs !== input.bindingUpdatedAtMs ||
           permit.destructiveKind !== "manual-thread-cleanup" ||
-          permit.profileKey !== entry.profileName ||
+          permit.profileKey !== (options.admissionProfileKey ?? entry.profileName) ||
           permit.bindingKey !== entry.bindingKey ||
           permit.slot !== entry.slot ||
           targetKey(permit.target) !== targetKey(entry.target) ||
           !permit.operationId ||
-          !permit.retirementIntentId ||
+          permit.retirementIntentId !== workSet.operationId ||
           !safeTime(permit.issuedAtMs)
         )
           throw new Error(
@@ -842,12 +852,13 @@ export async function executeTelegramInactiveThreadCleanup(input: {
 
 export function createTelegramThreadCleanupPermitRuntime(deps: {
   ledger: {
+    getProfileKey(): string;
     read(): { fence?: TelegramWorkspaceDestructiveFence };
     acquireThreadCleanupFence(input: {
       operationId: string;
       cleanupWorkSetId: string;
       bindingKey: string;
-      slot: string;
+      slot: string | null;
       target: { chatId: number; threadId: number };
       leaderEpoch: number | string;
       cleanupRequestedAtMs: number;
@@ -930,7 +941,7 @@ export function createTelegramThreadCleanupPermitRuntime(deps: {
     const fence = deps.ledger.read().fence;
     return fence?.operationId === operationId &&
       fence.destructiveKind === "manual-thread-cleanup" &&
-      fence.profileKey === candidate.profileName &&
+      fence.profileKey === deps.ledger.getProfileKey() &&
       fence.retirementIntentId === workSetId &&
       fence.bindingKey === candidate.bindingKey &&
       fence.slot === candidate.slot &&
@@ -1045,8 +1056,17 @@ export function createTelegramThreadCleanupPermitRuntime(deps: {
         : { kind: "already-issued" };
     },
     async settleDeleted(fence, commit) {
+      const assertAuthority = () => {
+        const owner = deps.getOwner();
+        if (deps.getLeaderEpoch() !== fence.leaderEpoch ||
+            owner.processId !== fence.owner.processId || owner.processBirthId !== fence.owner.processBirthId)
+          throw new Error("Telegram Thread cleanup settlement authority changed.");
+      };
+      assertAuthority();
       const ready = deps.ledger.confirmThreadCleanupAbsence(fence);
-      if (!(await commit())) return "commit-pending";
+      const committed = await commit();
+      assertAuthority();
+      if (!committed) return "commit-pending";
       deps.ledger.completeThreadCleanupFence(ready);
       return "completed";
     },
@@ -1069,6 +1089,138 @@ export interface TelegramInactiveThreadCleanupCoordinatorDeps<TBinding> {
   ): Promise<boolean>;
 }
 
+export interface TelegramInactiveThreadCleanupAuthority {
+  profileName: string;
+  leaderEpoch: number | string;
+  ledger: TelegramWorkspaceAdmissionLedger;
+  isCurrent(): boolean;
+}
+
+/** Review owns ordinary admission; confirmed cleanup uses the shared gate and its exclusive manual fence instead. */
+export function createTelegramInactiveThreadCleanupRuntime(deps: {
+  store: Pick<TelegramTopicTargetStore, "load" | "listWorkspaceBindings" | "listReservations" | "listPendingProvisions" | "listPendingCleanups" | "commitInactiveWorkspaceCleanup">;
+  captureAuthority(): TelegramInactiveThreadCleanupAuthority | undefined;
+  getWorkStore(authority: TelegramInactiveThreadCleanupAuthority): TelegramThreadCleanupWorkStore;
+  getProtection(binding: TelegramWorkspaceThreadBinding): {
+    liveOwner: TelegramThreadCleanupProtectionState;
+    acceptedWork: TelegramThreadCleanupProtectionState;
+    deliveryAuthority: TelegramThreadCleanupProtectionState;
+  };
+  getProcessLiveness(owner: TelegramWorkspaceAdmissionOwner): TelegramProcessLiveness;
+  runExclusive<T>(operation: () => Promise<T>): Promise<T>;
+  runWorkspaceOperation: TelegramWorkspaceOperationRunner;
+  deleteThread: TelegramWorkspaceThreadDeletionTransport;
+  onError?: (error: unknown) => void;
+}): {
+  review(): Promise<{ count: number; operationId?: string }>;
+  clean(operationId: string): Promise<TelegramInactiveThreadCleanupResult>;
+} {
+  const capture = () => {
+    const authority = deps.captureAuthority();
+    if (!authority || !authority.isCurrent())
+      throw new Error("Inactive Thread cleanup requires current leader authority.");
+    const ledgerKey = authority.ledger.getProfileKey();
+    const owner = authority.ledger.getOwner();
+    const assertCurrent = () => {
+      if (!authority.isCurrent() || authority.ledger.getProfileKey() !== ledgerKey)
+        throw new Error("Inactive Thread cleanup authority changed.");
+    };
+    const evidence = () => {
+      assertCurrent();
+      return captureTelegramInactiveThreadCleanupEvidence({
+        profileName: authority.profileName,
+        listBindings: deps.store.listWorkspaceBindings,
+        getProtection: deps.getProtection,
+        listReservations: deps.store.listReservations,
+        listPendingProvisions: deps.store.listPendingProvisions,
+        listPendingCleanups: deps.store.listPendingCleanups,
+      });
+    };
+    return { authority, owner, assertCurrent, evidence };
+  };
+  return {
+    async review() {
+      const scope = capture();
+      return createTelegramInactiveThreadCleanupReviewRuntime({
+        getProfileName: () => scope.authority.profileName,
+        listBindings: deps.store.listWorkspaceBindings,
+        getProtection: deps.getProtection,
+        listReservations: deps.store.listReservations,
+        listPendingProvisions: deps.store.listPendingProvisions,
+        listPendingCleanups: deps.store.listPendingCleanups,
+        getWorkStore() { scope.assertCurrent(); return deps.getWorkStore(scope.authority); },
+        runWorkspaceOperation(metadata, operation) {
+          return deps.runWorkspaceOperation(metadata, async () => {
+            scope.assertCurrent();
+            await deps.store.load();
+            scope.assertCurrent();
+            return operation();
+          });
+        },
+      }).review();
+    },
+    async clean(operationId) {
+      const scope = capture();
+      return deps.runExclusive(async () => {
+        scope.assertCurrent();
+        const { authority } = scope;
+        const work = deps.getWorkStore(authority);
+        const exactBinding = (candidate: TelegramThreadCleanupCandidate) => {
+          const fresh = planTelegramInactiveThreadCleanup(scope.evidence()).find(binding => binding.bindingKey === candidate.bindingKey);
+          if (!fresh || !sameCandidates([fresh], [candidate])) return undefined;
+          return deps.store.listWorkspaceBindings().find(binding => binding.bindingKey === fresh.bindingKey);
+        };
+        const loadExactBinding = async (candidate: TelegramThreadCleanupCandidate) => {
+          scope.assertCurrent();
+          await deps.store.load();
+          scope.assertCurrent();
+          return exactBinding(candidate);
+        };
+        const permitRuntime = createTelegramThreadCleanupPermitRuntime({
+          ledger: authority.ledger,
+          getLeaderEpoch: () => authority.isCurrent() ? authority.leaderEpoch : undefined,
+          getProfileName: () => authority.profileName,
+          getOwner: () => scope.owner,
+          canAdoptFence: fence => authority.isCurrent() && deps.getProcessLiveness(fence.owner) === "dead",
+          revalidateUnderFence: async candidate => !!(await loadExactBinding(candidate)),
+        });
+        return cleanReviewedInactiveThreads({
+          store: work, operationId, permitRuntime,
+          resolveFullBinding: loadExactBinding,
+          async deleteWithPermit(permit, candidate) {
+            try {
+              await deps.deleteThread(() => {
+                scope.assertCurrent();
+                const fence = authority.ledger.read().fence;
+                if (!fence || !isTelegramWorkspaceRetirementFence(fence) ||
+                    fence.destructiveKind !== "manual-thread-cleanup" || fence.phase !== "deletion-issued" ||
+                    fence.operationId !== permit.operationId || fence.retirementIntentId !== operationId ||
+                    fence.profileKey !== permit.profileKey || fence.bindingKey !== candidate.bindingKey ||
+                    fence.slot !== candidate.slot || fence.deletionIssuedAtMs !== permit.issuedAtMs ||
+                    fence.leaderEpoch !== authority.leaderEpoch || fence.owner.processId !== scope.owner.processId ||
+                    fence.owner.processBirthId !== scope.owner.processBirthId ||
+                    targetKey(fence.target) !== targetKey(permit.target) || !exactBinding(candidate))
+                  throw new Error("Inactive Thread cleanup deletion permit is stale.");
+                return { ...permit.target };
+              });
+              scope.assertCurrent();
+            } catch (error) {
+              deps.onError?.(error);
+              throw error;
+            }
+          },
+          async commitBinding(candidate) {
+            scope.assertCurrent();
+            await deps.store.load();
+            scope.assertCurrent();
+            return deps.store.commitInactiveWorkspaceCleanup(candidate, authority.isCurrent);
+          },
+        });
+      });
+    },
+  };
+}
+
 export function createTelegramInactiveThreadCleanupSettingsPort<TBinding>(
   deps: TelegramInactiveThreadCleanupCoordinatorDeps<TBinding>,
 ): (operationId: string) => Promise<TelegramInactiveThreadCleanupResult> {
@@ -1105,9 +1257,13 @@ export async function cleanReviewedInactiveThreads<TBinding>(
         entry,
         input.operationId,
       );
-      if (ready)
-        await input.permitRuntime.settleDeleted(ready, async () => true);
-      deleted += 1;
+      if (ready) {
+        const settlement = await input.permitRuntime.settleDeleted(ready, async () => true);
+        if (settlement === "completed") deleted += 1;
+        else outcomeUnknown += 1;
+      } else if (input.permitRuntime.diagnoseRecovery(entry, input.operationId) !== "none") {
+        outcomeUnknown += 1;
+      } else deleted += 1;
       continue;
     }
     if (entry.state === "outcome-unknown") {

package/node_modules/@llblab/pi-telegram/lib/thread-display.ts

@@ -174,8 +174,12 @@ export function resolveTelegramWorkspaceDisplayNames(
       : undefined;
     if (manualName) {
       labels.set(binding.bindingKey, boundedLabel(manualName));
+    } else if (!slot) {
+      // A displaced binding retains its generated identity, not the letter now owned elsewhere.
+      const name = binding.threadName ? labelText(binding.threadName) : undefined;
+      if (name) labels.set(binding.bindingKey, boundedLabel(name));
     } else if (mode === "letters") {
-      if (slot) labels.set(binding.bindingKey, slot);
+      labels.set(binding.bindingKey, slot);
     } else if (mode === "names") {
       const name = binding.threadName ? labelText(binding.threadName) : slot;
       if (name) labels.set(binding.bindingKey, boundedLabel(name));
@@ -191,12 +195,11 @@ export function resolveTelegramWorkspaceDisplayNames(
             bindings.filter((candidate) => candidate.cwd === binding.cwd)
               .length > 1
           : (liveDirectoryCounts.get(binding.cwd) ?? 0) > 1;
-      if (showSuffix && !slot) continue;
       const suffix = !showSuffix
         ? ""
         : mode === "directory-title"
           ? ` ${slot}`
-          : `_${slot!.toLowerCase()}`;
+          : `_${slot.toLowerCase()}`;
       labels.set(binding.bindingKey, boundedLabel(base, suffix));
     }
   }
@@ -378,9 +381,9 @@ export function createTelegramThreadDisplaySettingsRuntime(deps: {
 /** Caller owns triggering and reporting; no timer or background retry is created. */
 export function createTelegramThreadDisplayReconciler(
   deps: TelegramThreadDisplayReconcilerDeps,
-): { reconcile(): Promise<{ changed: number }> } {
+): { reconcile(bindingKey?: string): Promise<{ changed: number }> } {
   let tail: Promise<unknown> = Promise.resolve();
-  const apply = async (): Promise<{ changed: number }> => {
+  const apply = async (bindingKey?: string): Promise<{ changed: number }> => {
     const epoch = deps.getLeaderEpoch();
     const profile = deps.getProfileKey();
     const mode = deps.getMode();
@@ -406,6 +409,7 @@ export function createTelegramThreadDisplayReconciler(
     );
     let changed = 0;
     for (const binding of bindings) {
+      if (bindingKey !== undefined && binding.bindingKey !== bindingKey) continue;
       const isBindingCurrent = deps.captureBindingAuthority(binding);
       if (!isBindingCurrent) continue;
       const title = titles.get(binding.bindingKey);
@@ -426,7 +430,7 @@ export function createTelegramThreadDisplayReconciler(
       };
       assertBinding(binding);
       if ((binding.displayTitle ?? binding.threadName) === title) continue;
-      await deps.callApi(
+      const acknowledged = await deps.callApi<boolean>(
         "editForumTopic",
         {
           chat_id: binding.target.chatId,
@@ -436,6 +440,8 @@ export function createTelegramThreadDisplayReconciler(
         { maxAttempts: 1 },
       );
       assertBinding(binding);
+      if (acknowledged !== true)
+        throw new Error("Telegram Thread display update was not acknowledged.");
       if (!deps.store.setWorkspaceDisplayTitle(binding, title)) {
         throw new Error(
           "Telegram Thread display binding changed before title commit.",
@@ -452,8 +458,8 @@ export function createTelegramThreadDisplayReconciler(
     return { changed };
   };
   return {
-    reconcile() {
-      const run = tail.then(apply);
+    reconcile(bindingKey) {
+      const run = tail.then(() => apply(bindingKey));
       tail = run.catch(() => undefined);
       return run;
     },

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

@@ -74,6 +74,7 @@ import {
 } from "./workspace-identity.ts";
 import {
   planTelegramWorkspaceSlotAllocation,
+  selectTelegramWorkspaceReusableSlot,
   TELEGRAM_WORKSPACE_SLOTS,
   TelegramWorkspaceSlotUnavailableError,
   type TelegramWorkspaceSlotOccupancy,
@@ -873,7 +874,7 @@ export interface TelegramTopicTargetStore {
           sessionId?: string;
           sessionKey?: string;
           instanceSlot: string;
-          slot: string;
+          slot: string | null;
           bindingKey: string;
           target: { chatId: number; threadId: number };
           inactiveSinceMs: number;
@@ -886,6 +887,19 @@ export interface TelegramTopicTargetStore {
     getExternalProtection: TelegramWorkspaceExternalProtectionCapture,
     options?: { expectedRetirement?: TelegramWorkspaceRetirementIntent },
   ) => TelegramWorkspaceSlotOccupancySnapshot;
+  /**
+   * Fallback for a full A-Z pool: strips the display letter from the least recently used
+   * binding (and its current Thread record) and persists, so a fresh allocation can take it.
+   * Metadata only: the Thread, journals and accepted work stay untouched, and a binding or
+   * letter held by a claim, reservation, provision, cleanup or retirement is never chosen.
+   */
+  reuseLeastRecentlyUsedWorkspaceSlot: (
+    isCurrent: () => boolean,
+  ) => Promise<
+    | { kind: "free" }
+    | { kind: "reused"; bindingKey: string; slot: string }
+    | undefined
+  >;
   hasWorkspaceBinding: (cwd: string, sessionId?: string) => boolean;
   setWorkspaceDisplayTitle: (
     expected: TelegramWorkspaceThreadBinding,
@@ -3556,8 +3570,6 @@ export function createTelegramTopicTargetStore(
     >,
     nowMs: number,
     options: {
-      /** Slot equality only counts when the binding itself holds a slot. */
-      requireBindingSlot?: boolean;
       isRetirementExcluded?: (
         intent: TelegramWorkspaceRetirementIntent,
         index: number,
@@ -3565,7 +3577,7 @@ export function createTelegramTopicTargetStore(
     } = {},
   ): boolean => {
     const slotMatches = (slot: string | undefined): boolean =>
-      (!options.requireBindingSlot || !!binding.slot) && slot === binding.slot;
+      !!binding.slot && slot === binding.slot;
     const targetOrSlotMatches = (candidate: {
       target?: TelegramTarget;
       slot?: string;
@@ -7272,7 +7284,7 @@ export function createTelegramTopicTargetStore(
         (!cleanupSnapshot.cwd ||
           !cleanupSnapshot.workspaceKey ||
           !cleanupSnapshot.instanceSlot ||
-          !cleanupSnapshot.slot ||
+          !(cleanupSnapshot.slot === null || (typeof cleanupSnapshot.slot === "string" && /^[A-Z]$/u.test(cleanupSnapshot.slot))) ||
           !cleanupSnapshot.bindingKey ||
           ((cleanupSnapshot.sessionId !== undefined ||
             cleanupSnapshot.sessionKey !== undefined) &&
@@ -7287,7 +7299,7 @@ export function createTelegramTopicTargetStore(
         return false;
       if (
         !cleanupSnapshot &&
-        (!normalized?.slot || normalized.inactiveSinceMs === undefined)
+        (!normalized || normalized.inactiveSinceMs === undefined)
       )
         return false;
       const mapKey = getWorkspaceBindingMapKey(
@@ -7301,7 +7313,7 @@ export function createTelegramTopicTargetStore(
           binding.sessionId === cleanupSessionId &&
           binding.sessionKey === cleanupSessionKey &&
           binding.instanceSlot === cleanupSnapshot.instanceSlot &&
-          binding.slot === cleanupSnapshot.slot &&
+          (binding.slot ?? null) === cleanupSnapshot.slot &&
           binding.bindingKey === cleanupSnapshot.bindingKey &&
           targetMatches(binding.target, cleanupSnapshot.target) &&
           binding.inactiveSinceMs === cleanupSnapshot.inactiveSinceMs &&
@@ -7420,13 +7432,13 @@ export function createTelegramTopicTargetStore(
       const nowMs = getNowMs();
       const inSnapshot =
         getExternalProtection.withSnapshot ?? ((capture) => capture());
-      const bindings = inSnapshot(() => Array.from(workspaceBindings.values()).map((binding) => {
-        const slot = binding.slot?.toLowerCase() ?? "";
+      // A slotless binding (legacy or reassigned) holds no letter, so it can neither block planning nor be retired for capacity.
+      const bindings = inSnapshot(() => Array.from(workspaceBindings.values()).filter((binding) => binding.slot).map((binding) => {
+        const slot = binding.slot!.toLowerCase();
         const locallyProtected = isWorkspaceBindingLocallyProtected(
           binding,
           nowMs,
           {
-            requireBindingSlot: true,
             isRetirementExcluded: (intent) =>
               isDeepStrictEqual(intent, options?.expectedRetirement),
           },
@@ -7491,6 +7503,150 @@ export function createTelegramTopicTargetStore(
         : [...localReservedSlots, "invalid"];
       return { bindings, reservedSlots };
     },
+    async reuseLeastRecentlyUsedWorkspaceSlot(isCurrent) {
+      if (workspaceRetirementCommitInFlight || !isCurrent()) return undefined;
+      const external = captureExternalReservedSlots();
+      if (!external) return undefined;
+      const nowMs = getNowMs();
+      const currentRecords = Array.from(records.values()).filter(
+        ThreadReconciler.isCurrentThreadRecord,
+      );
+      const held = new Set<string>(
+        [
+          ...external,
+          ...Array.from(workspaceClaims.values()).map(
+            (claim) => claim.identity.slot,
+          ),
+          ...reservations
+            .filter(
+              (reservation) =>
+                reservation.expiresAtMs === undefined ||
+                reservation.expiresAtMs > nowMs,
+            )
+            .map((reservation) => reservation.slot),
+          ...pendingProvisions
+            .filter((provision) =>
+              isPendingProvisionLiveOrTargeted(provision, nowMs),
+            )
+            .map((provision) => provision.slot),
+        ].filter((slot): slot is string => !!slot),
+      );
+      const occupied = new Set<string>([
+        ...held,
+        ...Array.from(workspaceBindings.values()).flatMap((binding) =>
+          binding.slot ? [binding.slot] : [],
+        ),
+        ...currentRecords.flatMap((record) => (record.slot ? [record.slot] : [])),
+      ]);
+      if (
+        Array.from(TELEGRAM_WORKSPACE_SLOTS, (slot) => slot.toUpperCase()).some(
+          (slot) => !occupied.has(slot),
+        )
+      )
+        return { kind: "free" };
+      const claimedKeys = new Set(
+        Array.from(workspaceClaims.values()).map(
+          (claim) => claim.identity.bindingKey,
+        ),
+      );
+      const candidates = Array.from(workspaceBindings.values()).flatMap(
+        (binding) => {
+          const slot = binding.slot;
+          if (
+            !slot ||
+            !/^[A-Z]$/u.test(slot) ||
+            held.has(slot) ||
+            claimedKeys.has(binding.bindingKey) ||
+            hasWorkspaceRetirementConflict({
+              bindingKey: binding.bindingKey,
+              target: binding.target,
+              slot,
+            }) ||
+            pendingCleanups.some((intent) =>
+              targetMatches(intent.target, binding.target),
+            ) ||
+            // Another Thread already holding the letter is unresolved duplication, not reusable metadata.
+            currentRecords.some(
+              (record) =>
+                record.slot === slot && !targetMatches(record.target, binding.target),
+            )
+          )
+            return [];
+          const live = currentRecords.some((record) =>
+            targetMatches(record.target, binding.target),
+          );
+          return [
+            {
+              bindingKey: binding.bindingKey,
+              slot,
+              live,
+              lastUsedMs:
+                !live && binding.inactiveSinceMs !== undefined
+                  ? binding.inactiveSinceMs
+                  : binding.updatedAtMs,
+            },
+          ];
+        },
+      );
+      const selected = selectTelegramWorkspaceReusableSlot(candidates);
+      if (!selected) return undefined;
+      const mapKey = Array.from(workspaceBindings.entries()).find(
+        ([, binding]) => binding.bindingKey === selected.bindingKey,
+      )?.[0];
+      const binding = mapKey ? workspaceBindings.get(mapKey) : undefined;
+      if (!mapKey || !binding) return undefined;
+      const affected = currentRecords.filter(
+        (record) =>
+          record.slot === selected.slot && targetMatches(record.target, binding.target),
+      );
+      const previousBinding = cloneWorkspaceBinding(binding);
+      const previousRecords = affected.map((record) => ({
+        key: getRecordOwnerKey(record),
+        record: cloneRecord(record),
+        identity: identities.get(getRecordOwnerKey(record)),
+      }));
+      const { slot: _slot, ...slotless } = previousBinding;
+      workspaceRetirementCommitInFlight = true;
+      workspaceBindings.set(mapKey, slotless);
+      for (const record of affected) {
+        delete record.slot;
+        const key = getRecordOwnerKey(record);
+        const identity = identities.get(key);
+        if (identity?.slot === selected.slot) {
+          const { slot: _identitySlot, ...rest } = identity;
+          identities.set(key, rest);
+        }
+      }
+      markDirty();
+      const restoreInMemory = () => {
+        workspaceBindings.set(mapKey, cloneWorkspaceBinding(previousBinding));
+        for (const previous of previousRecords) {
+          records.set(previous.key, cloneRecord(previous.record));
+          if (previous.identity) identities.set(previous.key, previous.identity);
+        }
+        markDirty();
+      };
+      try {
+        if (!isCurrent() || !(await persistSnapshot())) {
+          restoreInMemory();
+          return undefined;
+        }
+        return {
+          kind: "reused" as const,
+          bindingKey: selected.bindingKey,
+          slot: selected.slot,
+        };
+      } catch (error) {
+        try {
+          await loadFromDisk();
+        } catch {
+          restoreInMemory();
+        }
+        throw error;
+      } finally {
+        workspaceRetirementCommitInFlight = false;
+      }
+    },
     hasWorkspaceBinding(cwd, sessionId) {
       const normalizedCwd = normalizeTelegramWorkspacePath(cwd);
       const normalizedSessionId =

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

@@ -10657,12 +10657,13 @@ export function createTelegramUpdateAdmissionWorkerRuntime<
       const typedUpdate = update as TUpdate;
       const prepared = deps.prepareUpdateForExecution?.(typedUpdate) ?? typedUpdate;
       // Journal/source evidence remains the original; only the warm released handler projection changes destination.
-      const routed = target ? { ...prepared,
-        ...(prepared.message ? { message: prepared.message.message_thread_id === target.threadId ? { ...prepared.message }
-          : withoutTelegramTurnReplyAnchor({ ...prepared.message, message_thread_id: target.threadId, reply_to_message: undefined }) } : {}),
-        ...(prepared.edited_message ? { edited_message: prepared.edited_message.message_thread_id === target.threadId ? { ...prepared.edited_message }
-          : withoutTelegramTurnReplyAnchor({ ...prepared.edited_message, message_thread_id: target.threadId, reply_to_message: undefined }) } : {}),
-      } as TUpdate : prepared;
+      const projectTo = (destination: TelegramTarget & { threadId: number }): TUpdate => ({ ...prepared,
+        ...(prepared.message ? { message: prepared.message.message_thread_id === destination.threadId ? { ...prepared.message }
+          : withoutTelegramTurnReplyAnchor({ ...prepared.message, message_thread_id: destination.threadId, reply_to_message: undefined }) } : {}),
+        ...(prepared.edited_message ? { edited_message: prepared.edited_message.message_thread_id === destination.threadId ? { ...prepared.edited_message }
+          : withoutTelegramTurnReplyAnchor({ ...prepared.edited_message, message_thread_id: destination.threadId, reply_to_message: undefined }) } : {}),
+      } as TUpdate);
+      const routed = target ? projectTo(target) : prepared;
       try {
         return await executeUpdate(
           routed,
@@ -10673,6 +10674,8 @@ export function createTelegramUpdateAdmissionWorkerRuntime<
         if (await deps.settleTerminalExecutionFailure?.(error)) {
           return { kind: "complete" };
         }
+        // A refused reply proves only that send was not issued, not that the handler made no prior effects.
+        // Leave failure settlement to the worker's retry policy; never re-enter the handler to recover delivery here.
         throw error;
       }
     },