@llblab/pi-telegram 0.52.1 → 0.52.2

package/AGENTS.md

@@ -84,7 +84,7 @@ Use the relevant local skill before non-trivial work in its domain. Keep skill o
 
 - Admission is journal-first: validate and persist the complete `getUpdates` response before one monotonic offset commit, then signal an independent worker without awaiting semantic execution. Missing cursor with a non-empty journal, malformed/foreign authority, or capacity exhaustion fails closed. “Durable” means process-crash recovery after atomic rename, not unflushed host/kernel/filesystem/device/power-loss survival.
 - Storage cutovers must reconcile actual consumer locations before correcting path adapters. Never normalize a relative historical reference into new authority or treat equal reference strings / empty canonical storage as source completeness. Exact-path preflight is lexical only; physical identity, historical coverage, writer closure and migration remain separate proofs.
-- Workspace mutations acquire cross-process admission before their shared process-local gate and hold it through asynchronous API work and durable settlement. Topic lifecycle, complete unbound/reroute target handling, manual disconnect, and session-restart cleanup use profile-wide scope; either retained retirement-fence phase rejects them before state access. Cleanup scope spans intent publication, target mutation, persistence, and transport release. Detached reconciliation that mutates Thread state must reacquire fresh profile admission through the same gate; it cannot inherit a caller lease that ended before its timer runs. A live operation ID has one process-local caller: concurrent reuse is rejected before lease acquisition, while retry after the caller exits may resume exact durable authority.
+- Workspace mutations acquire cross-process admission before their shared process-local gate and hold it through asynchronous API work and durable settlement. Topic lifecycle, complete unbound/reroute target handling, manual disconnect, and session-restart cleanup use profile-wide scope; either retained retirement-fence phase rejects them before state access. Cleanup admission spans intent publication, target mutation, persistence, and successful transport release. Explicit manual disconnect may stop only its captured local transport after cleanup admission/effects fail; it must not bypass Thread mutation fences, release a replacement connection, claim unconfirmed deletion, or retry an uncertain stop. Session-restart cleanup retains its admission-required behavior. Detached reconciliation that mutates Thread state must reacquire fresh profile admission through the same gate; it cannot inherit a caller lease that ended before its timer runs. A live operation ID has one process-local caller: concurrent reuse is rejected before lease acquisition, while retry after the caller exits may resume exact durable authority.
 - Workspace retirement is capacity-pressure-only. Elapsed time and heartbeat silence never trigger deletion; only complete `A`–`Z` exhaustion may propose the oldest continuously proven inactive, fully unprotected binding. Exact deletion, durable retirement, and fence completion precede slot reuse. Authorized demand-driven rotation retries one failed fresh allocation after retirement; restore-only follower startup never evicts. Release ordinary registration/provisioning leases before acquiring the destructive fence, retain the shared mutation gate across retirement, and validate the exact permit immediately before one non-retried deletion. Persist an exact method/target-matched rejection before withdrawing its intent; release that fence only after durable withdrawal, retaining the binding. A later attempt requires fresh operation authority. Protection reads must never repair, quarantine, or reset journals. Non-destructive owner detachment must atomically retain one exact Workspace binding and its letter while removing only its uniquely matched owner record and stamping first inactivity; it never manufactures Thread-deletion evidence or clears accepted work. During authenticated follower registration, the exact Workspace claim owns the letter: a mismatched retained target record is repaired to that claim before binding commit, while any unrelated binding that owns the stale letter remains untouched. Retained prune observations are bounded, non-routing and registration/profile/epoch/runtime-fenced. One unfinished preservation operation retains its admission identity across fresh-PID-proof retries; it can never become deletion authority. Leader quit requires completed delivery/polling/worker teardown under the captured session generation, profile and epoch; reload/new/resume/fork never establish inactivity. Unknown deletion outcomes retain their fence; only confirmed durable completion permits reuse.
 - Foreign forwarding settles as `accepted`, `retryable`, or `terminal-rejected`. Only an authenticated acknowledgement carrying the expected `deliveryId` and `sourceUpdateId` releases leader journal authority. Negative, missing, stale, mismatched, or capacity-failed settlement remains durable; callback error answers are side effects only. Exception: the operator-approved fixed chooser deadline may discard its exact unclaimed donor pending source without a body archive or delivery-success claim. Accepted recipient queue/work and bound Threads are untouched; old donor controls and late reports cannot replay it. The lifetime and temporary cleanup contract lives in `docs/architecture.md`.
 - A forwarding delivery id is stable across registration replacement and derives from envelope kind, source `update_id`, and stable recipient binding. Runtime instance and registration generation remain separate attempt fences. Persisted message ownership carries the stable binding so replay can rebind only to its current authenticated registration.

package/BACKLOG.md

@@ -2,10 +2,12 @@
 
 _This file owns unresolved project work only. Completed behavior belongs in `CHANGELOG.md`; durable contracts belong in `AGENTS.md` and `/docs`._
 
-## Routing Lifetime External Report
+## Post-Release Transport Recovery Acceptance
 
-- [ ] Report the patch's precise shipped routing-lifetime scope externally only after separate authorization and verified release evidence. Do not claim a universal TTL or cleanup of historical originals lacking saved chooser clocks; native Windows destructive cleanup remains gated on strict evidence.
-- Evidence boundary: The operator reports passing TTL live acceptance. New continuation-reaction and callback-copy behavior has native regression evidence, not a separate live-client claim. Neither establishes native Windows Restore/destructive-cleanup support. Completed implementation is recorded in `CHANGELOG.md`; durable contracts remain in `/docs`.
+- Release boundary: The operator authorized the hotfix on native regression and CI evidence; real Telegram smoke/fault acceptance remains open below, not a claimed completed check. Installing/reloading Pi or injecting live faults needs separate authorization.
+- CI boundary: Native Linux/macOS/Windows checks exercise capped poll/admission backoff, preserved persistent-conflict stand-down and generation-fenced manual disconnect. Existing skipped strict journal witnesses remain a separate Windows boundary; green CI does not replace operator acceptance.
+- [ ] Obtain operator acceptance for ordinary disconnect, unconfirmed-cleanup reporting and outage recovery without manual reconnect on a disposable setup. Local fake-transport/storage regressions do not certify real Telegram or platform fault behavior; installation/reload and live fault injection require separate authorization.
+- Acceptance: Captured manual stop never affects a replacement connection or bypasses Thread deletion fences, uncertain stop is not retried, and accepted local work is preserved. Session-restart cleanup remains admission-required.
 
 ## Windows Reliability
 

package/CHANGELOG.md

@@ -4,6 +4,12 @@
 
 ## Unreleased
 
+## 0.52.2: Polling recovery, safe disconnect and Windows downloads
+
+- `Polling recovery`: Non-conflict poll/admission failures back off from 1 to 30 seconds and keep retrying, allowing recovery after prolonged outages without manual reconnect. Backoff resets only after durable admission succeeds; persistent competing-client conflicts retain their existing terminal stand-down.
+- `Disconnect safety`: Failed or unavailable Thread cleanup still attempts one captured local transport stop without bypassing Workspace fences. Reconnect revokes stale cleanup/stop continuations; delayed teardown cannot release replacement ownership. Unconfirmed cleanup is reported without claiming it was skipped, while uncertain stop/release outcomes remain incomplete and are never blindly retried ([#310](https://github.com/llblab/pi-telegram/pull/310)).
+- `Windows downloads`: Publishing a complete attachment retries transient Windows `EPERM`/`EACCES` sharing failures for at most six rename attempts, without replaying HTTP. Cancellation stops the bounded wait; permanent/non-sharing failures still propagate and remove the private partial file. Concurrent downloads retain deterministic names and complete-file publication.
+
 ## 0.52.1: Finite chooser lifetime, continue cancellation and callback copy
 
 - `Chooser expiry`: Fixed 60-minute clocks end unselected/unacknowledged donor routing without archives or replay. Fully resolved disposable tabs use fenced one-shot cleanup; accepted queues, independent work and restored Threads survive. Confirmed expiry clears worker custody even if cleanup fails; metadata retries use body-free proof and never repeat an issued delete. Cold startup preserves deadlines, and queue admission retains selected lifetime metadata.

package/README.md

@@ -69,6 +69,8 @@ The prompt queue is session-local. Before a reload or restart, let it drain or k
 
 Journal recovery is a separate existing loss policy, not shared-envelope recovery. A snapshot removed by older broad temp cleanup is rebuilt when its complete segment history proves an empty result, while a revisionless snapshot is repaired from the first surviving segment's exact predecessor when the reconstructed tail validates. Otherwise the damaged snapshot and segments are deleted (their inputs are lost), a fresh journal is published, and startup continues with an informational diagnostic. Unsupported journal versions block recovery without rewriting or quarantining retained files; use a compatible runtime rather than deleting journals. Saved `telegram.json` configuration and runtime diagnostics are outside that journal reset. Startup best-effort removes obsolete current-runtime root/session `recovery/` folders, so those directories are not a preservation location.
 
+Ordinary network or admission failures use exponential retry pauses capped at 30 seconds, without permanently stopping after an arbitrary attempt count. The poller recovers when the outage clears. Explicit `/telegram-disconnect` still attempts to stop its captured local transport if Thread cleanup is unavailable; it reports unconfirmed cleanup rather than successful deletion, and an old disconnect cannot stop a new connection. Incomplete stop/release remains visible; check `/telegram-status --debug` and keep Pi open.
+
 Persistent competing `getUpdates` clients cause a bounded transport stand-down rather than endless retries. Accepted local work remains queued/executable, but Telegram delivery stops. Inspect `/telegram-status --debug`, stop the competing client, then reconnect. See [Runtime Ownership](./docs/architecture.md#runtime-ownership).
 
 ### 4. Pair your Telegram account

package/dist/lib/extension.js

@@ -1551,6 +1551,7 @@ export default function (pi) {
         getSyncState: telegramSyncStateRuntime.getState,
         setSyncState: telegramSyncStateRuntime.setState,
         stopPolling: lockedPollingRuntime.stop,
+        captureStopPolling: lockedPollingRuntime.captureStop,
         suspendPolling: lockedPollingRuntime.suspend,
         recordRuntimeEvent,
         runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,

package/dist/lib/locks.d.ts

@@ -215,6 +215,11 @@ type TelegramLockedPollingStartResult = {
 export interface TelegramLockedPollingRuntime<TContext extends TelegramLockContext> {
     start: (ctx: TContext, options?: TelegramLockedPollingStartOptions) => Promise<TelegramLockedPollingStartResult>;
     stop: () => Promise<string>;
+    /** Capture one disconnect attempt before cleanup awaits; a newer start revokes it. */
+    captureStop: () => {
+        isCurrent: () => boolean;
+        stop: () => Promise<string>;
+    };
     suspend: () => Promise<void>;
     isSuspended: () => boolean;
     /** Fence one owned polling generation; suspension, restart, conflict or lock loss revokes it. */

package/dist/lib/locks.js

@@ -1210,6 +1210,8 @@ export function createTelegramLockedPollingRuntime(deps) {
             stopOwnershipWatcher();
             if (sessionAutoStartRun) {
                 await sessionAutoStartRun;
+                if (generation !== pollingGeneration)
+                    return;
                 deps.stopFollowerRegistration?.();
             }
             if (ownershipStop) {
@@ -1325,6 +1327,21 @@ export function createTelegramLockedPollingRuntime(deps) {
     const canStartPolling = (ctx) => deps.canStartPolling?.(ctx) ?? true;
     const formatStartBlockedMessage = (ctx) => deps.formatStartBlockedMessage?.(ctx) ??
         "Telegram polling is unavailable in this Pi run mode.";
+    const stop = async () => {
+        const generation = pollingGeneration + 1;
+        await suspendPolling();
+        if (generation !== pollingGeneration)
+            throw new Error("Telegram disconnect was superseded by a new connection.");
+        const state = deps.lock.release();
+        deps.onTransportAvailabilityChanged?.();
+        if (state.kind === "active-elsewhere") {
+            return `Telegram bridge is active in another Pi instance (${formatTelegramLockEntry(state.lock)}).`;
+        }
+        if (state.kind === "stale") {
+            return `Removed stale Telegram bridge lock (${formatTelegramLockEntry(state.lock)}).`;
+        }
+        return "Telegram bridge disconnected.";
+    };
     return {
         start: async (ctx, options = {}) => {
             if (!deps.hasBotToken()) {
@@ -1440,17 +1457,18 @@ export function createTelegramLockedPollingRuntime(deps) {
             const staleSuffix = acquired.replacedStale ? " Replaced stale lock." : "";
             return { ok: true, message: `Telegram bridge connected.${staleSuffix}` };
         },
-        stop: async () => {
-            await suspendPolling();
-            const state = deps.lock.release();
-            deps.onTransportAvailabilityChanged?.();
-            if (state.kind === "active-elsewhere") {
-                return `Telegram bridge is active in another Pi instance (${formatTelegramLockEntry(state.lock)}).`;
-            }
-            if (state.kind === "stale") {
-                return `Removed stale Telegram bridge lock (${formatTelegramLockEntry(state.lock)}).`;
-            }
-            return "Telegram bridge disconnected.";
+        stop,
+        captureStop() {
+            const generation = pollingGeneration;
+            const isCurrent = () => generation === pollingGeneration;
+            return {
+                isCurrent,
+                async stop() {
+                    if (!isCurrent())
+                        throw new Error("Telegram disconnect was superseded by a new connection.");
+                    return stop();
+                },
+            };
         },
         suspend: suspendPolling,
         captureTransportAuthority(ctx) {

package/dist/lib/polling.d.ts

@@ -28,6 +28,8 @@ export declare class TelegramPersistentGetUpdatesConflictError extends Error {
     readonly count: number;
     constructor(count: number);
 }
+/** Exponential backoff for non-conflict polling/admission failures. */
+export declare function getTelegramPollingRetryDelayMs(consecutiveFailures: number): number;
 export declare class TelegramGetUpdatesTimeoutError extends Error {
     readonly timeoutMs: number;
     constructor(timeoutMs: number);

package/dist/lib/polling.js

@@ -14,7 +14,8 @@ export const TELEGRAM_GET_UPDATES_CONFLICT_STOP_LIMIT = 10;
 const TELEGRAM_GET_UPDATES_CONFLICT_FAST_RETRY_LIMIT = 3;
 const TELEGRAM_GET_UPDATES_CONFLICT_FAST_RETRY_MS = 1_000;
 const TELEGRAM_GET_UPDATES_CONFLICT_SLOW_RETRY_MS = 3_000;
-const TELEGRAM_POLLING_RETRY_MS = 3_000;
+const TELEGRAM_POLLING_RETRY_BASE_MS = 1_000;
+const TELEGRAM_POLLING_RETRY_MAX_MS = 30_000;
 const TELEGRAM_GET_UPDATES_GRACE_MS = 10_000;
 // Standard Telegram DM polling does not expose ordinary message-deletion events.
 // Business deletions belong to a separate namespace and default routing ignores them.
@@ -51,6 +52,11 @@ export class TelegramPersistentGetUpdatesConflictError extends Error {
         this.count = count;
     }
 }
+/** Exponential backoff for non-conflict polling/admission failures. */
+export function getTelegramPollingRetryDelayMs(consecutiveFailures) {
+    const exponent = Math.max(0, Math.min(consecutiveFailures - 1, 16));
+    return Math.min(TELEGRAM_POLLING_RETRY_BASE_MS * 2 ** exponent, TELEGRAM_POLLING_RETRY_MAX_MS);
+}
 export class TelegramGetUpdatesTimeoutError extends Error {
     timeoutMs;
     constructor(timeoutMs) {
@@ -1103,6 +1109,7 @@ export async function runTelegramPollLoop(deps) {
     if (!deps.config.botToken)
         return;
     let consecutiveGetUpdatesConflicts = 0;
+    let consecutiveFailures = 0;
     const retryConflict = async () => {
         consecutiveGetUpdatesConflicts += 1;
         if (consecutiveGetUpdatesConflicts >= TELEGRAM_GET_UPDATES_CONFLICT_STOP_LIMIT) {
@@ -1171,6 +1178,7 @@ export async function runTelegramPollLoop(deps) {
                 onPhaseChange: deps.onPhaseChange,
                 recordRuntimeEvent: deps.recordRuntimeEvent,
             });
+            consecutiveFailures = 0;
             currentUpdateId = undefined;
         }
         catch (error) {
@@ -1190,8 +1198,10 @@ export async function runTelegramPollLoop(deps) {
                     : {}),
             });
             consecutiveGetUpdatesConflicts = 0;
+            consecutiveFailures += 1;
             deps.onErrorStatus(getTelegramPollingErrorMessage(error));
-            await deps.sleep(TELEGRAM_POLLING_RETRY_MS, deps.signal);
+            // Cap the pause, not retry count: outages must recover without manual reconnect.
+            await deps.sleep(getTelegramPollingRetryDelayMs(consecutiveFailures), deps.signal);
             if (deps.signal.aborted)
                 return;
             deps.onStatusReset();

package/dist/lib/sync.d.ts

@@ -92,6 +92,7 @@ export interface TelegramManualThreadDisconnectDeps<TSyncState> {
     recordRuntimeEvent: (category: string, error: unknown, details?: Record<string, unknown>) => void;
     runWorkspaceOperation: TelegramSyncWorkspaceOperationRunner;
     workspaceOperationKind?: string;
+    isDisconnectCurrent?: () => boolean;
     getNowMs?: () => number;
 }
 export declare function createTelegramPreservedLeaderQuitHandler(deps: {
@@ -112,6 +113,10 @@ export interface TelegramThreadDisconnectAssembly {
 }
 export declare function createTelegramThreadDisconnectAssembly<TSyncState extends TelegramSyncState>(deps: Omit<TelegramManualThreadDisconnectDeps<TSyncState>, "stopPolling"> & {
     stopPolling: () => Promise<string>;
+    captureStopPolling?: () => {
+        isCurrent: () => boolean;
+        stop: () => Promise<string>;
+    };
     suspendPolling: () => Promise<void>;
 }): TelegramThreadDisconnectAssembly;
 export declare function createTelegramManualThreadDisconnectHandler<TSyncState extends TelegramSyncState>(deps: TelegramManualThreadDisconnectDeps<TSyncState>): () => Promise<string>;

package/dist/lib/sync.js

@@ -74,11 +74,41 @@ function createTelegramSessionRestartThreadCleanupHandler(deps) {
 }
 export function createTelegramThreadDisconnectAssembly(deps) {
     return {
-        disconnect: createTelegramManualThreadDisconnectHandler({
-            ...deps,
-            workspaceOperationKind: "workspace.disconnect-thread",
-            stopPolling: deps.stopPolling,
-        }),
+        async disconnect() {
+            const captured = deps.captureStopPolling?.();
+            const stop = captured?.stop ?? deps.stopPolling;
+            let stopAttempted = false;
+            const disconnect = createTelegramManualThreadDisconnectHandler({
+                ...deps,
+                workspaceOperationKind: "workspace.disconnect-thread",
+                isDisconnectCurrent: captured?.isCurrent ?? deps.isDisconnectCurrent,
+                stopPolling() {
+                    stopAttempted = true;
+                    return stop();
+                },
+            });
+            try {
+                return await disconnect();
+            }
+            catch (error) {
+                // Never retry a stop whose teardown/release outcome may already have committed.
+                if (stopAttempted) {
+                    deps.recordRuntimeEvent("connection", error, { phase: "disconnect-stop" });
+                    throw error;
+                }
+                deps.recordRuntimeEvent("connection", error, { phase: "disconnect-cleanup" });
+                let stopped;
+                try {
+                    stopped = await stop();
+                }
+                catch (stopError) {
+                    deps.recordRuntimeEvent("connection", stopError, { phase: "disconnect-stop" });
+                    throw stopError;
+                }
+                const separator = /[.!?]$/u.test(stopped) ? " " : ". ";
+                return `${stopped}${separator}Thread cleanup was not confirmed. Check /telegram-status --debug.`;
+            }
+        },
         cleanupForSessionRestart: createTelegramSessionRestartThreadCleanupHandler({
             ...deps,
             suspendPolling: deps.suspendPolling,
@@ -86,7 +116,12 @@ export function createTelegramThreadDisconnectAssembly(deps) {
     };
 }
 export function createTelegramManualThreadDisconnectHandler(deps) {
+    const assertCurrent = () => {
+        if (deps.isDisconnectCurrent?.() === false)
+            throw new Error("Telegram disconnect was superseded by a new connection.");
+    };
     const operation = async () => {
+        assertCurrent();
         const currentRecord = deps.getCurrentThreadRecord();
         let cleanupPending = false;
         if (currentRecord?.target.threadId) {
@@ -98,6 +133,7 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
             if (isManualFollower && !ownsLeader) {
                 if (deps.disconnectFollowerThread) {
                     const disconnected = await deps.disconnectFollowerThread();
+                    assertCurrent();
                     if (!disconnected) {
                         throw new Error("Telegram follower thread deletion requires a live leader registration.");
                     }
@@ -122,6 +158,7 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
                 const isCleanupTargetProtected = createTelegramCleanupTargetProtection(deps.topicTargetStore, departingRecord);
                 deps.topicTargetStore.upsertPendingCleanup(intent);
                 await deps.topicTargetStore.persist();
+                assertCurrent();
                 const cleanupPlan = ThreadReconciler.planThreadReconciliation({
                     nowMs: (deps.getNowMs ?? Date.now)(),
                     currentLeaderEpoch: leaderEpoch,
@@ -131,20 +168,25 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
                 const cleanup = await ThreadReconciler.applyThreadReconciliationPlan(cleanupPlan, {
                     isCleanupTargetProtected,
                     callApi(method, body) {
+                        assertCurrent();
                         return deps.callApi(method, body);
                     },
                     markStaleByTarget(targetToMark, syncStatus, lastSyncError) {
+                        assertCurrent();
                         return deps.topicTargetStore.markStaleByTarget(targetToMark, syncStatus, lastSyncError);
                     },
                     removeCleanupIntentById(id) {
+                        assertCurrent();
                         return deps.topicTargetStore.removePendingCleanup(id);
                     },
                     persist() {
+                        assertCurrent();
                         return deps.topicTargetStore.persist();
                     },
                     getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
                     recordRuntimeEvent: deps.recordRuntimeEvent,
                 });
+                assertCurrent();
                 if (cleanupPlan.actions.some((action) => isCleanupTargetProtected(action.target, action))) {
                     return "Thread disconnect superseded by a new binding.";
                 }
@@ -160,6 +202,7 @@ export function createTelegramManualThreadDisconnectHandler(deps) {
                 action: "manual-disconnect",
             }));
         }
+        assertCurrent();
         const stopped = await deps.stopPolling();
         return cleanupPending
             ? `${stopped} Telegram thread cleanup remains pending for the next leader.`

package/dist/lib/telegram-api.js

@@ -30,6 +30,7 @@ function getTelegramApiTempDir() {
     return resolveTelegramAttachmentsDir();
 }
 const TELEGRAM_TEMP_FILE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const TELEGRAM_DOWNLOAD_RENAME_MAX_ATTEMPTS = 6;
 const activeTelegramApiWorkspaceAdmissionOperationIds = new Set();
 const TELEGRAM_INBOUND_FILE_MAX_BYTES = getTelegramInboundFileByteLimitFromEnv(process.env, ["PI_TELEGRAM_INBOUND_FILE_MAX_BYTES", "TELEGRAM_MAX_FILE_SIZE_BYTES"], TELEGRAM_FILE_MAX_BYTES);
 const TELEGRAM_NETWORK_FAMILY_ENV = "PI_TELEGRAM_NETWORK_FAMILY";
@@ -391,6 +392,22 @@ async function writeTelegramDownloadResponse(response, targetPath, maxFileSizeBy
     }
     await pipeline(Readable.from(response.body, { objectMode: false }), createTelegramDownloadLimitTransform(maxFileSizeBytes), createWriteStream(targetPath, { mode: 0o600 }));
 }
+async function publishTelegramDownload(partPath, targetPath, signal) {
+    for (let attempt = 0;; attempt++) {
+        throwIfTelegramApiCallAborted(signal);
+        try {
+            await rename(partPath, targetPath);
+            return;
+        }
+        catch (error) {
+            const code = error?.code;
+            // Windows may briefly deny replacement while another publisher/scanner holds the file.
+            if (process.platform !== "win32" || (code !== "EPERM" && code !== "EACCES") || attempt + 1 >= TELEGRAM_DOWNLOAD_RENAME_MAX_ATTEMPTS)
+                throw error;
+            await sleepTelegramRetry(50 * 2 ** attempt, signal);
+        }
+    }
+}
 async function removeTelegramPartialDownload(path) {
     try {
         await unlink(path);
@@ -787,7 +804,7 @@ export async function downloadTelegramFile(botToken, fileId, suggestedName, temp
     assertTelegramFileSizeWithinLimit(contentLength ? Number.parseInt(contentLength, 10) : undefined, options?.maxFileSizeBytes);
     try {
         await writeTelegramDownloadResponse(response, partPath, options?.maxFileSizeBytes);
-        await rename(partPath, targetPath);
+        await publishTelegramDownload(partPath, targetPath, options?.signal);
     }
     catch (error) {
         await removeTelegramPartialDownload(partPath);

package/dist/package.json

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

package/docs/architecture.md

@@ -334,10 +334,12 @@ Read-only migration probes constrain that comparison. Publishing a v2 snapshot o
 
 ### Runtime Ownership
 
-- `/telegram-connect` acquires or moves the active profile's owner slot before polling starts. `/telegram-disconnect` keeps its destructive confirmation, then stops polling and releases only that exact slot. In Threaded Mode it tears down the disconnecting instance's bound Telegram thread: leaders delete their own thread directly, and followers send an authenticated exact-generation disconnect envelope and wait for confirmed leader cleanup before unregistering. Graceful Pi `quit` always preserves the owner slot as restart intent, allowing a reopened same-`cwd` session to reclaim the stale lease. When `threads.automaticCleanup` is enabled (the default), quit also deletes the bound Telegram tab without releasing that restart intent; disabling it preserves the tab. After delivery, polling and inbound-worker shutdown complete, a quitting leader detaches its exact owner record under profile admission while retaining the Workspace, letter and restart ownership. Publication rechecks the captured session generation, profile, leader epoch and successful current-generation suspension; unfinished startup/teardown, unproven suspension and pending cleanup stay protected. Preparation/publication errors are diagnostic and cannot block remaining session cleanup. Failed automatic deletion likewise falls back to safe suspension.
+- `/telegram-connect` acquires or moves the active profile's owner slot before polling starts. `/telegram-disconnect` keeps its destructive confirmation, then stops polling and releases only that exact slot. In Threaded Mode it tears down the disconnecting instance's bound Telegram thread: leaders delete their own thread directly, and followers send an authenticated exact-generation disconnect envelope seeking confirmed leader cleanup before unregistering. If cleanup fails, explicit manual disconnect may instead stop its captured local transport without claiming Thread deletion. Graceful Pi `quit` always preserves the owner slot as restart intent, allowing a reopened same-`cwd` session to reclaim the stale lease. When `threads.automaticCleanup` is enabled (the default), quit also deletes the bound Telegram tab without releasing that restart intent; disabling it preserves the tab. After delivery, polling and inbound-worker shutdown complete, a quitting leader detaches its exact owner record under profile admission while retaining the Workspace, letter and restart ownership. Publication rechecks the captured session generation, profile, leader epoch and successful current-generation suspension; unfinished startup/teardown, unproven suspension and pending cleanup stay protected. Preparation/publication errors are diagnostic and cannot block remaining session cleanup. Failed automatic deletion likewise falls back to safe suspension.
+- Explicit manual disconnect captures one lifecycle-generation-bound stop before entering cleanup admission. The cleanup path rechecks that captured authority before observing a target, after intent publication, before API/store effects and after awaited reconciliation. A newer connection revokes old cleanup and fallback stop; teardown also checks its generation after suspension before durable lock release. Cleanup admission failure may trigger only the captured local stop, not an unguarded latest-runtime stop or new Thread mutations. Failed cleanup reports unconfirmed outcome with debug guidance rather than claiming deletion was skipped or exposing raw errors. A stop/release error propagates as incomplete without another teardown attempt. Session-restart cleanup remains fail-closed behind admission fences and never uses this manual fallback.
 - Without an explicit carried connection intent, session start schedules polling resume asynchronously only when the owner slot already points at the current `pid`/`cwd`, or when a stale same-`cwd` owner can be safely replaced after process restart. Under a live foreign leader, startup instead attempts capability-gated restore-only follower admission when the selected profile has a remembered exact-`cwd` Workspace binding; it never provisions an unremembered Workspace. Startup and `/resume` do not wait on leader election, Bot API probes, poller handoff, or thread reconciliation before restoring the Pi session.
 - On local `/resume`, an in-flight `/telegram-connect` or established connection supplies one process-local, 30-second intent containing the selected profile, exact CWD and target session file. The file matches only the lifecycle successor; the fresh public session ID still owns binding selection. Startup claims intent before asynchronous initialization and uses the normal connection path instead of concurrent auto-restore. Quit/reload/disconnect, mismatch, expiry or supersession cancel it. The predecessor carries no Pi context, callback, Thread or slot, and late completion can clear only its own attempt. Resume startup has no automatic forced takeover or repeated failure retry; errors remain diagnostic with a compact recovery notice.
 - The polling owner alone bounds `getUpdates`: each request derives its cancellation budget from Telegram's declared long-poll timeout plus 10 seconds of transport grace (10 seconds for the zero-timeout initial sync and 40 seconds for the normal 30-second poll). The request-local controller inherits poller cancellation, rejects its owner at the budget, and fences any late transport result. Ordinary Bot API and media operations do not receive speculative blanket deadlines. Existing caller signals remain authoritative through API retry waits, only retry-safe methods replay explicit retryable responses, and non-idempotent sends preserve commit-unknown evidence instead of risking duplicate mutation.
+- Ordinary non-conflict poll/admission failures retry with exponential pauses of `1s → 2s → 4s → 8s → 16s → 30s`, capped at 30 seconds without a retry-count ceiling. Only successful durable admission resets this backoff; a successful HTTP response followed by journal failure does not. Retry sleeps remain poller-abortable, and accepted inputs/cursor ordering are unchanged. Outages therefore recover through the existing poller without manual reconnect.
 - Ten consecutive `getUpdates` conflict responses, including initial cursor sync, terminate polling with `persistent-conflict`; a successful response or a different error resets the count. The controller detaches its inner promise before notifying the locked lifecycle, avoiding teardown waiting on itself. That lifecycle stops ownership checks, lease refresh, capability monitoring, typing, and classic or bus transport (including leader health, pruning, and IPC), withdraws local direct authority, and transactionally releases only its exact lock. A failed durable release leaves local authority revoked; explicit reacquisition mints a fresh epoch. Accepted queue receipts and local Pi dispatch survive. One terminal diagnostic distinguishes lost local ownership from a competing client despite an apparently owned lock and reports cleanup failures; ordinary status refreshes retain generic `error` until transport recovers. Remove the competing client, then use `/telegram-connect`; no automatic retry continues after the terminal threshold.
 - Manual and automatic polling starts share a lifecycle generation. A later suspend, disconnect, persistent-conflict stop, or accepted start invalidates older startup continuations; reconnect captures its generation before waiting for transport teardown and rechecks it before acquiring ownership and after awaited startup work. Obsolete completion or failure cannot report a successful connection or roll back a replacement. Admission rejects stale/unauthorized contexts before advancing its own startup generation, so a rejected call cannot cancel valid in-flight initialization. After awaited bus startup, thread-aware completion checks its generation before starting leader health or changing fallback/startup-option state; teardown clears health independently of the current mode flag. Startup probes, capability-monitor transitions, and observed-target transitions share an orchestration lifecycle fence and check it inside their effect-owning helpers after awaited queries, persistence, or transport work. Monitor stop also invalidates pending observations. These checks suppress subsequent state changes, fallback, health, and status effects; already-issued API/persistence calls retain their own transport/storage fencing.
 - `pollingActive` reports only whether this runtime still owns an unresolved polling lifecycle; it is not health evidence. A separate observable state records `starting`, `long-poll`, `persisting-journal`, `persisting-offset`, `retrying`, or `stopped`, together with phase start, current update id, last successful response time/count, and terminal stop reason. This distinguishes a stuck HTTP poll from downstream update work without a wall-clock stale heuristic.
@@ -521,6 +523,8 @@ All inbound updates are gated by the configured authorized user id.
 8. Remove local prompt journal authority synchronously immediately before `sendUserMessage`, so session/process replacement can lose an unstarted prompt at that narrow crash boundary but can never replay a prompt already admitted to Pi; controls and foreign forwarding retain their explicit settlement boundaries.
 9. Handle `edited_message` updates separately while the original turn is still queued and dispatch only when all safety gates are clear.
 
+Attachments stream into private unique `.part` files and publish by rename only after complete, size-checked download. Windows `EPERM`/`EACCES` sharing failures allow at most six rename attempts, with abortable `50/100/200/400/800 ms` waits; no metadata/content HTTP request is replayed. Non-Windows, non-sharing and exhausted errors propagate, cancellation stops retries, and failure removes the partial file without deleting the existing target. This is attachment publication policy, not a journal/state recovery rule or strict Windows evidence.
+
 #### Durable Admission And Recovery
 
 Here, **durable** means recovery across ordinary process exit, crash, kill, and replacement after a successful atomic rename is visible to the filesystem. It does not promise survival across host, kernel, filesystem, storage-device, or power failure: journal and offset publication do not call `fsync`/`fdatasync`, and parent directories are not flushed. A host-level failure may therefore lose a recently acknowledged rename despite correct process-level ordering. Operators requiring that stronger boundary must place the agent directory on storage with an independently managed durability/backup policy; `0.28.0` must not be described as power-loss durable.

package/lib/extension.ts

@@ -1818,6 +1818,7 @@ export default function (pi: Pi.ExtensionAPI) {
     getSyncState: telegramSyncStateRuntime.getState,
     setSyncState: telegramSyncStateRuntime.setState,
     stopPolling: lockedPollingRuntime.stop,
+    captureStopPolling: lockedPollingRuntime.captureStop,
     suspendPolling: lockedPollingRuntime.suspend,
     recordRuntimeEvent,
     runWorkspaceOperation: telegramWorkspaceOperationRuntime.run,

package/lib/locks.ts

@@ -1489,6 +1489,8 @@ export interface TelegramLockedPollingRuntime<
     options?: TelegramLockedPollingStartOptions,
   ) => Promise<TelegramLockedPollingStartResult>;
   stop: () => Promise<string>;
+  /** Capture one disconnect attempt before cleanup awaits; a newer start revokes it. */
+  captureStop: () => { isCurrent: () => boolean; stop: () => Promise<string> };
   suspend: () => Promise<void>;
   isSuspended: () => boolean;
   /** Fence one owned polling generation; suspension, restart, conflict or lock loss revokes it. */
@@ -1582,6 +1584,7 @@ export function createTelegramLockedPollingRuntime<
       stopOwnershipWatcher();
       if (sessionAutoStartRun) {
         await sessionAutoStartRun;
+        if (generation !== pollingGeneration) return;
         deps.stopFollowerRegistration?.();
       }
       if (ownershipStop) {
@@ -1687,6 +1690,20 @@ export function createTelegramLockedPollingRuntime<
   const formatStartBlockedMessage = (ctx: TContext): string =>
     deps.formatStartBlockedMessage?.(ctx) ??
     "Telegram polling is unavailable in this Pi run mode.";
+  const stop = async (): Promise<string> => {
+    const generation = pollingGeneration + 1;
+    await suspendPolling();
+    if (generation !== pollingGeneration) throw new Error("Telegram disconnect was superseded by a new connection.");
+    const state = deps.lock.release();
+    deps.onTransportAvailabilityChanged?.();
+    if (state.kind === "active-elsewhere") {
+      return `Telegram bridge is active in another Pi instance (${formatTelegramLockEntry(state.lock)}).`;
+    }
+    if (state.kind === "stale") {
+      return `Removed stale Telegram bridge lock (${formatTelegramLockEntry(state.lock)}).`;
+    }
+    return "Telegram bridge disconnected.";
+  };
   return {
     start: async (ctx, options = {}) => {
       if (!deps.hasBotToken()) {
@@ -1798,17 +1815,17 @@ export function createTelegramLockedPollingRuntime<
       const staleSuffix = acquired.replacedStale ? " Replaced stale lock." : "";
       return { ok: true, message: `Telegram bridge connected.${staleSuffix}` };
     },
-    stop: async () => {
-      await suspendPolling();
-      const state = deps.lock.release();
-      deps.onTransportAvailabilityChanged?.();
-      if (state.kind === "active-elsewhere") {
-        return `Telegram bridge is active in another Pi instance (${formatTelegramLockEntry(state.lock)}).`;
-      }
-      if (state.kind === "stale") {
-        return `Removed stale Telegram bridge lock (${formatTelegramLockEntry(state.lock)}).`;
-      }
-      return "Telegram bridge disconnected.";
+    stop,
+    captureStop() {
+      const generation = pollingGeneration;
+      const isCurrent = () => generation === pollingGeneration;
+      return {
+        isCurrent,
+        async stop() {
+          if (!isCurrent()) throw new Error("Telegram disconnect was superseded by a new connection.");
+          return stop();
+        },
+      };
     },
     suspend: suspendPolling,
     captureTransportAuthority(ctx) {

package/lib/polling.ts

@@ -25,7 +25,8 @@ export const TELEGRAM_GET_UPDATES_CONFLICT_STOP_LIMIT = 10;
 const TELEGRAM_GET_UPDATES_CONFLICT_FAST_RETRY_LIMIT = 3;
 const TELEGRAM_GET_UPDATES_CONFLICT_FAST_RETRY_MS = 1_000;
 const TELEGRAM_GET_UPDATES_CONFLICT_SLOW_RETRY_MS = 3_000;
-const TELEGRAM_POLLING_RETRY_MS = 3_000;
+const TELEGRAM_POLLING_RETRY_BASE_MS = 1_000;
+const TELEGRAM_POLLING_RETRY_MAX_MS = 30_000;
 const TELEGRAM_GET_UPDATES_GRACE_MS = 10_000;
 
 // Standard Telegram DM polling does not expose ordinary message-deletion events.
@@ -79,6 +80,17 @@ export class TelegramPersistentGetUpdatesConflictError extends Error {
   }
 }
 
+/** Exponential backoff for non-conflict polling/admission failures. */
+export function getTelegramPollingRetryDelayMs(
+  consecutiveFailures: number,
+): number {
+  const exponent = Math.max(0, Math.min(consecutiveFailures - 1, 16));
+  return Math.min(
+    TELEGRAM_POLLING_RETRY_BASE_MS * 2 ** exponent,
+    TELEGRAM_POLLING_RETRY_MAX_MS,
+  );
+}
+
 export class TelegramGetUpdatesTimeoutError extends Error {
   readonly timeoutMs: number;
 
@@ -1709,6 +1721,7 @@ export async function runTelegramPollLoop<
 >(deps: TelegramPollLoopDeps<TUpdate, TContext>): Promise<void> {
   if (!deps.config.botToken) return;
   let consecutiveGetUpdatesConflicts = 0;
+  let consecutiveFailures = 0;
   const retryConflict = async () => {
     consecutiveGetUpdatesConflicts += 1;
     if (consecutiveGetUpdatesConflicts >= TELEGRAM_GET_UPDATES_CONFLICT_STOP_LIMIT) {
@@ -1791,6 +1804,7 @@ export async function runTelegramPollLoop<
         onPhaseChange: deps.onPhaseChange,
         recordRuntimeEvent: deps.recordRuntimeEvent,
       });
+      consecutiveFailures = 0;
       currentUpdateId = undefined;
     } catch (error) {
       if (shouldStopTelegramPolling(deps.signal.aborted, error)) return;
@@ -1809,8 +1823,13 @@ export async function runTelegramPollLoop<
           : {}),
       });
       consecutiveGetUpdatesConflicts = 0;
+      consecutiveFailures += 1;
       deps.onErrorStatus(getTelegramPollingErrorMessage(error));
-      await deps.sleep(TELEGRAM_POLLING_RETRY_MS, deps.signal);
+      // Cap the pause, not retry count: outages must recover without manual reconnect.
+      await deps.sleep(
+        getTelegramPollingRetryDelayMs(consecutiveFailures),
+        deps.signal,
+      );
       if (deps.signal.aborted) return;
       deps.onStatusReset();
     }

package/lib/sync.ts

@@ -176,6 +176,7 @@ export interface TelegramManualThreadDisconnectDeps<TSyncState> {
   ) => void;
   runWorkspaceOperation: TelegramSyncWorkspaceOperationRunner;
   workspaceOperationKind?: string;
+  isDisconnectCurrent?: () => boolean;
   getNowMs?: () => number;
 }
 
@@ -270,15 +271,44 @@ export function createTelegramThreadDisconnectAssembly<
 >(
   deps: Omit<TelegramManualThreadDisconnectDeps<TSyncState>, "stopPolling"> & {
     stopPolling: () => Promise<string>;
+    captureStopPolling?: () => { isCurrent: () => boolean; stop: () => Promise<string> };
     suspendPolling: () => Promise<void>;
   },
 ): TelegramThreadDisconnectAssembly {
   return {
-    disconnect: createTelegramManualThreadDisconnectHandler({
-      ...deps,
-      workspaceOperationKind: "workspace.disconnect-thread",
-      stopPolling: deps.stopPolling,
-    }),
+    async disconnect() {
+      const captured = deps.captureStopPolling?.();
+      const stop = captured?.stop ?? deps.stopPolling;
+      let stopAttempted = false;
+      const disconnect = createTelegramManualThreadDisconnectHandler({
+        ...deps,
+        workspaceOperationKind: "workspace.disconnect-thread",
+        isDisconnectCurrent: captured?.isCurrent ?? deps.isDisconnectCurrent,
+        stopPolling() {
+          stopAttempted = true;
+          return stop();
+        },
+      });
+      try {
+        return await disconnect();
+      } catch (error) {
+        // Never retry a stop whose teardown/release outcome may already have committed.
+        if (stopAttempted) {
+          deps.recordRuntimeEvent("connection", error, { phase: "disconnect-stop" });
+          throw error;
+        }
+        deps.recordRuntimeEvent("connection", error, { phase: "disconnect-cleanup" });
+        let stopped: string;
+        try {
+          stopped = await stop();
+        } catch (stopError) {
+          deps.recordRuntimeEvent("connection", stopError, { phase: "disconnect-stop" });
+          throw stopError;
+        }
+        const separator = /[.!?]$/u.test(stopped) ? " " : ". ";
+        return `${stopped}${separator}Thread cleanup was not confirmed. Check /telegram-status --debug.`;
+      }
+    },
     cleanupForSessionRestart:
       createTelegramSessionRestartThreadCleanupHandler({
         ...deps,
@@ -290,7 +320,11 @@ export function createTelegramThreadDisconnectAssembly<
 export function createTelegramManualThreadDisconnectHandler<
   TSyncState extends TelegramSyncState,
 >(deps: TelegramManualThreadDisconnectDeps<TSyncState>): () => Promise<string> {
+  const assertCurrent = () => {
+    if (deps.isDisconnectCurrent?.() === false) throw new Error("Telegram disconnect was superseded by a new connection.");
+  };
   const operation = async (): Promise<string> => {
+    assertCurrent();
     const currentRecord = deps.getCurrentThreadRecord();
     let cleanupPending = false;
     if (currentRecord?.target.threadId) {
@@ -302,6 +336,7 @@ export function createTelegramManualThreadDisconnectHandler<
       if (isManualFollower && !ownsLeader) {
         if (deps.disconnectFollowerThread) {
           const disconnected = await deps.disconnectFollowerThread();
+          assertCurrent();
           if (!disconnected) {
             throw new Error(
               "Telegram follower thread deletion requires a live leader registration.",
@@ -329,6 +364,7 @@ export function createTelegramManualThreadDisconnectHandler<
         const isCleanupTargetProtected = createTelegramCleanupTargetProtection(deps.topicTargetStore, departingRecord);
         deps.topicTargetStore.upsertPendingCleanup(intent);
         await deps.topicTargetStore.persist();
+        assertCurrent();
         const cleanupPlan = ThreadReconciler.planThreadReconciliation({
           nowMs: (deps.getNowMs ?? Date.now)(),
           currentLeaderEpoch: leaderEpoch,
@@ -340,9 +376,11 @@ export function createTelegramManualThreadDisconnectHandler<
           {
             isCleanupTargetProtected,
             callApi(method, body) {
+              assertCurrent();
               return deps.callApi(method, body);
             },
             markStaleByTarget(targetToMark, syncStatus, lastSyncError) {
+              assertCurrent();
               return deps.topicTargetStore.markStaleByTarget(
                 targetToMark,
                 syncStatus,
@@ -350,15 +388,18 @@ export function createTelegramManualThreadDisconnectHandler<
               );
             },
             removeCleanupIntentById(id) {
+              assertCurrent();
               return deps.topicTargetStore.removePendingCleanup(id);
             },
             persist() {
+              assertCurrent();
               return deps.topicTargetStore.persist();
             },
             getCurrentLeaderEpoch: deps.getCurrentLeaderEpoch,
             recordRuntimeEvent: deps.recordRuntimeEvent,
           },
         );
+        assertCurrent();
         if (cleanupPlan.actions.some((action) => isCleanupTargetProtected(action.target, action))) {
           return "Thread disconnect superseded by a new binding.";
         }
@@ -378,6 +419,7 @@ export function createTelegramManualThreadDisconnectHandler<
         }) as TSyncState,
       );
     }
+    assertCurrent();
     const stopped = await deps.stopPolling();
     return cleanupPending
       ? `${stopped} Telegram thread cleanup remains pending for the next leader.`

package/lib/telegram-api.ts

@@ -38,6 +38,7 @@ function getTelegramApiTempDir(): string {
   return resolveTelegramAttachmentsDir();
 }
 const TELEGRAM_TEMP_FILE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+const TELEGRAM_DOWNLOAD_RENAME_MAX_ATTEMPTS = 6;
 const activeTelegramApiWorkspaceAdmissionOperationIds = new Set<string>();
 const TELEGRAM_INBOUND_FILE_MAX_BYTES = getTelegramInboundFileByteLimitFromEnv(
   process.env,
@@ -1106,6 +1107,25 @@ async function writeTelegramDownloadResponse(
   );
 }
 
+async function publishTelegramDownload(
+  partPath: string,
+  targetPath: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  for (let attempt = 0; ; attempt++) {
+    throwIfTelegramApiCallAborted(signal);
+    try {
+      await rename(partPath, targetPath);
+      return;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException | undefined)?.code;
+      // Windows may briefly deny replacement while another publisher/scanner holds the file.
+      if (process.platform !== "win32" || (code !== "EPERM" && code !== "EACCES") || attempt + 1 >= TELEGRAM_DOWNLOAD_RENAME_MAX_ATTEMPTS) throw error;
+      await sleepTelegramRetry(50 * 2 ** attempt, signal);
+    }
+  }
+}
+
 async function removeTelegramPartialDownload(path: string): Promise<void> {
   try {
     await unlink(path);
@@ -1693,7 +1713,7 @@ export async function downloadTelegramFile(
       partPath,
       options?.maxFileSizeBytes,
     );
-    await rename(partPath, targetPath);
+    await publishTelegramDownload(partPath, targetPath, options?.signal);
   } catch (error) {
     await removeTelegramPartialDownload(partPath);
     throw error;

package/package.json

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