@llblab/pi-kit 0.14.1 → 0.16.0

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

@@ -645,6 +645,50 @@ function normalizeWorkspaceBindingRecord(value) {
 function cloneWorkspaceBinding(binding) {
     return { ...binding, target: { ...binding.target } };
 }
+function cloneSessionReplacementIntent(intent) {
+    return { ...intent, target: { ...intent.target } };
+}
+function normalizeSessionReplacementIntent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const record = value;
+    const target = record.target;
+    if (typeof record.cwd !== "string" || !normalizeTelegramWorkspacePath(record.cwd) ||
+        typeof record.profileName !== "string" || !record.profileName ||
+        typeof record.sourceSessionId !== "string" || !normalizeTelegramSessionId(record.sourceSessionId) ||
+        typeof record.sourceUpdateId !== "number" || !Number.isSafeInteger(record.sourceUpdateId) ||
+        !target || typeof target.chatId !== "number" ||
+        (target.threadId !== undefined &&
+            (typeof target.threadId !== "number" || !Number.isSafeInteger(target.threadId))) ||
+        typeof record.messageId !== "number" || !Number.isSafeInteger(record.messageId) ||
+        typeof record.createdAtMs !== "number" || !Number.isSafeInteger(record.createdAtMs) ||
+        typeof record.expiresAtMs !== "number" || !Number.isSafeInteger(record.expiresAtMs) ||
+        record.expiresAtMs <= record.createdAtMs)
+        return undefined;
+    const continuity = record.continuity === "workspace-thread" ||
+        record.continuity === "classic-chat"
+        ? record.continuity
+        : target.threadId !== undefined ? "workspace-thread" : "classic-chat";
+    if ((continuity === "workspace-thread") !== (target.threadId !== undefined)) {
+        return undefined;
+    }
+    return {
+        continuity,
+        cwd: normalizeTelegramWorkspacePath(record.cwd),
+        profileName: record.profileName,
+        sourceSessionId: normalizeTelegramSessionId(record.sourceSessionId),
+        sourceUpdateId: record.sourceUpdateId,
+        target: {
+            chatId: target.chatId,
+            ...(typeof target.threadId === "number" ? { threadId: target.threadId } : {}),
+        },
+        messageId: record.messageId,
+        ...(typeof record.slot === "string" ? { slot: record.slot } : {}),
+        ...(typeof record.threadName === "string" ? { threadName: record.threadName } : {}),
+        createdAtMs: record.createdAtMs,
+        expiresAtMs: record.expiresAtMs,
+    };
+}
 function normalizeWorkspaceRetirementIntent(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return undefined;
@@ -905,6 +949,7 @@ function parseTopicTargetFile(value) {
                 return normalized ? [normalized] : [];
             })
             : [],
+        sessionReplacement: normalizeSessionReplacementIntent(file.sessionReplacement),
         reservations: Array.isArray(file.reservations)
             ? file.reservations.flatMap((reservation) => {
                 const normalized = normalizeReservation(reservation);
@@ -1026,6 +1071,7 @@ export function createTelegramTopicTargetStore(options) {
     let identities = new Map();
     let workspaceBindings = new Map();
     let workspaceRetirements = [];
+    let sessionReplacement;
     let workspaceRetirementCommitInFlight = false;
     const hasWorkspaceRetirementConflict = (input) => workspaceRetirements.some((intent) => (input.bindingKey !== undefined && intent.binding.bindingKey === input.bindingKey) ||
         (input.cwd !== undefined && intent.binding.cwd === input.cwd) ||
@@ -1150,6 +1196,7 @@ export function createTelegramTopicTargetStore(options) {
         identities = new Map();
         workspaceBindings = new Map();
         workspaceRetirements = [];
+        sessionReplacement = undefined;
         workspaceRetirementCommitInFlight = false;
         workspaceClaims = new Map();
         reservations = [];
@@ -1171,6 +1218,7 @@ export function createTelegramTopicTargetStore(options) {
             identities = new Map();
             workspaceBindings = new Map();
             workspaceRetirements = [];
+            sessionReplacement = undefined;
             workspaceRetirementCommitInFlight = false;
             reservations = [];
             pendingProvisions = [];
@@ -1208,6 +1256,9 @@ export function createTelegramTopicTargetStore(options) {
             cloneWorkspaceBinding(binding),
         ]));
         workspaceRetirements = (file.workspaceRetirements ?? []).map(cloneWorkspaceRetirementIntent);
+        sessionReplacement = file.sessionReplacement
+            ? cloneSessionReplacementIntent(file.sessionReplacement)
+            : undefined;
         reconcileWorkspaceSuffixExposure();
         for (const record of records.values())
             rememberIdentity(record);
@@ -1286,6 +1337,9 @@ export function createTelegramTopicTargetStore(options) {
                 identities: Array.from(identities.values()).map(cloneIdentityRecord),
                 workspaceBindings: Array.from(workspaceBindings.values()).map(cloneWorkspaceBinding),
                 workspaceRetirements: workspaceRetirements.map(cloneWorkspaceRetirementIntent),
+                ...(sessionReplacement
+                    ? { sessionReplacement: cloneSessionReplacementIntent(sessionReplacement) }
+                    : {}),
                 reservations: reservations.map((reservation) => ({ ...reservation })),
                 pendingProvisions: pendingProvisions.map((provision) => ({
                     ...provision,
@@ -1563,6 +1617,40 @@ export function createTelegramTopicTargetStore(options) {
         listWorkspaceBindings() {
             return Array.from(workspaceBindings.values()).map(cloneWorkspaceBinding);
         },
+        getWorkspaceBindingByTarget(target, sessionId) {
+            const binding = Array.from(workspaceBindings.values()).find((candidate) => targetMatches(candidate.target, target) &&
+                (sessionId === undefined || candidate.sessionId === sessionId));
+            return binding ? cloneWorkspaceBinding(binding) : undefined;
+        },
+        getSessionReplacementIntent() {
+            return sessionReplacement
+                ? cloneSessionReplacementIntent(sessionReplacement)
+                : undefined;
+        },
+        async commitSessionReplacementIntent(intent, isCurrent) {
+            const next = normalizeSessionReplacementIntent(intent);
+            if (!next || !isCurrent())
+                return false;
+            await loadFromDisk();
+            if (!isCurrent())
+                return false;
+            const existing = sessionReplacement;
+            if (existing && existing.expiresAtMs > getNowMs() &&
+                !isDeepStrictEqual(existing, next))
+                return false;
+            sessionReplacement = cloneSessionReplacementIntent(next);
+            markDirty();
+            return await persistSnapshot() && isCurrent();
+        },
+        async removeSessionReplacementIntent(expected, isCurrent) {
+            await loadFromDisk();
+            if (!isCurrent() || !sessionReplacement ||
+                !isDeepStrictEqual(sessionReplacement, expected))
+                return false;
+            sessionReplacement = undefined;
+            markDirty();
+            return await persistSnapshot() && isCurrent();
+        },
         listWorkspaceRetirementIntents() {
             return workspaceRetirements.map(cloneWorkspaceRetirementIntent);
         },
@@ -1959,6 +2047,36 @@ export function createTelegramTopicTargetStore(options) {
                 (options?.sessionId !== undefined && !normalizedSessionId) ||
                 hasWorkspaceRetirementConflict({ cwd: normalizedCwd }))
                 return undefined;
+            let replacementPreviousInstanceId;
+            const replacement = sessionReplacement;
+            if (replacement?.continuity === "workspace-thread" && normalizedSessionId &&
+                replacement.expiresAtMs > getNowMs() &&
+                replacement.profileName === (getTelegramProfile() ?? "default") &&
+                replacement.cwd === normalizedCwd &&
+                replacement.sourceSessionId !== normalizedSessionId) {
+                const sourceEntry = Array.from(workspaceBindings.entries()).find(([, binding]) => binding.cwd === normalizedCwd &&
+                    binding.sessionId === replacement.sourceSessionId &&
+                    targetMatches(binding.target, replacement.target));
+                if (sourceEntry) {
+                    const [sourceKey, sourceBinding] = sourceEntry;
+                    const replacementIdentity = Array.from({ length: TELEGRAM_WORKSPACE_SLOTS.length })
+                        .map((_, ordinal) => createTelegramWorkspaceBindingIdentityWithKey(sourceBinding.cwd, sourceBinding.workspaceKey, ordinal, normalizedSessionId))
+                        .find((identity) => identity?.instanceSlot === sourceBinding.instanceSlot);
+                    if (replacementIdentity &&
+                        replacementIdentity.instanceSlot === sourceBinding.instanceSlot) {
+                        const existingTargetRecord = Array.from(records.values()).find((record) => targetMatches(record.target, replacement.target));
+                        replacementPreviousInstanceId = existingTargetRecord?.instanceId;
+                        workspaceBindings.delete(sourceKey);
+                        workspaceBindings.set(getWorkspaceBindingMapKey(replacementIdentity), {
+                            ...sourceBinding,
+                            ...replacementIdentity,
+                            updatedAtMs: getNowMs(),
+                        });
+                        markDirty();
+                    }
+                }
+            }
+            const effectivePreviousInstanceId = previousInstanceId ?? replacementPreviousInstanceId;
             const externalReservedSlots = captureExternalReservedSlots();
             if (!externalReservedSlots) {
                 options?.onCapacityUnavailable?.();
@@ -1995,9 +2113,16 @@ export function createTelegramTopicTargetStore(options) {
                 const mapKey = getWorkspaceBindingMapKey(identity);
                 const existingClaim = workspaceClaims.get(mapKey);
                 if (existingClaim) {
-                    return existingClaim.instanceId === instanceId
-                        ? { ...existingClaim.identity }
-                        : undefined;
+                    if (existingClaim.instanceId === instanceId) {
+                        return { ...existingClaim.identity };
+                    }
+                    if (existingClaim.instanceId !== effectivePreviousInstanceId)
+                        return undefined;
+                    workspaceClaims.set(mapKey, {
+                        identity: existingClaim.identity,
+                        instanceId,
+                    });
+                    return { ...existingClaim.identity };
                 }
                 const binding = workspaceBindings.get(mapKey);
                 const liveRecord = binding
@@ -2005,7 +2130,7 @@ export function createTelegramTopicTargetStore(options) {
                     : undefined;
                 if (liveRecord &&
                     liveRecord.instanceId !== instanceId &&
-                    liveRecord.instanceId !== previousInstanceId) {
+                    liveRecord.instanceId !== effectivePreviousInstanceId) {
                     return undefined;
                 }
                 const retainedTarget = binding?.target ?? legacyRecord?.target;
@@ -2147,8 +2272,29 @@ export function createTelegramTopicTargetStore(options) {
             if (!next)
                 return undefined;
             const nextMapKey = getWorkspaceBindingMapKey(next);
-            const claim = workspaceClaims.get(nextMapKey);
-            if (next.slot && Array.from(workspaceBindings.values()).some((existing) => existing.bindingKey !== next.bindingKey && existing.slot === next.slot))
+            let claim = workspaceClaims.get(nextMapKey);
+            const replacedTargetBinding = Array.from(workspaceBindings.values()).find((existing) => existing.bindingKey !== next.bindingKey &&
+                targetMatches(existing.target, next.target));
+            if (claimInstanceId && claim?.instanceId === claimInstanceId &&
+                replacedTargetBinding?.slot) {
+                claim = {
+                    ...claim,
+                    identity: { ...claim.identity, slot: replacedTargetBinding.slot },
+                };
+                workspaceClaims.set(nextMapKey, claim);
+                next.slot = replacedTargetBinding.slot;
+                if (replacedTargetBinding.threadName && !next.threadName) {
+                    next.threadName = replacedTargetBinding.threadName;
+                }
+                if (replacedTargetBinding.manualThreadName && !next.manualThreadName) {
+                    next.manualThreadName = replacedTargetBinding.manualThreadName;
+                }
+                if (replacedTargetBinding.displayTitle && !next.displayTitle) {
+                    next.displayTitle = replacedTargetBinding.displayTitle;
+                }
+            }
+            if (next.slot && Array.from(workspaceBindings.values()).some((existing) => existing.bindingKey !== next.bindingKey && existing.slot === next.slot &&
+                !targetMatches(existing.target, next.target)))
                 return undefined;
             for (const existing of workspaceBindings.values()) {
                 if (existing.workspaceKey === next.workspaceKey &&

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

@@ -1216,6 +1216,7 @@ export interface TelegramUpdateWorkerOwnerRuntimeDeps<TContext> {
     isContextCurrent: (ctx: TContext) => boolean;
     dispatchNext: (ctx: TContext) => void;
     requestQueueHandoffReconciliation: (ctx: TContext) => void;
+    afterUpdateCompleted?: (updateId: number) => void;
 }
 export declare function createTelegramUpdateWorkerOwnerRuntime<TContext>(deps: TelegramUpdateWorkerOwnerRuntimeDeps<TContext>): TelegramUpdateWorkerOwnerRuntime<TContext>;
 export interface TelegramUpdateAdmissionRuntimeBinding<TContext> {

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

@@ -3177,9 +3177,11 @@ export function createTelegramUpdateWorkerOwnerRuntime(deps) {
             deps.dispatchNext(ctx);
             deps.requestQueueHandoffReconciliation(ctx);
         },
-        onUpdateCompleted(_updateId, ctx) {
-            if (deps.isContextCurrent(ctx))
-                deps.dispatchNext(ctx);
+        onUpdateCompleted(updateId, ctx) {
+            if (!deps.isContextCurrent(ctx))
+                return;
+            deps.dispatchNext(ctx);
+            deps.afterUpdateCompleted?.(updateId);
         },
     };
 }

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

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

package/node_modules/@llblab/pi-telegram/docs/architecture.md

@@ -42,7 +42,7 @@ Keep this boundary explicit:
 
 ### Instance, Session, And Context Cost
 
-A Telegram destination follows a Pi instance, not an immutable Pi session file. Ordinary Telegram prompts enter whichever session is active in that assigned instance when dispatch occurs. If the operator replaces or resumes a session locally, pi-telegram rebinds its session-scoped runtime state while preserving the instance's Telegram target where supported. Telegram currently exposes compaction for the active session, but not new-session, resume, fork, tree navigation, session switching, or full reload; those operations require safe public Pi extension APIs.
+A Telegram destination follows a Pi instance, not an immutable Pi session file. Ordinary Telegram prompts enter whichever session is active in that assigned instance when dispatch occurs. If the operator replaces or resumes a session locally, pi-telegram rebinds its session-scoped runtime state while preserving the instance's Telegram target where supported. Telegram exposes compaction and new-session replacement for the active session: `/new` first completes and removes its exact durable update, then dispatches an internal registered Pi command through `pi.sendUserMessage(..., { expandPromptTemplates: true })` so the handler runs with a real `ExtensionCommandContext` and calls the same `AgentSessionRuntime.newSession()` path as the terminal. Before invoking that path, the current transport owner CAS-publishes one expiring replacement intent inside the existing profile target snapshot. The intent discriminates `workspace-thread` from `classic-chat`. A same- or cross-process successor may consume either only for the exact profile, CWD, source session, target, and fresh lifetime: Threaded continuity re-keys the retained Workspace binding and preserves Thread, slot, and display identity, while Classic continuity preserves the exact chat target without creating a Workspace binding or entering topic lifecycle APIs. A confirmed callback is acknowledged and its dialog is deleted before session replacement begins. Once the successor has delivery authority, it atomically claims the intent by CAS-clearing it and then sends one separate terminal success result with bounded in-process transport retry. The old `withSession` path never publishes success, and an unclaimed intent never sends, preventing duplicate terminal notices across same-process startup and cleanup-ack ambiguity. Mismatch or expiry never authorizes binding takeover. Resume, fork, tree navigation, session switching, and full reload remain outside the stable Telegram API until Pi exposes safe public extension hooks for them.
 
 `/telegram-connect` never launches a hidden or headless Pi process. A long-lived background Pi process can own Telegram only when something else explicitly launched that process and it satisfies the normal lock/runtime rules. Pi `print` and `json` modes stay passive and exit rather than becoming hidden polling owners.
 
@@ -70,7 +70,7 @@ The repository uses a **Flat Domain DAG**:
 - `sync`: demand-driven Telegram reconciliation, mutable sync-slice state, nested provisioning activity, and local assumption policy. It does not own a complete Telegram bot read-model; Bot API lacks a complete topic/thread listing surface. It owns sync slices, invalidation triggers, config-persist invalidation sequencing, exact-target admitted stale-topic API recovery, observation intake, status/debug freshness, paired manual-disconnect/session-restart cleanup assembly, and reconciliation scheduling across bot identity, pairing assumptions, live target bindings, reservations, and transport health after meaningful observable signals. Production topic lifecycle and disconnect/restart cleanup enter profile-wide admission before the shared Workspace operation gate. Lifecycle admission spans observation-driven store settlement; cleanup admission spans intent publication, Telegram cleanup, binding mutation, durable settlement, and transport release. It should call narrower domain primitives rather than letting `index.ts`, `threads`, or `status` accumulate cross-cutting reconciliation policy.
 - `thread-reconciler`: Threaded Mode control-plane planning for Telegram thread/tab lifecycle. It owns the reconciliation state machine (`stable`, `provisioning`, `sync-required`, `cleanup-required`), pure plans, proof-before-delete rules, pending-provision protection, fresh-creation grace windows, leader-epoch checks, and the single policy authority for destructive thread cleanup actions. It excludes live Telegram API calls, inbound routing, menu rendering, and direct persistence.
 - `thread-cleanup-manager`: Disconnected proof-only admission planning for manual inactive-Workspace cleanup. It emits exact profile/binding/target snapshots only when durable inactivity exists, all live-owner/accepted-work/delivery evidence is `clear`, identities are unique, and no reservation, provision, or cleanup competes. Missing, malformed, duplicate, or `unknown` evidence returns no candidates; age and ordering never create authority. Its disconnected bounded profile/token-scoped work store atomically persists exact candidate snapshots, records one exact Workspace-issued deletion permit as outcome-unknown, rejects mismatched permits, and confirms deleted state idempotently; strict reads reject malformed/private-file ambiguity. A disconnected executor requires an injected exclusive Workspace deletion boundary across fresh planner evidence, exact retained-snapshot comparison, permit acquisition/recording, delete callback, and confirmation. The future fence owner must acquire and recheck in admission-ledger order; a retirement fence cannot be nested inside an active ordinary admission lease. Regressions prove drift stops before permit, unavailable/already-issued state cannot fabricate authority, and ambiguous delete remains outcome-unknown without replay. A production-shaped adapter preserves full Workspace records through external-protection resolution, then snapshots exact cleanup fields, reservations, provisions, and cleanup intents; protection exceptions become `unknown`, while source failures propagate fail-closed. Production Settings exposes **Review inactive tabs** only: profile-wide admission surrounds fresh evidence capture, one canonical 128-bit-digest work-set is retained, and a separate summary reports proven count, explicit no-deletion state, and Back navigation. The exact confirmation callback fits Telegram's 64-byte bound and accepts only canonical work-set IDs. **Clean inactive tabs** renders only when composition supplies a destructive port; production intentionally omits it, so malformed/stale callbacks fail closed and review remains non-destructive. Permit composition must not call `acquireRetirementFence()` because retirement remains pressure-only. The one admission-ledger fence now carries discriminated `pressure-retirement | manual-thread-cleanup` authority, treats legacy missing kind as pressure, exposes `acquireThreadCleanupFence()`, includes kind in exact comparison/permits, and remains profile-singleton. Cleanup-specific adopt/issue/absence/release/complete APIs preserve existing retirement callers and reject cross-kind use. Review admission releases before cleanup-fence acquisition; that fence then spans exact full-record/protection revalidation, sole permit issuance, work-set recording, one delete attempt, absence confirmation, binding/work-set commit, and fence completion. The v1-compatible schema and kind-specific acquire/adopt/issue/absence/release/complete methods are implemented; pressure methods reject manual fences and cleanup methods reject pressure fences. A disconnected permit runtime acquires the cleanup fence, revalidates under it, releases drifted unissued fences, refuses already-issued replay, and retains `commit-ready` until an injected durable commit succeeds. `threads.commitInactiveWorkspaceCleanup()` now removes only an exact full inactive binding after rechecking local records, claims, reservations, provisions, cleanups, and retirement intents; the retained cleanup candidate carries sufficient exact cwd/workspace/instance/global-slot/binding/target/inactivity/update commit identity, and under the retained fence exact absence closes commit-unknown retry without reconstructing the deleted full binding. Commit composition removes the binding before confirming the work-set, and failure retains `commit-ready`. A hidden coordinator validates canonical review identity, resolves the full binding, records the sole permit before one injected delete call, then commits binding, work-set, and fence. A `commit-ready` retry finishes without another delete; ambiguous deletion remains `deletion-issued` and is never replayed. A typed Settings-port adapter exposes this coordinator only when explicitly supplied and reports deleted, outcome-unknown, and blocked counts. Fake-port tests exercise the callback lifecycle and successor recovery: takeover requires injected proof, exact fence identity is preserved, live/unverifiable predecessors fail closed, and `commit-ready` resumes without deletion replay. Cross-process workers prove stale `prepared` contenders call fake transport once: deletion requires successful work-set permit CAS, and redundant fences over deleted entries settle without replay. Work-set pre-rename failure and lost post-rename acknowledgement retain recoverable fence truth; durable `deleted` completes that fence without another transport call. Binding-snapshot pre-rename ownership loss reloads and restores the exact binding, while post-rename acknowledgement loss reloads durable absence as successful commit. Cleanup runtime composition additionally requires candidate/work-set/runtime/fence profile equality before mutation and captures one stable successor owner snapshot for adoption. The optional Settings port reports only redacted exact-authority recovery classes: commit pending, deletion outcome unknown with no retry, or unavailable authority. It exposes no target, path, token, or transport details. Production still omits `cleanInactiveThreads`, so Bot API activation remains separate.
-- `thread-display`: Shared Letters/Names/Directories projection, initial-create title selection, and serialized leader-owned title application. Owns bounded path disambiguation, ambiguous-label rejection, and profile/mode/epoch plus captured live-binding fences. Acknowledged `displayTitle` remains distinct from stable `threadName`; the caller owns triggers and live-owner discovery. Leader provisioning applies the configured projection before creation; registration ACKs deliver the acknowledged title before initial follower status, and heartbeat ACKs carry later changes. Stable runtime names remain restoration identity rather than presentation. Current-thread/TUI display identity is separate from restoration identity. Live bot choosers, notices, prompt labels, and cross-instance agent-target resolution use acknowledged display titles while captured numeric targets and live registrations remain the routing authority. Settings routes direct-owner changes locally and follower changes through an authenticated capability-gated envelope. The leader serializes preference writes and application.
+- `thread-display`: Shared Letters/Names/Directories projection, Settings-mode/manual-override coordination, initial-create title selection, and serialized leader-owned title application. Owns bounded path disambiguation, ambiguous-label rejection, and profile/mode/epoch plus captured live-binding fences. Acknowledged `displayTitle` remains distinct from stable `threadName`; the caller owns triggers and live-owner discovery. Leader provisioning applies the configured projection before creation; registration ACKs deliver the acknowledged title before initial follower status, and heartbeat ACKs carry later changes. Stable runtime names remain restoration identity rather than presentation. Current-thread/TUI display identity is separate from restoration identity. Live bot choosers, notices, prompt labels, and cross-instance agent-target resolution use acknowledged display titles while captured numeric targets and live registrations remain the routing authority. Settings routes direct-owner changes locally and follower changes through an authenticated capability-gated envelope. The leader serializes preference writes and application.
 - `workspace-slots`: Pure bounded global-letter selection and pressure-reclamation proposals. It consumes explicit protection/inactivity evidence and never discovers owners, persists state, or performs deletion.
 - `workspace-admission`: Durable profile-scoped reader/writer ledger for cross-process exact-target, chat-wide, and profile-wide admission leases plus one destructive retirement fence. It owns atomic lease/fence transactions, proven-dead process-birth recovery, conservative malformed/ambiguous-state handling, exact successor adoption, retained-slot projection, and the durable `fenced` → `deletion-issued` → `commit-ready` phases that emit at most one deletion permit. Its runtime binding resolves `workspace-admission[.<profile>].json`, stores only the token SHA-256 profile authority, preserves separate named-profile identities across switching, permits changed-token rebind only when the prior ledger is provably empty, and fails closed while foreign leases or a fence remain. Issued fences cannot be released before confirmed absence and durable retirement commit; callers own journal/API/provisioning operations and retirement policy. Production composition supplies admission to journals, JSON/multipart API, leader/follower mutations, topic lifecycle, reroute restoration/reclamation, manual disconnect/session-restart cleanup, exact stale-target recovery, and Thread-store slot reservations; journal-evidence pruning also requires caller-supplied admission. Common async runners and the API adapter reject concurrent reuse of a live operation ID before a second caller can share or release its lease; once the first invocation exits, retry-stable recovery remains available. A 2/2 same-model independent post-fix quorum verified complete production-mutation composition at 0.96 confidence per reviewer. Destructive retirement remains disconnected by release scope; this verification does not authorize live deletion or replace disposable operator smoke.
 - `workspace-retirement`: Profile/leader-fenced pressure preparation over the store snapshot. It counts standalone reservations, selects one candidate only at full slot capacity, rechecks protection, and persists/resumes an exact durable intent. Workspace bindings accumulate their historical follower-journal routing keys and distinguish complete fresh metadata from incomplete legacy evidence. Its read-only accepted-work policy resolves those binding-specific journals plus the shared leader journal and combines them with local exact targets, failing closed when source coverage or target decoding is incomplete. It can prune a known empty follower-journal key only from complete readable evidence plus explicit writer quiescence under exact binding/profile/epoch fences and an exact-target admission lease held through durable publication. Incomplete legacy bindings consume discovered hashed journals as target-scoped evidence but remain incomplete so every later retirement repeats discovery. The shared Workspace operation runtime serializes topic lifecycle, reroute restoration/reclamation, provisioning, delayed post-provision reconciliation, follower/manual cleanup, rename, and display mutation through one exposed gate. Detached mutation work must reacquire fresh admission rather than inherit a lease already released by its caller. A successor may durably adopt one exact stale-epoch intent after profile/binding/protection revalidation; direct old-epoch execution remains blocked. The isolated executor consumes that gate and requires the durable admission ledger. It acquires or exactly adopts the matching fence, rechecks protection after admissions close, advances to `deletion-issued` before invoking an executor-only `deleteForumTopic` port with the sole permit, and never reissues from that phase. Success or exact absence advances to `commit-ready`; store commit failure retains the fence, and exact completion follows durable binding+intent removal. A successor resolves an issued unknown outcome only through a separate exact-absence probe. Leader composition exposes exact registry, active/queued work, known journals, and profile-exact legacy discovery as protection evidence. Missing queue targets and incomplete reads remain unknown. The common direct Bot API client counts exact JSON/multipart targets until settlement; message-scoped edits/deletes without a thread conservatively protect every binding in their chat. Known historical follower owner keys decode to process-birth identity before liveness checks. Durable intents block matching claims and binding mutations. Preparation/adoption/execution remains disconnected from leader runtime by release scope. Independent review cleared the admission-composition blocker; live deletion and operator acceptance remain separate gates.
@@ -596,7 +596,7 @@ The concrete runtime and wire reference remains in [Generative Apps Runtime For
 - Voice/STT/TTS providers: [Voice Integration](./voice.md).
 - Inbound/outbound command-template handlers: [Command Templates](./command-templates.md).
 
-Extension callbacks must avoid `pi-telegram` owned prefixes such as `compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, and `section:`. Workflow-specific Telegram slash commands should use the public command registry instead of becoming new core built-ins unless they are bridge lifecycle, transport ownership, queue safety, or essential operator controls.
+Extension callbacks must avoid `pi-telegram` owned prefixes such as `compact:`, `new:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, and `section:`. Workflow-specific Telegram slash commands should use the public command registry instead of becoming new core built-ins unless they are bridge lifecycle, transport ownership, queue safety, or essential operator controls.
 
 The bridge does not mirror arbitrary `ctx.ui.confirm/input/select/custom` prompts from other extensions into Telegram. Companion extensions that need Telegram operation should expose a Telegram-native command, section, settings row, callback, status line, inbound/update handler, or assistant action-markup path instead of relying on hidden TUI-only prompts.
 

package/node_modules/@llblab/pi-telegram/docs/callback-namespaces.md

@@ -20,7 +20,7 @@ myext:page:2
 
 - Use a stable extension-owned namespace, preferably the package or extension name without scope punctuation.
 - Keep the namespace lowercase ASCII: `a-z`, `0-9`, `_`, `-`.
-- Do not use `pi-telegram` owned prefixes: `compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, `section:`. Current app navigation uses `menu:`; `status:` remains reserved for legacy/owned status callbacks but is not emitted by current UI. `compact:` is owned by the manual compaction confirmation dialog. `section:` is owned by the Extension Sections platform (0.10.0+), documented in [Extension Sections](./sections.md). `settings:` is owned for the built-in Settings submenu.
+- Do not use `pi-telegram` owned prefixes: `compact:`, `new:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, `section:`. Current app navigation uses `menu:`; `status:` remains reserved for legacy/owned status callbacks but is not emitted by current UI. `compact:` and `new:` are owned by their destructive-action confirmation dialogs. `section:` is owned by the Extension Sections platform (0.10.0+), documented in [Extension Sections](./sections.md). `settings:` is owned for the built-in Settings submenu.
 - Keep the full `callback_data` within Telegram's 64-byte limit.
 - Put only opaque ids or small enum values in payloads; do not store secrets, full prompts, or large state.
 - Treat callbacks as untrusted input. Validate namespace, action, and payload before executing side effects.

package/node_modules/@llblab/pi-telegram/docs/public-api.md

@@ -51,6 +51,7 @@ Stable commands inside Pi:
 Stable commands inside the paired Telegram DM:
 
 - `/start` — pair when needed and open the main application menu.
+- `/new` — after idle and empty-queue checks, request a new Pi session in the current classic chat or Thread. The bridge acknowledges the callback, deletes its confirmation, completes and removes the exact durable update, then dispatches an internal Pi command through `pi.sendUserMessage(..., { expandPromptTemplates: true })`. Its real `ExtensionCommandContext` calls `ctx.newSession()`; one discriminated durable intent preserves either exact classic Profile/CWD/session/chat continuity or the Thread binding with slot/name re-key. The successor CAS-claims that intent before sending one terminal result. Busy, identity-mismatch, and unavailable-host paths fail closed.
 - `/compact` — open confirmation and compact when idle.
 - `/next` — abort active work first when needed, let the interrupted prompt receive its abort notice, then reply `Dispatching next queued turn.` to the exact queued prompt selected for the next model turn. The command itself is never the lifecycle-notice reply target, and aborted pending assistant text is suppressed.
 - `/continue` — enqueue a priority `continue` prompt.
@@ -59,7 +60,7 @@ Stable commands inside the paired Telegram DM:
 
 Hidden compatibility shortcuts may open sections directly: `/help`, `/status`, `/model`, `/thinking`, `/queue`, and `/settings`.
 
-This command surface is a mobile companion subset, not a raw terminal-command bridge or session browser. A Telegram destination follows its assigned Pi instance and sends prompts into that instance's currently active session; it is not permanently bound to one session identity. Compaction operates on the current session, while new-session, resume, fork, tree navigation, session switching, TUI transcript clearing, and arbitrary slash-command dispatch stay out of the stable Telegram API unless Pi exposes safe public extension hooks for them.
+This command surface is a mobile companion subset, not a raw terminal-command bridge or session browser. A Telegram destination follows its assigned Pi instance and sends prompts into that instance's currently active session; it is not permanently bound to one session identity. Compaction and new-session replacement operate on the current session; resume, fork, tree navigation, session switching, TUI transcript clearing, and arbitrary slash-command dispatch stay out of the stable Telegram API unless Pi exposes safe public extension hooks for them.
 
 ### Tools and assistant-authored actions
 
@@ -120,7 +121,7 @@ Bot/session identity always persists under `profiles.<name>`. The ordinary setup
 
 The file is global across Pi instances and contains configuration only. The per-profile polling/admission cursor is `acceptedThroughUpdateId` in that profile's private durable update journal; it is not a config key. On first connection after this cut, a legacy config cursor is transferred directly into the journal before polling and then removed from config. Journal publication failure preserves the legacy source; config publication failure leaves the journal authoritative so retry is idempotent. Cooperating instances serialize recursive config delta merges through `telegram.json.transaction` and preserve unrelated global/profile changes from newer disk snapshots. A semantically unchanged merge adopts the latest disk state in memory without replacing the file; later commits win when two deltas intentionally change the same leaf. Same-parent temp-file replacement retries bounded transient `EPERM`, `EACCES`, and `EBUSY` destination contention without deleting the live config or leaving transaction serialization. For manual edits, stop or idle the connected instances, publish a complete valid file atomically, and let them reload. A non-transactional editor racing Pi persistence has no same-leaf conflict guarantee.
 
-Threaded Mode Settings exposes **Thread display** as Letters (default), Names, `directory-snake`, or `directory-title`; retained `directories` is unsupported, resolves to Letters, and is never rewritten automatically. `profiles.<name>.threadDisplayMode` is profile-scoped; absent and invalid values resolve to `letters`. Settings previews the current binding set through the same projector used for fresh titles and reconciliation. Names projects the generated dictionary name for the slot; the two directory modes tokenize Unicode path segments deterministically and render snake case or humanized title case, with `_a` or ` A` slot suffixes when required. The leader serializes preference persistence and title reconciliation, while a follower sends an authenticated `follower.setThreadDisplayMode` request gated by `thread-display-mode-v1`, the additional `directory-display-format-v1` capability for either new directory mode, and its exact registration generation. Config writes check the originating authority inside the config transaction; mode changes preserve target IDs, slots, generated recovery names, manual overrides, and queue ownership. `/name` mutations carry their originating target through final binding validation. The caller confirms only after application succeeds. A partial failure may leave the preference saved and some titles updated; Settings reports that state and permits retry. Acknowledged follower titles arrive through heartbeat rather than a new read loop.
+Threaded Mode Settings exposes **Thread display** as Letters (default), Names, `directory-snake`, or `directory-title`; retained `directories` is unsupported, resolves to Letters, and is never rewritten automatically. `profiles.<name>.threadDisplayMode` is profile-scoped; absent and invalid values resolve to `letters`. Settings previews the current binding set through the same projector used for fresh titles and reconciliation. A manual `/name` override appears as `custom`; choosing any automatic Thread display option clears that override for the current Thread and immediately reapplies the selected projection. Names projects the generated dictionary name for the slot; the two directory modes tokenize Unicode path segments deterministically and render snake case or humanized title case, with `_a` or ` A` slot suffixes when required. The leader serializes preference persistence and title reconciliation, while a follower sends an authenticated `follower.setThreadDisplayMode` request gated by `thread-display-mode-v1`, the additional `directory-display-format-v1` capability for either new directory mode, and its exact registration generation. Config writes check the originating authority inside the config transaction; mode changes preserve target IDs, slots, generated recovery names, manual overrides, and queue ownership. `/name` mutations carry their originating target through final binding validation. The caller confirms only after application succeeds. A partial failure may leave the preference saved and some titles updated; Settings reports that state and permits retry. Acknowledged follower titles arrive through heartbeat rather than a new read loop.
 
 Hidden/default semantics are represented by absence:
 
@@ -577,7 +578,7 @@ async function synthesizeDemoOgg(_text: string): Promise<string> {
 
 ## Callback Namespaces
 
-Owned prefixes are reserved by `pi-telegram`: `compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, and `section:`.
+Owned prefixes are reserved by `pi-telegram`: `compact:`, `new:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, and `section:`.
 
 Companion extensions should use their own short prefix for raw callbacks or use `ctx.callbackData()` inside sections. Unknown unowned callbacks may be forwarded to Pi as `[callback] <data>` after built-in handlers decline them.
 

package/node_modules/@llblab/pi-telegram/docs/sections.md

@@ -197,7 +197,7 @@ The token is an implementation detail. Section authors **never** write `section:
 1. Telegram update arrives through the single `pi-telegram` polling loop
 2. Update handlers observe/consume (raw update interception)
 3. Button action store (`tgbtn:*`)
-4. Compact confirmation callbacks (`compact:*`)
+4. New-session and compact confirmation callbacks (`new:*`, `compact:*`)
 5. Queue menu callbacks (`queue:*`)
 6. Settings menu callbacks (`settings:*`)
 7. Section callbacks (`section:*`)
@@ -372,7 +372,7 @@ section:0:settings:open          → open settings root
 section:0:<action>:<payload>     → forwarded to handleCallback
 ```
 
-`section:` is listed in `TELEGRAM_OWNED_CALLBACK_PREFIXES` alongside `compact:`, `menu:`, `model:`, `settings:`, `status:`, `tgbtn:`, `thinking:`, `queue:`. Layered extensions must not use this prefix.
+`section:` is listed in `TELEGRAM_OWNED_CALLBACK_PREFIXES` alongside `compact:`, `new:`, `menu:`, `model:`, `settings:`, `status:`, `tgbtn:`, `thinking:`, `queue:`. Layered extensions must not use this prefix.
 
 ### Inline keyboard layout
 

package/node_modules/@llblab/pi-telegram/docs/ui-style.md

@@ -48,7 +48,7 @@ Use emoji as stable semantic markers, not decoration. Emoji carry transportable
 | `▶️` | Play / continue immediately | Idle `/next` result, `/continue` command, and matching menu action | Means work can start or resume directly without first aborting an active turn. |
 | `⏹️` | Abort current Pi work | `/abort` command description and active `/stop` result | Stops active work; accompanying copy states separately when queued work is cleared. |
 | `🟥` | Destructive stop command | `/stop` command description | Strong warning at the command/action entrypoint; standalone results use the more precise idle or abort state icon. |
-| `🆕` | New session / fresh start | Reserved visible extension command example for `/new`-like flows | Same-thread Telegram `/new` is currently blocked by Pi core API; keep this meaning reserved. |
+| `🆕` | New session / fresh start | `/new`, session replacement notices | `/new` replaces the active Pi session while preserving the current classic chat or Thread target; use it only for a real session reset. |
 | `🔄` | Refresh | Queue refresh row and future refresh buttons | Re-fetch/re-render current surface, not transport reconnect. |
 | `↪️` | Reroute to an existing target | Thread chooser buttons that send a captured command/message from one thread to another live thread | Curved arrow means the message arrived here but bends to another target. |
 | `🔁` | Replace/restore mode | Thread replace/restore chooser entrypoints | Opens a second step for moving a Pi instance binding to the current source thread. |
@@ -228,6 +228,7 @@ Rules:
 - Format standalone notices as one fully bold line: relevant emoji, one space, concise sentence, and terminal period. Menu or chooser headings use the same fully bold form but end in a colon when controls or detail follow. Empty-queue headings are the deliberate exception: fully bold, with no trailing period or colon.
 - Keep the emoji and complete sentence or heading inside the single bold span; do not bold only a fragment. A material name or phrase may receive nested italic emphasis without breaking the outer bold hierarchy—for example `<b>📡 Instance <i>Cedar</i> connected.</b>`.
 - Apply the same hierarchy to success, progress, empty, busy, unavailable, cancellation, and failure notices.
+- Once an action has settled, describe only the completed result in completed-state language. Do not append transitional copy such as “returning” or “starting”; use a separate progress surface only while work is genuinely still pending.
 - Callback alerts remain plain text because Telegram does not support rich text there, but still keep the relevant emoji and concise sentence.
 - Setting detail cards may include an emoji in the heading, then a colon and the current value in `<code>`.
 - Explain what the setting does and what the options mean only as much as needed.

package/node_modules/@llblab/pi-telegram/docs/updates.md

@@ -150,7 +150,7 @@ This means:
 
 - Extensions can claim callback namespaces that `pi-telegram` would otherwise forward as `[callback] <data>` text.
 - Extensions can observe updates by always returning `"pass"`.
-- Extensions must not consume updates that belong to `pi-telegram`'s own prefixes (`compact:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, `section:`) unless they are deliberately replacing that behavior.
+- Extensions must not consume updates that belong to `pi-telegram`'s own prefixes (`compact:`, `new:`, `tgbtn:`, `menu:`, `model:`, `thinking:`, `status:`, `queue:`, `settings:`, `section:`) unless they are deliberately replacing that behavior.
 
 ## Ownership semantics
 

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

@@ -804,7 +804,9 @@ export function createTelegramActivityPublicationRuntime(): TelegramActivityPubl
 
 export interface TelegramAssistantOutputRuntime {
   start: () => void;
+  beginTurn: () => void;
   accept: (event: TelegramAssistantSegmentEvent) => void;
+  hasAdmittedTelegramIntermediate: (text: string) => boolean;
   waitForIdle: () => Promise<void>;
   stop: () => void;
 }
@@ -834,6 +836,7 @@ export function createTelegramAssistantOutputRuntime<TAuthority = undefined>(dep
   let running = false;
   let tail: Promise<void> = Promise.resolve();
   const admitted = new Set<string>();
+  const admittedTelegramIntermediateText = new Set<string>();
   const isEligibleEvent = (event: TelegramAssistantSegmentEvent): boolean =>
     (event.source === "telegram" && event.placement === "intermediate") ||
     event.source === "local" ||
@@ -845,13 +848,20 @@ export function createTelegramAssistantOutputRuntime<TAuthority = undefined>(dep
       generation += 1;
       running = true;
       admitted.clear();
+      admittedTelegramIntermediateText.clear();
       tail = Promise.resolve();
     },
+    beginTurn() {
+      admittedTelegramIntermediateText.clear();
+    },
     accept(event) {
       if (!running || !isEligibleEvent(event) || !event.text.trim()) return;
       const key = `${event.activityId}:${event.sequence}`;
       if (admitted.has(key)) return;
       admitted.add(key);
+      if (event.source === "telegram" && event.placement === "intermediate") {
+        admittedTelegramIntermediateText.add(event.text.trim());
+      }
       const admittedGeneration = generation;
       const admittedAuthority = deps.captureAuthority?.();
       const preparation = deps.prepareSend?.(event);
@@ -877,6 +887,9 @@ export function createTelegramAssistantOutputRuntime<TAuthority = undefined>(dep
         }
       }).finally(() => preparation?.settle());
     },
+    hasAdmittedTelegramIntermediate(text) {
+      return admittedTelegramIntermediateText.has(text.trim());
+    },
     waitForIdle() {
       return tail;
     },
@@ -884,6 +897,7 @@ export function createTelegramAssistantOutputRuntime<TAuthority = undefined>(dep
       generation += 1;
       running = false;
       admitted.clear();
+      admittedTelegramIntermediateText.clear();
     },
   };
 }

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

@@ -835,7 +835,7 @@ interface TelegramLifecycleBindingDeps {
   activityVerbosityRuntime?: ActivityVerbosity.TelegramActivityVerbosityRuntime;
   assistantOutputRuntime: Pick<
     Activity.TelegramAssistantOutputRuntime,
-    "start" | "waitForIdle" | "stop"
+    "start" | "beginTurn" | "hasAdmittedTelegramIntermediate" | "waitForIdle" | "stop"
   >;
   sessionLifecycleRuntime: Pick<
     Lifecycle.TelegramLifecycleRegistrationDeps,
@@ -862,6 +862,7 @@ interface TelegramLifecycleBindingDeps {
   deferredQueueDispatchRuntime: Queue.TelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>;
   modelContextAvailabilityRuntime: Prompts.TelegramModelContextAvailabilityRuntime;
   disconnectOnQuit?: () => Promise<unknown>;
+  onSessionStarted?: (event: Pi.SessionStartEvent, ctx: Pi.ExtensionContext) => void;
   shutdownGenerativeAppLiveSurfaces?: () => void;
   resolveAutomaticThreadCleanupEnabled?: () => boolean | Promise<boolean>;
   buttonActionStore: OutboundHandlers.TelegramButtonActionStore;
@@ -952,6 +953,7 @@ export function registerTelegramLifecycleRuntimeHooks({
   deferredQueueDispatchRuntime,
   modelContextAvailabilityRuntime,
   disconnectOnQuit,
+  onSessionStarted,
   shutdownGenerativeAppLiveSurfaces,
   resolveAutomaticThreadCleanupEnabled,
   buttonActionStore,
@@ -1136,7 +1138,10 @@ export function registerTelegramLifecycleRuntimeHooks({
     clearDispatchPending: lifecycle.clearDispatchPending,
     setFoldQueuedPromptsIntoHistory: lifecycle.setFoldQueuedPromptsIntoHistory,
     setActiveTurn: activeTurnRuntime.set,
-    onPromptHandedOff,
+    onPromptHandedOff: (turn, ctx) => {
+      assistantOutputRuntime.beginTurn();
+      onPromptHandedOff?.(turn, ctx);
+    },
     createPreviewState: previewRuntime.resetState,
     startTypingLoop: (ctx) => {
       const turn = activeTurnRuntime.get();
@@ -1148,6 +1153,8 @@ export function registerTelegramLifecycleRuntimeHooks({
     getActiveTurn: activeTurnRuntime.get,
     loadConfig: configStore.load,
     extractAssistant: Replies.extractRunAssistantMessage,
+    isRecoveredAssistantAlreadyPublished: (assistant) =>
+      !!assistant.text && assistantOutputRuntime.hasAdmittedTelegramIntermediate(assistant.text),
     getFoldQueuedPromptsIntoHistory:
       lifecycle.shouldFoldQueuedPromptsIntoHistory,
     resetRuntimeState: agentEndResetter,
@@ -1273,6 +1280,7 @@ export function registerTelegramLifecycleRuntimeHooks({
       activityVerbosityRuntime?.reset();
       modelContextAvailabilityRuntime.reconcile();
       await sessionLifecycleRuntime.onSessionStart(event, ctx);
+      onSessionStarted?.(event, ctx);
     },
     async onSessionShutdown(event, ctx) {
       if (!isSessionContextActive(ctx)) return;