@llblab/pi-kit 0.36.1 → 0.36.3

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

@@ -505,6 +505,19 @@ export declare class TelegramApiStaleTargetError extends Error {
         threadId: number;
     });
 }
+/** A follower API refusal; legacy text alone does not prove the request was rejected before execution. */
+export declare class TelegramApiFollowerNotAllowedError extends Error {
+    readonly requestTarget: {
+        chatId: number;
+        threadId: number;
+    } | undefined;
+    /** Present only after a structured pre-execution refusal matches the requested API method. */
+    readonly rejectedRequestMethod: string | undefined;
+    constructor(message: string, requestTarget?: {
+        chatId: number;
+        threadId: number;
+    }, rejectedRequestMethod?: string);
+}
 export declare function getTelegramApiErrorRequestTarget(error: unknown): {
     chatId: number;
     threadId: number;

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

@@ -338,6 +338,18 @@ export class TelegramApiStaleTargetError extends Error {
         this.requestTarget = { ...requestTarget };
     }
 }
+/** A follower API refusal; legacy text alone does not prove the request was rejected before execution. */
+export class TelegramApiFollowerNotAllowedError extends Error {
+    requestTarget;
+    /** Present only after a structured pre-execution refusal matches the requested API method. */
+    rejectedRequestMethod;
+    constructor(message, requestTarget, rejectedRequestMethod) {
+        super(message);
+        this.name = "TelegramApiFollowerNotAllowedError";
+        this.requestTarget = requestTarget ? { ...requestTarget } : undefined;
+        this.rejectedRequestMethod = rejectedRequestMethod;
+    }
+}
 export function getTelegramApiErrorRequestTarget(error) {
     const target = error instanceof TelegramApiHttpError ||
         error instanceof TelegramApiStaleTargetError

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

@@ -3,7 +3,11 @@
  * Zones: telegram threads, workspace lifecycle
  * Owns fail-closed cleanup eligibility projection without persistence or Bot API effects
  */
-import type { TelegramWorkspaceDeletionPermit, TelegramWorkspaceDestructiveFence, TelegramWorkspaceRetirementFence } from "./workspace-admission.ts";
+import type { TelegramWorkspaceDeletionPermit, TelegramWorkspaceDestructiveFence, TelegramWorkspaceRetirementFence, TelegramWorkspaceAdmissionLedger, TelegramWorkspaceAdmissionOwner } 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;
     workspaceKey: string;
@@ -38,7 +42,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;
@@ -155,6 +160,8 @@ export declare 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;
@@ -185,6 +192,7 @@ export declare function executeTelegramInactiveThreadCleanup(input: {
 }>;
 export declare function createTelegramThreadCleanupPermitRuntime(deps: {
     ledger: {
+        getProfileKey(): string;
         read(): {
             fence?: TelegramWorkspaceDestructiveFence;
         };
@@ -192,7 +200,7 @@ export declare function createTelegramThreadCleanupPermitRuntime(deps: {
             operationId: string;
             cleanupWorkSetId: string;
             bindingKey: string;
-            slot: string;
+            slot: string | null;
             target: {
                 chatId: number;
                 threadId: number;
@@ -256,6 +264,34 @@ export interface TelegramInactiveThreadCleanupCoordinatorDeps<TBinding> {
     deleteWithPermit(permit: TelegramThreadCleanupDeletionPermit, candidate: TelegramThreadCleanupCandidate): Promise<void>;
     commitBinding(candidate: TelegramThreadCleanupCandidate, currentBinding?: 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 declare 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>;
+};
 export declare function createTelegramInactiveThreadCleanupSettingsPort<TBinding>(deps: TelegramInactiveThreadCleanupCoordinatorDeps<TBinding>): (operationId: string) => Promise<TelegramInactiveThreadCleanupResult>;
 export interface TelegramInactiveThreadCleanupResult {
     deleted: number;

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

@@ -7,6 +7,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { publishTelegramPrivateFile, readTelegramPrivateFile, TelegramPrivateFileError, withTelegramFileTransaction, } from "./locks.js";
 import { getTelegramJournalPublicationPaths } from "./paths.js";
 import { isWireRecord as isObject, hasOnlyWireKeys as onlyKeys, isNonNegativeWireInteger as safeTime, } from "./wire.js";
+import { isTelegramWorkspaceRetirementFence } from "./workspace-admission.js";
 function targetKey(target) {
     return `${target.chatId}:${target.threadId}`;
 }
@@ -42,8 +43,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) ||
@@ -72,9 +72,7 @@ export function planTelegramInactiveThreadCleanup(input) {
     for (const binding of input.bindings) {
         const inactiveSinceMs = binding.inactiveSinceMs;
         const slot = binding.slot;
-        if (typeof slot !== "string" ||
-            !slot ||
-            !Number.isSafeInteger(inactiveSinceMs) ||
+        if (!Number.isSafeInteger(inactiveSinceMs) ||
             inactiveSinceMs === undefined ||
             inactiveSinceMs < 0 ||
             !Number.isSafeInteger(binding.updatedAtMs) ||
@@ -97,7 +95,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,
@@ -228,8 +226,7 @@ function validateWorkSet(value, profileName) {
             !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(raw.target) ||
@@ -311,7 +308,11 @@ function validateWorkSet(value, profileName) {
     return { operationId: value.operationId, createdAtMs, entries };
 }
 function sameCandidates(left, right) {
-    return JSON.stringify(left) === JSON.stringify(right);
+    const keys = ["profileName", "bindingKey", "cwd", "workspaceKey", "sessionId", "sessionKey", "instanceSlot", "slot", "inactiveSinceMs", "bindingUpdatedAtMs"];
+    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(value, profileName, tokenSha256) {
     if (!isObject(value) ||
@@ -411,12 +412,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("Telegram Thread cleanup entry or deletion permit is stale or mismatched.");
                 if (entry.state !== "prepared") {
@@ -522,7 +523,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 &&
@@ -629,14 +630,132 @@ 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()))
+            const committed = await commit();
+            assertAuthority();
+            if (!committed)
                 return "commit-pending";
             deps.ledger.completeThreadCleanupFence(ready);
             return "completed";
         },
     };
 }
+/** Review owns ordinary admission; confirmed cleanup uses the shared gate and its exclusive manual fence instead. */
+export function createTelegramInactiveThreadCleanupRuntime(deps) {
+    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) => {
+                    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) => {
+                    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(deps) {
     return (operationId) => cleanReviewedInactiveThreads({ ...deps, operationId });
 }
@@ -654,9 +773,18 @@ export async function cleanReviewedInactiveThreads(input) {
     for (const entry of workSet.entries) {
         if (entry.state === "deleted") {
             const ready = input.permitRuntime.findCommitReady(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/dist/lib/thread-display.d.ts

@@ -62,7 +62,7 @@ export declare function createTelegramThreadDisplaySettingsRuntime(deps: {
 };
 /** Caller owns triggering and reporting; no timer or background retry is created. */
 export declare function createTelegramThreadDisplayReconciler(deps: TelegramThreadDisplayReconcilerDeps): {
-    reconcile(): Promise<{
+    reconcile(bindingKey?: string): Promise<{
         changed: number;
     }>;
 };

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

@@ -123,9 +123,14 @@ export function resolveTelegramWorkspaceDisplayNames(bindings, mode, liveBinding
         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;
@@ -142,8 +147,6 @@ export function resolveTelegramWorkspaceDisplayNames(bindings, mode, liveBinding
                     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"
@@ -239,7 +242,7 @@ export function createTelegramThreadDisplaySettingsRuntime(deps) {
 /** Caller owns triggering and reporting; no timer or background retry is created. */
 export function createTelegramThreadDisplayReconciler(deps) {
     let tail = Promise.resolve();
-    const apply = async () => {
+    const apply = async (bindingKey) => {
         const epoch = deps.getLeaderEpoch();
         const profile = deps.getProfileKey();
         const mode = deps.getMode();
@@ -257,6 +260,8 @@ export function createTelegramThreadDisplayReconciler(deps) {
         const titles = resolveTelegramWorkspaceDisplayNames(bindings, mode, liveBindingKeys);
         let changed = 0;
         for (const binding of bindings) {
+            if (bindingKey !== undefined && binding.bindingKey !== bindingKey)
+                continue;
             const isBindingCurrent = deps.captureBindingAuthority(binding);
             if (!isBindingCurrent)
                 continue;
@@ -275,12 +280,14 @@ export function createTelegramThreadDisplayReconciler(deps) {
             assertBinding(binding);
             if ((binding.displayTitle ?? binding.threadName) === title)
                 continue;
-            await deps.callApi("editForumTopic", {
+            const acknowledged = await deps.callApi("editForumTopic", {
                 chat_id: binding.target.chatId,
                 message_thread_id: binding.target.threadId,
                 name: title,
             }, { 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.");
             }
@@ -296,8 +303,8 @@ export function createTelegramThreadDisplayReconciler(deps) {
         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/dist/lib/threads.d.ts

@@ -543,7 +543,7 @@ export interface TelegramTopicTargetStore {
         sessionId?: string;
         sessionKey?: string;
         instanceSlot: string;
-        slot: string;
+        slot: string | null;
         bindingKey: string;
         target: {
             chatId: number;
@@ -556,6 +556,19 @@ export interface TelegramTopicTargetStore {
     captureWorkspaceSlotOccupancy: (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, title: string) => boolean;
     markWorkspaceBindingInactiveByTarget: (target: TelegramTarget, inactiveSinceMs?: number) => boolean;

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

@@ -17,7 +17,7 @@ import { resolveTelegramProfileTempFilePath } from "./paths.js";
 import { createTelegramRuntimeProjectionStore } from "./status.js";
 import * as ThreadReconciler from "./thread-reconciler.js";
 import { createTelegramSessionKey, createTelegramWorkspaceBindingIdentityWithKey, createTelegramWorkspaceDirectoryKey, normalizeTelegramSessionId, normalizeTelegramWorkspacePath, TELEGRAM_WORKSPACE_KEY_MAX_LENGTH, } from "./workspace-identity.js";
-import { planTelegramWorkspaceSlotAllocation, TELEGRAM_WORKSPACE_SLOTS, TelegramWorkspaceSlotUnavailableError, } from "./workspace-slots.js";
+import { planTelegramWorkspaceSlotAllocation, selectTelegramWorkspaceReusableSlot, TELEGRAM_WORKSPACE_SLOTS, TelegramWorkspaceSlotUnavailableError, } from "./workspace-slots.js";
 export { createTelegramWorkspaceBindingIdentity, createTelegramWorkspaceDirectoryKey, normalizeTelegramSessionId, normalizeTelegramWorkspacePath, } from "./workspace-identity.js";
 const TELEGRAM_THREAD_RESERVATION_TTL_MS = 15 * 60 * 1000;
 function getNextMonotonicSlot(records, reservations, pendingProvisions, nowMs, lastSlot) {
@@ -1871,7 +1871,7 @@ export function createTelegramTopicTargetStore(options) {
     };
     /** Current records, claims, reservations, provisions, cleanups or other retirements still holding a binding's Thread or slot. */
     const isWorkspaceBindingLocallyProtected = (binding, nowMs, options = {}) => {
-        const slotMatches = (slot) => (!options.requireBindingSlot || !!binding.slot) && slot === binding.slot;
+        const slotMatches = (slot) => !!binding.slot && slot === binding.slot;
         const targetOrSlotMatches = (candidate) => (!!candidate.target && targetMatches(candidate.target, binding.target)) ||
             slotMatches(candidate.slot);
         return (Array.from(records.values()).some((record) => ThreadReconciler.isCurrentThreadRecord(record) &&
@@ -4572,7 +4572,7 @@ export function createTelegramTopicTargetStore(options) {
                 (!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) &&
@@ -4585,7 +4585,7 @@ export function createTelegramTopicTargetStore(options) {
                     cleanupSnapshot.target.threadId <= 0))
                 return false;
             if (!cleanupSnapshot &&
-                (!normalized?.slot || normalized.inactiveSinceMs === undefined))
+                (!normalized || normalized.inactiveSinceMs === undefined))
                 return false;
             const mapKey = getWorkspaceBindingMapKey((cleanupSnapshot ?? normalized));
             const binding = workspaceBindings.get(mapKey);
@@ -4597,7 +4597,7 @@ export function createTelegramTopicTargetStore(options) {
                     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 &&
@@ -4710,10 +4710,10 @@ export function createTelegramTopicTargetStore(options) {
         captureWorkspaceSlotOccupancy(getExternalProtection, options) {
             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),
                 });
                 const externalProtection = getExternalProtection(cloneWorkspaceBinding(binding));
@@ -4765,6 +4765,120 @@ export function createTelegramTopicTargetStore(options) {
                 : [...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([
+                ...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));
+            const occupied = new Set([
+                ...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",
+                    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 = sessionId === undefined