@llblab/pi-kit 0.36.1 → 0.36.3

package/node_modules/@llblab/pi-telegram/lib/workspace-admission.ts

@@ -187,7 +187,8 @@ interface TelegramWorkspaceRetirementFenceBase {
   retirementIntentId: string;
   profileKey: string;
   bindingKey: string;
-  slot: string;
+  /** Null is admitted only for explicit manual cleanup of a slotless binding. */
+  slot: string | null;
   target: TelegramTarget & { threadId: number };
   leaderEpoch: number | string;
   retirementRequestedAtMs: number;
@@ -228,7 +229,7 @@ export interface TelegramWorkspaceDeletionPermit {
   readonly retirementIntentId: string;
   readonly profileKey: string;
   readonly bindingKey: string;
-  readonly slot: string;
+  readonly slot: string | null;
   readonly target: TelegramTarget & { threadId: number };
   readonly leaderEpoch: number | string;
   readonly issuedAtMs: number;
@@ -376,7 +377,7 @@ export interface TelegramWorkspaceAdmissionLedger {
     operationId: string;
     cleanupWorkSetId: string;
     bindingKey: string;
-    slot: string;
+    slot: string | null;
     target: TelegramTarget & { threadId: number };
     leaderEpoch: number | string;
     cleanupRequestedAtMs: number;
@@ -538,8 +539,8 @@ function normalizeFence(
     !isBoundedText(value.retirementIntentId) ||
     value.profileKey !== profileKey ||
     !isBoundedText(value.bindingKey) ||
-    typeof value.slot !== "string" ||
-    !/^[A-Z]$/u.test(value.slot) ||
+    !((typeof value.slot === "string" && /^[A-Z]$/u.test(value.slot)) ||
+      (value.destructiveKind === "manual-thread-cleanup" && value.slot === null)) ||
     !target ||
     !isLeaderEpoch(value.leaderEpoch) ||
     !isSafeTimestamp(value.retirementRequestedAtMs) ||
@@ -1869,7 +1870,7 @@ export function createTelegramWorkspaceAdmissionLedger(
       operationId: string;
       retirementIntentId: string;
       bindingKey: string;
-      slot: string;
+      slot: string | null;
       target: TelegramTarget & { threadId: number };
       leaderEpoch: number | string;
       retirementRequestedAtMs: number;
@@ -2307,7 +2308,7 @@ export function createTelegramWorkspaceAdmissionLedger(
     }),
     listReservedSlots: () => {
       const fence = read().fence;
-      return fence && isTelegramWorkspaceRetirementFence(fence)
+      return fence && isTelegramWorkspaceRetirementFence(fence) && fence.slot !== null
         ? [fence.slot]
         : [];
     },

package/node_modules/@llblab/pi-telegram/lib/workspace-retirement.ts

@@ -1764,6 +1764,8 @@ export async function runTelegramWorkspaceRetirementLifecycle(input: {
               owner,
               leaderEpoch: epoch,
             });
+      if (fence.slot === null)
+        return { kind: "retained", reason: "stale-intent" };
       input.admission.completeRetirementFence(fence);
       return {
         kind: "retired",
@@ -1892,6 +1894,7 @@ export function createTelegramWorkspaceSlotRotation(
       binding: TelegramWorkspaceThreadBinding,
     ) => TelegramWorkspaceExternalProtectionEvidence;
     recordEvent: (message: string, details: Record<string, unknown>) => void;
+    onSlotReused?: (bindingKey: string, isCurrent: () => boolean) => Promise<void>;
   },
 ): TelegramWorkspaceCapacityRunner {
   const requests = createTelegramWorkspaceOperationGate();
@@ -1906,7 +1909,7 @@ export function createTelegramWorkspaceSlotRotation(
     return requests.runExclusive(async () => {
       if (!isCurrent())
         throw new Error("Telegram Workspace allocation lost leader authority.");
-      const rotate = async () => {
+      const rotate = async (options?: { reuseWhenProtected?: boolean }) => {
         const result = await input.runExclusive(async () => {
           if (!isCurrent())
             throw new Error(
@@ -1959,6 +1962,57 @@ export function createTelegramWorkspaceSlotRotation(
             },
           });
         });
+        if (
+          options?.reuseWhenProtected &&
+          result.kind === "blocked" &&
+          result.stage === "preparation" &&
+          result.reason === "protected-capacity"
+        ) {
+          // Every letter is protected, so deleting a Thread is off the table: reassign the
+          // least recently used letter as metadata and keep its Thread, journals and work.
+          const reused = await input.runExclusive(async () => {
+            if (!isCurrent())
+              throw new Error(
+                "Telegram Workspace slot reuse lost leader authority.",
+              );
+            await input.store.load();
+            if (!isCurrent())
+              throw new Error(
+                "Telegram Workspace slot reuse lost leader authority.",
+              );
+            return input.store.reuseLeastRecentlyUsedWorkspaceSlot(isCurrent);
+          });
+          if (!isCurrent())
+            throw new Error("Telegram Workspace rotation lost leader authority.");
+          if (reused) {
+            if (reused.kind === "reused") {
+              // The store commit is final. Await display repair before the next allocation,
+              // but never roll back or repeat a published reuse after a transport failure.
+              try {
+                await input.onSlotReused?.(reused.bindingKey, isCurrent);
+              } catch (error) {
+                try {
+                  input.recordEvent("Telegram Workspace slot display update failed.", {
+                    slot: reused.slot,
+                    error: error instanceof Error ? error.message : String(error),
+                  });
+                } catch {
+                  /* A diagnostic failure grants no rollback or another display attempt. */
+                }
+              }
+              if (!isCurrent())
+                throw new Error("Telegram Workspace rotation lost leader authority.");
+              try {
+                input.recordEvent("Telegram Workspace slot reused.", {
+                  slot: reused.slot,
+                });
+              } catch {
+                /* Diagnostics cannot turn a published reassignment into another attempt. */
+              }
+            }
+            return { kind: "reused" as const };
+          }
+        }
         if (
           result.kind !== "retired" &&
           result.kind !== "not-needed" &&
@@ -2104,7 +2158,7 @@ export function createTelegramWorkspaceSlotRotation(
             }
           }
         }
-        await rotate();
+        await rotate({ reuseWhenProtected: true });
         return operation();
       }
     });

package/node_modules/@llblab/pi-telegram/lib/workspace-slots.ts

@@ -27,6 +27,50 @@ export type TelegramWorkspaceSlotAllocation =
   | { kind: "reclaim"; candidate: TelegramWorkspaceSlotOccupancy }
   | { kind: "blocked"; reason: "invalid-state" | "protected-capacity" };
 
+/** A binding whose letter may be reassigned without touching its Thread, journals or accepted work. */
+export interface TelegramWorkspaceReusableSlot {
+  bindingKey: string;
+  /** Uppercase display letter currently held by the binding. */
+  slot: string;
+  /** A live owner counts as most recently used, whatever its stored clocks say. */
+  live: boolean;
+  /** Last known use: inactivity start for detached bindings, otherwise the last binding update. */
+  lastUsedMs: number;
+}
+
+/**
+ * Metadata-only fallback for a full A-Z pool: pick the least recently used letter,
+ * preferring detached bindings over live ones. Unlike pressure retirement this
+ * ignores accepted-work protection because reuse deletes nothing.
+ * Returns undefined for an empty or malformed candidate set.
+ */
+export function selectTelegramWorkspaceReusableSlot(
+  candidates: readonly TelegramWorkspaceReusableSlot[],
+): TelegramWorkspaceReusableSlot | undefined {
+  const slots = new Set<string>();
+  const keys = new Set<string>();
+  for (const candidate of candidates) {
+    if (
+      !/^[A-Z]$/u.test(candidate.slot) ||
+      !candidate.bindingKey ||
+      !Number.isSafeInteger(candidate.lastUsedMs) ||
+      candidate.lastUsedMs < 0 ||
+      slots.has(candidate.slot) ||
+      keys.has(candidate.bindingKey)
+    )
+      return undefined;
+    slots.add(candidate.slot);
+    keys.add(candidate.bindingKey);
+  }
+  const [selected] = [...candidates].sort(
+    (left, right) =>
+      Number(left.live) - Number(right.live) ||
+      left.lastUsedMs - right.lastUsedMs ||
+      left.slot.localeCompare(right.slot),
+  );
+  return selected ? { ...selected } : undefined;
+}
+
 function isSlot(slot: string): boolean {
   return /^[a-z]$/u.test(slot);
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.57.3",
+  "version": "0.57.11",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -28,6 +28,7 @@
   },
   "scripts": {
     "test": "node --experimental-strip-types --import ./tests/fixtures/canonical-tmpdir.ts --test --test-concurrency=4 --test-reporter=dot tests/*.test.ts",
+    "test:low-concurrency": "node --experimental-strip-types --import ./tests/fixtures/canonical-tmpdir.ts --test --test-concurrency=2 --test-reporter=dot tests/*.test.ts",
     "test:verbose": "node --experimental-strip-types --import ./tests/fixtures/canonical-tmpdir.ts --test --test-reporter=spec tests/*.test.ts",
     "typecheck": "tsc --noEmit",
     "build": "node scripts/build-dist.mjs",

package/node_modules/@llblab/pi-telegram/scripts/run-macos-tests.mjs

@@ -0,0 +1,43 @@
+/**
+ * Deterministic macOS CI test shards
+ * Zones: CI, test execution
+ * Keeps real-process tests isolated and partitions the remaining files without changing test deadlines.
+ */
+import { spawnSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const [shard, phase, mode, ...extra] = process.argv.slice(2);
+if (!["0", "1"].includes(shard) || !["process", "remaining"].includes(phase) ||
+    (mode !== undefined && mode !== "--list") || extra.length) {
+  throw new Error("Usage: run-macos-tests.mjs <0|1> <process|remaining> [--list]");
+}
+const root = fileURLToPath(new URL("..", import.meta.url));
+const entries = readdirSync(join(root, "tests"), { withFileTypes: true })
+  .filter((entry) => entry.name.endsWith(".test.ts"));
+if (entries.some((entry) => !entry.isFile()))
+  throw new Error("The CI test inventory must contain only regular test files.");
+const names = entries.map((entry) => entry.name).sort();
+const processTest = "process-shutdown.test.ts";
+if (!names.includes(processTest)) throw new Error("The real-process test suite is missing.");
+const files = (phase === "process"
+  ? (shard === "0" ? [processTest] : [])
+  : names.filter((name) => name !== processTest).filter((_, index) => index % 2 === Number(shard)))
+  .map((name) => `tests/${name}`);
+if (mode === "--list") {
+  console.log(JSON.stringify(files));
+} else if (files.length) {
+  console.log(`macOS shard ${Number(shard) + 1}/2 ${phase}: ${files.length} test file(s)`);
+  const result = spawnSync(process.execPath, [
+    "--experimental-strip-types", "--import", "./tests/fixtures/canonical-tmpdir.ts",
+    "--test", "--test-concurrency=1", `--test-reporter=${phase === "process" ? "spec" : "dot"}`,
+    ...files,
+  ], {
+    cwd: root,
+    stdio: "inherit",
+    env: { ...process.env, PATH: [join(root, "node_modules", ".bin"), process.env.PATH].filter(Boolean).join(delimiter) },
+  });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.36.1",
+  "version": "0.36.3",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -45,12 +45,12 @@
   ],
   "dependencies": {
     "@llblab/pi-actors": "0.55.0",
-    "@llblab/pi-claude-usage": "0.2.2",
+    "@llblab/pi-claude-usage": "0.2.3",
     "@llblab/pi-clean-room": "0.3.0",
-    "@llblab/pi-codex-usage": "0.13.1",
+    "@llblab/pi-codex-usage": "0.13.2",
     "@llblab/pi-grow-loop": "0.9.0",
     "@llblab/pi-state-flow": "0.26.5",
-    "@llblab/pi-telegram": "0.57.3",
+    "@llblab/pi-telegram": "0.57.11",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [