pilotswarm-sdk 0.5.20 → 0.5.22

package/api/src/http-api-transport.js

@@ -150,6 +150,10 @@ export class HttpApiTransport {
         return this.api.call("setSessionModel", { sessionId, options });
     }
 
+    async regenerateSession(sessionId, options = {}) {
+        return this.api.call("regenerateSession", { sessionId, options });
+    }
+
     async stopSessionTurn(sessionId, options = {}) {
         return this.api.call("stopSessionTurn", { sessionId, options });
     }

package/api/src/protocol.js

@@ -104,6 +104,8 @@ export const OPERATIONS = [
     { name: "getSessionEvents", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/events", params: { sessionId: path("sessionId"), afterSeq: query("number"), limit: query("number"), eventTypes: query("json") }, summary: "Session events after a sequence number (reconnect catch-up). Optional eventTypes (JSON string array) narrows to those event types server-side." },
     { name: "getSessionEventsBefore", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/events-before", params: { sessionId: path("sessionId"), beforeSeq: query("number"), limit: query("number"), eventTypes: query("json") }, summary: "Older session events for history paging. Optional eventTypes (JSON string array) narrows to those event types server-side (chat transcript paging)." },
     { name: "getSessionMetricSummary", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/metric-summary", params: { sessionId: path("sessionId") }, summary: "Per-session metric summary." },
+    { name: "getSessionFootprint", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/footprint", params: { sessionId: path("sessionId") }, summary: "Session footprint: context/compaction health, event-log and snapshot sizes, and an assessment (ok/elevated/degraded) with a recommendation. Control-plane only; TTL-cached." },
+    { name: "regenerateSession", access: "session:manage", method: "POST", path: "/management/sessions/:sessionId/regenerate", params: { sessionId: path("sessionId"), options: body() }, summary: "Regenerate the session's transcript in place (epoch rebirth): archive, distill, and recreate the Copilot session at a turn boundary. Enqueue-then-observe; outcomes arrive as session.regenerate_* events." },
     { name: "getSessionTokensByModel", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/tokens-by-model", params: { sessionId: path("sessionId") }, summary: "Token totals grouped by model." },
     { name: "getSessionTreeStats", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/tree-stats", params: { sessionId: path("sessionId") }, summary: "Stats rolled up across the spawn tree." },
     { name: "getSessionSkillUsage", access: "session:read", method: "GET", path: "/management/sessions/:sessionId/skill-usage", params: { sessionId: path("sessionId"), since: query("string") }, summary: "Skill usage for one session." },

package/dist/blob-store.d.ts

@@ -28,7 +28,29 @@
  */
 import { ContainerClient, StorageSharedKeyCredential } from "@azure/storage-blob";
 import { type SnapshotCommitInput, type SnapshotCommitResult, type SnapshotHydrateResult, type SnapshotProbe, type VersionedSnapshotStore } from "./snapshot-protocol.js";
-import { type ArtifactDownloadResult, type ArtifactMetadata, type SessionStateStore, type ArtifactStore, type ArtifactUploadOptions } from "./session-store.js";
+import { type ArtifactDownloadResult, type ArtifactMetadata, type SessionStateStore, type ArtifactStore, type ArtifactUploadOptions, type SnapshotCodec } from "./session-store.js";
+/**
+ * Epoch-chain snapshot blob: `S.e<E>.tar.br`, one blob per chain. The name
+ * must NEVER end `.tar.gz` — that is the only shape shipped resource-manager
+ * purge binaries collect as delete candidates, and this name invisibility
+ * (not fail-closed parsing in new code) is what protects retained epochs
+ * from an old binary. See the key-shape invariant in snapshot-protocol.ts.
+ */
+export declare function epochSnapshotBlobName(sessionId: string, epoch: number): string;
+/**
+ * Snapshot-blob metadata for a CAS commit, written atomically with the
+ * content by single-shot Put Blob. Epoch chains additionally carry
+ * `psepoch` — the key already scopes them; the field makes listings
+ * self-describing.
+ */
+export declare function snapshotCommitBlobMetadata(args: {
+    version: number;
+    turnKey: string;
+    contentHash: string;
+    codec: SnapshotCodec;
+    rawSizeBytes: number;
+    epoch?: number;
+}): Record<string, string>;
 /**
  * Configuration for constructing a {@link SessionBlobStore} against an
  * already-built `ContainerClient`. Used by the managed-identity path
@@ -82,30 +104,39 @@ export declare class SessionBlobStore implements SessionStateStore, ArtifactStor
      * Dehydrate a session: tar, upload, remove local files.
      * Frees the worker slot for another session.
      */
-    dehydrate(sessionId: string, meta?: Record<string, unknown>): Promise<void>;
+    dehydrate(sessionId: string, meta?: Record<string, unknown>, epoch?: number): Promise<void>;
     /**
      * Hydrate a session: download tar from blob, extract to local disk.
      * No-op if local session files already exist.
      */
-    hydrate(sessionId: string): Promise<void>;
+    hydrate(sessionId: string, epoch?: number): Promise<void>;
     /**
      * Checkpoint: upload current session state to blob without removing local files.
      * Used for crash resilience — the session stays warm in memory.
      */
-    checkpoint(sessionId: string): Promise<void>;
-    getSnapshotSizeBytes(sessionId: string): Promise<number | undefined>;
+    checkpoint(sessionId: string, epoch?: number): Promise<void>;
+    /** Size-cache key: legacy family caches under the bare id, epoch chains under their blob name. */
+    private sizeCacheKey;
+    getSnapshotSizeBytes(sessionId: string, epoch?: number): Promise<number | undefined>;
     /** Check if a dehydrated session exists in blob storage. */
-    exists(sessionId: string): Promise<boolean>;
-    /** Delete a dehydrated session from blob storage. */
-    delete(sessionId: string): Promise<void>;
+    exists(sessionId: string, epoch?: number): Promise<boolean>;
+    /** Delete a dehydrated session from blob storage (epoch >= 1: only that epoch's chain). */
+    delete(sessionId: string, epoch?: number): Promise<void>;
+    /**
+     * Remove the legacy family AND every epoch chain for the session (real
+     * session deletion). Epoch objects are enumerated by prefix and deleted
+     * ONLY when the fail-closed parser accepts the name — anything else
+     * under the prefix is logged and left alone.
+     */
+    deleteAllEpochs(sessionId: string): Promise<void>;
     private static readonly COMMIT_MAX_ATTEMPTS;
     private static readonly SINGLE_SHOT_MAX_BYTES;
     private snapshotBlobName;
     private probeFromMetadata;
     private headSnapshot;
-    probeSnapshot(sessionId: string): Promise<SnapshotProbe>;
-    commitSnapshot(sessionId: string, input: SnapshotCommitInput): Promise<SnapshotCommitResult>;
-    hydrateSnapshot(sessionId: string): Promise<SnapshotHydrateResult>;
+    probeSnapshot(sessionId: string, epoch?: number): Promise<SnapshotProbe>;
+    commitSnapshot(sessionId: string, input: SnapshotCommitInput, epoch?: number): Promise<SnapshotCommitResult>;
+    hydrateSnapshot(sessionId: string, epoch?: number): Promise<SnapshotHydrateResult>;
     private artifactBlobPath;
     /**
      * Upload an artifact file (e.g. .md) to blob storage.

package/dist/blob-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blob-store.d.ts","sourceRoot":"","sources":["../src/blob-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"blob-store.d.ts","sourceRoot":"","sources":["../src/blob-store.ts"],"names":[],"mappings":"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"}

package/dist/blob-store.js

@@ -33,8 +33,34 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { faultPoint } from "./fault-injection.js";
-import { SnapshotConflictError, } from "./snapshot-protocol.js";
-import { DEFAULT_SESSION_STATE_DIR, DEFAULT_SNAPSHOT_CODEC, archiveSessionDir, buildMetadata, extractSessionArchive, isBinaryArtifactContentType, normalizeArtifactContentType, resolveArtifactFileUpload, resolveArtifactUpload, resolveSnapshotCodec, waitForSessionSnapshot, } from "./session-store.js";
+import { SnapshotConflictError, isLegacyEpoch, } from "./snapshot-protocol.js";
+import { DEFAULT_SESSION_STATE_DIR, DEFAULT_SNAPSHOT_CODEC, archiveSessionDir, buildMetadata, extractSessionArchive, isBinaryArtifactContentType, normalizeArtifactContentType, parseEpochSnapshotName, resolveArtifactFileUpload, resolveArtifactUpload, resolveSnapshotCodec, waitForSessionSnapshot, } from "./session-store.js";
+/**
+ * Epoch-chain snapshot blob: `S.e<E>.tar.br`, one blob per chain. The name
+ * must NEVER end `.tar.gz` — that is the only shape shipped resource-manager
+ * purge binaries collect as delete candidates, and this name invisibility
+ * (not fail-closed parsing in new code) is what protects retained epochs
+ * from an old binary. See the key-shape invariant in snapshot-protocol.ts.
+ */
+export function epochSnapshotBlobName(sessionId, epoch) {
+    return `${sessionId}.e${epoch}.tar.br`;
+}
+/**
+ * Snapshot-blob metadata for a CAS commit, written atomically with the
+ * content by single-shot Put Blob. Epoch chains additionally carry
+ * `psepoch` — the key already scopes them; the field makes listings
+ * self-describing.
+ */
+export function snapshotCommitBlobMetadata(args) {
+    return {
+        psver: String(args.version),
+        psturnkey: args.turnKey,
+        pssha: args.contentHash,
+        pscodec: args.codec,
+        psraw: String(args.rawSizeBytes),
+        ...(isLegacyEpoch(args.epoch) ? {} : { psepoch: String(args.epoch) }),
+    };
+}
 function formatBlobLogValue(value) {
     if (value == null)
         return "";
@@ -126,19 +152,20 @@ export class SessionBlobStore {
      * Dehydrate a session: tar, upload, remove local files.
      * Frees the worker slot for another session.
      */
-    async dehydrate(sessionId, meta) {
+    async dehydrate(sessionId, meta, epoch) {
         const sessionDir = path.join(this.sessionStateDir, sessionId);
         logBlobStore("info", sessionId, "dehydrate start", {
             container: this.containerName,
             dir: sessionDir,
             reason: meta?.reason,
+            ...(isLegacyEpoch(epoch) ? {} : { epoch }),
         });
         // Versioned-snapshot fence: the committed chain (lifecycle protocol)
         // already holds this session's durable state, and an unconditional
         // legacy Put would replace both content and the CAS metadata
         // (psver/psturnkey/pssha). Degrade to release: free local files.
         try {
-            const head = await this.headSnapshot(sessionId);
+            const head = await this.headSnapshot(sessionId, epoch);
             if (head.exists && !head.legacy) {
                 logBlobStore("warn", sessionId, "dehydrate skipped upload: versioned snapshot exists; releasing local files only", {
                     container: this.containerName,
@@ -154,6 +181,11 @@ export class SessionBlobStore {
                 error: errorMessage(probeErr),
             });
         }
+        // Epoch chains are versioned-only: the Put below writes the legacy
+        // (epoch-0) family (`S.tar.gz`) and must never run for epoch >= 1.
+        if (!isLegacyEpoch(epoch)) {
+            throw new Error(`dehydrate(${sessionId}) reached the legacy upload path with epoch ${epoch}; epoch chains commit via commitSnapshot`);
+        }
         const snapshot = await waitForSessionSnapshot(this.sessionStateDir, sessionId);
         if (!snapshot.ready) {
             logBlobStore("warn", sessionId, "dehydrate snapshot not ready", {
@@ -216,7 +248,12 @@ export class SessionBlobStore {
      * Hydrate a session: download tar from blob, extract to local disk.
      * No-op if local session files already exist.
      */
-    async hydrate(sessionId) {
+    async hydrate(sessionId, epoch) {
+        // Legacy whole-dir restore; epoch chains hydrate via hydrateSnapshot
+        // (atomic swap), so this path never sees them.
+        if (!isLegacyEpoch(epoch)) {
+            throw new Error(`hydrate(${sessionId}) is the legacy path; epoch ${epoch} chains hydrate via hydrateSnapshot`);
+        }
         const sessionDir = path.join(this.sessionStateDir, sessionId);
         logBlobStore("info", sessionId, "hydrate start", {
             container: this.containerName,
@@ -260,7 +297,7 @@ export class SessionBlobStore {
      * Checkpoint: upload current session state to blob without removing local files.
      * Used for crash resilience — the session stays warm in memory.
      */
-    async checkpoint(sessionId) {
+    async checkpoint(sessionId, epoch) {
         const sessionDir = path.join(this.sessionStateDir, sessionId);
         if (!fs.existsSync(sessionDir)) {
             logBlobStore("info", sessionId, "checkpoint skipped", {
@@ -272,7 +309,7 @@ export class SessionBlobStore {
         // Versioned-snapshot fence (see dehydrate): never clobber the
         // CAS-protected chain with an unversioned legacy write.
         try {
-            const head = await this.headSnapshot(sessionId);
+            const head = await this.headSnapshot(sessionId, epoch);
             if (head.exists && !head.legacy) {
                 logBlobStore("warn", sessionId, "checkpoint skipped: versioned snapshot exists", {
                     container: this.containerName,
@@ -287,6 +324,10 @@ export class SessionBlobStore {
                 error: errorMessage(probeErr),
             });
         }
+        // Epoch chains are versioned-only (see dehydrate).
+        if (!isLegacyEpoch(epoch)) {
+            throw new Error(`checkpoint(${sessionId}) reached the legacy upload path with epoch ${epoch}; epoch chains commit via commitSnapshot`);
+        }
         const codec = DEFAULT_SNAPSHOT_CODEC;
         const tarPath = path.join(os.tmpdir(), `${sessionId}.tar`);
         try {
@@ -324,10 +365,37 @@ export class SessionBlobStore {
             catch { }
         }
     }
-    async getSnapshotSizeBytes(sessionId) {
-        const cached = this.snapshotSizeBySession.get(sessionId);
+    /** Size-cache key: legacy family caches under the bare id, epoch chains under their blob name. */
+    sizeCacheKey(sessionId, epoch) {
+        return isLegacyEpoch(epoch) ? sessionId : epochSnapshotBlobName(sessionId, epoch);
+    }
+    async getSnapshotSizeBytes(sessionId, epoch) {
+        const cached = this.snapshotSizeBySession.get(this.sizeCacheKey(sessionId, epoch));
         if (Number.isFinite(cached))
             return cached;
+        // Epoch chains keep no meta.json mirror (key-shape invariant) — the
+        // blob's own content length is the stored size.
+        if (!isLegacyEpoch(epoch)) {
+            const blobName = epochSnapshotBlobName(sessionId, epoch);
+            try {
+                const props = await this.containerClient.getBlockBlobClient(blobName).getProperties();
+                const sizeBytes = Number(props.contentLength);
+                if (Number.isFinite(sizeBytes)) {
+                    this.snapshotSizeBySession.set(this.sizeCacheKey(sessionId, epoch), sizeBytes);
+                    return sizeBytes;
+                }
+            }
+            catch (error) {
+                if (error?.statusCode !== 404) {
+                    logBlobStore("warn", sessionId, "snapshot size read failed", {
+                        container: this.containerName,
+                        blob: blobName,
+                        error: errorMessage(error),
+                    });
+                }
+            }
+            return undefined;
+        }
         const metaBlob = this.containerClient.getBlockBlobClient(`${sessionId}.meta.json`);
         try {
             if (!(await metaBlob.exists())) {
@@ -355,13 +423,14 @@ export class SessionBlobStore {
         return undefined;
     }
     /** Check if a dehydrated session exists in blob storage. */
-    async exists(sessionId) {
-        const tarBlob = this.containerClient.getBlockBlobClient(`${sessionId}.tar.gz`);
+    async exists(sessionId, epoch) {
+        const blobName = this.snapshotBlobName(sessionId, epoch);
+        const tarBlob = this.containerClient.getBlockBlobClient(blobName);
         try {
             const exists = await tarBlob.exists();
             logBlobStore("info", sessionId, "exists probe", {
                 container: this.containerName,
-                blob: `${sessionId}.tar.gz`,
+                blob: blobName,
                 exists,
             });
             return exists;
@@ -369,22 +438,30 @@ export class SessionBlobStore {
         catch (error) {
             logBlobStore("warn", sessionId, "exists probe failed", {
                 container: this.containerName,
-                blob: `${sessionId}.tar.gz`,
+                blob: blobName,
                 error: errorMessage(error),
             });
             throw error;
         }
     }
-    /** Delete a dehydrated session from blob storage. */
-    async delete(sessionId) {
+    /** Delete a dehydrated session from blob storage (epoch >= 1: only that epoch's chain). */
+    async delete(sessionId, epoch) {
         logBlobStore("info", sessionId, "delete start", {
             container: this.containerName,
+            ...(isLegacyEpoch(epoch) ? {} : { epoch }),
         });
         try {
-            await this.containerClient.getBlockBlobClient(`${sessionId}.tar.gz`).deleteIfExists();
-            await this.containerClient.getBlockBlobClient(`${sessionId}.meta.json`).deleteIfExists();
+            if (isLegacyEpoch(epoch)) {
+                await this.containerClient.getBlockBlobClient(`${sessionId}.tar.gz`).deleteIfExists();
+                await this.containerClient.getBlockBlobClient(`${sessionId}.meta.json`).deleteIfExists();
+            }
+            else {
+                // One blob per epoch chain, no meta.json mirror — nothing else to collect.
+                await this.containerClient.getBlockBlobClient(epochSnapshotBlobName(sessionId, epoch)).deleteIfExists();
+            }
             logBlobStore("info", sessionId, "delete complete", {
                 container: this.containerName,
+                ...(isLegacyEpoch(epoch) ? {} : { epoch }),
             });
         }
         catch (error) {
@@ -395,6 +472,27 @@ export class SessionBlobStore {
             throw error;
         }
     }
+    /**
+     * Remove the legacy family AND every epoch chain for the session (real
+     * session deletion). Epoch objects are enumerated by prefix and deleted
+     * ONLY when the fail-closed parser accepts the name — anything else
+     * under the prefix is logged and left alone.
+     */
+    async deleteAllEpochs(sessionId) {
+        await this.delete(sessionId);
+        const prefix = `${sessionId}.e`;
+        for await (const blob of this.containerClient.listBlobsFlat({ prefix })) {
+            const parsed = parseEpochSnapshotName(sessionId, blob.name);
+            if (!parsed) {
+                logBlobStore("warn", sessionId, "deleteAllEpochs leaving unparseable name alone", {
+                    container: this.containerName,
+                    blob: blob.name,
+                });
+                continue;
+            }
+            await this.containerClient.getBlockBlobClient(blob.name).deleteIfExists();
+        }
+    }
     // ─── Versioned CAS contract (session-lifecycle-protocol §3.1) ───
     //
     // The version is an explicit counter in the tar blob's metadata
@@ -408,8 +506,8 @@ export class SessionBlobStore {
     // Metadata for version bumps (it would decouple counter from content).
     static COMMIT_MAX_ATTEMPTS = 5;
     static SINGLE_SHOT_MAX_BYTES = 256 * 1024 * 1024;
-    snapshotBlobName(sessionId) {
-        return `${sessionId}.tar.gz`;
+    snapshotBlobName(sessionId, epoch) {
+        return isLegacyEpoch(epoch) ? `${sessionId}.tar.gz` : epochSnapshotBlobName(sessionId, epoch);
     }
     probeFromMetadata(metadata, etag) {
         const codec = resolveSnapshotCodec(metadata?.pscodec);
@@ -428,8 +526,8 @@ export class SessionBlobStore {
             ...(etag ? { etag } : {}),
         };
     }
-    async headSnapshot(sessionId) {
-        const blob = this.containerClient.getBlockBlobClient(this.snapshotBlobName(sessionId));
+    async headSnapshot(sessionId, epoch) {
+        const blob = this.containerClient.getBlockBlobClient(this.snapshotBlobName(sessionId, epoch));
         try {
             const props = await blob.getProperties();
             return this.probeFromMetadata(props.metadata, props.etag);
@@ -440,18 +538,20 @@ export class SessionBlobStore {
             throw error;
         }
     }
-    async probeSnapshot(sessionId) {
-        const { etag: _etag, ...probe } = await this.headSnapshot(sessionId);
+    async probeSnapshot(sessionId, epoch) {
+        const { etag: _etag, ...probe } = await this.headSnapshot(sessionId, epoch);
         return probe;
     }
-    async commitSnapshot(sessionId, input) {
+    async commitSnapshot(sessionId, input, epoch) {
         const sessionDir = path.join(this.sessionStateDir, sessionId);
         const snapshot = await waitForSessionSnapshot(this.sessionStateDir, sessionId);
         if (!snapshot.ready) {
             throw new Error(`Session state directory not ready during commit: ${sessionId} (${sessionDir}). ` +
                 `Missing: ${snapshot.missing.join(", ") || "unknown"}`);
         }
-        const codec = DEFAULT_SNAPSHOT_CODEC;
+        // Epoch chains pin brotli — their names bake `.tar.br` (key-shape
+        // invariant) — rather than tracking the default.
+        const codec = isLegacyEpoch(epoch) ? DEFAULT_SNAPSHOT_CODEC : "brotli";
         const tarPath = path.join(os.tmpdir(), `ps-commit-${sessionId}-${process.pid}-${Date.now()}.tar`);
         try {
             const { rawSizeBytes } = await archiveSessionDir(this.sessionStateDir, sessionId, tarPath, codec);
@@ -462,9 +562,9 @@ export class SessionBlobStore {
                     `Audit the session workspace for files that belong in tar excludes.`);
             }
             const contentHash = crypto.createHash("sha256").update(body).digest("hex");
-            const blob = this.containerClient.getBlockBlobClient(this.snapshotBlobName(sessionId));
+            const blob = this.containerClient.getBlockBlobClient(this.snapshotBlobName(sessionId, epoch));
             for (let attempt = 1; attempt <= SessionBlobStore.COMMIT_MAX_ATTEMPTS; attempt++) {
-                const head = await this.headSnapshot(sessionId);
+                const head = await this.headSnapshot(sessionId, epoch);
                 if (head.exists && head.version === input.baseVersion + 1 && head.turnKey === input.turnKey) {
                     logBlobStore("info", sessionId, "commit already landed (idempotent retry)", {
                         version: head.version,
@@ -491,36 +591,44 @@ export class SessionBlobStore {
                 try {
                     await blob.upload(body, body.length, {
                         conditions,
-                        metadata: {
-                            psver: String(version),
-                            psturnkey: input.turnKey,
-                            pssha: contentHash,
-                            pscodec: codec,
-                            psraw: String(rawSizeBytes),
-                        },
-                    });
-                    faultPoint("store.commit.after-write");
-                    // Legacy compat: keep <sessionId>.meta.json fresh so
-                    // getSnapshotSizeBytes and older tooling keep working.
-                    // Unconditional + best-effort — it is informational only.
-                    try {
-                        const metadata = {
-                            ...buildMetadata(tarPath, sessionId, { reason: "turn-commit" }),
+                        metadata: snapshotCommitBlobMetadata({
                             version,
                             turnKey: input.turnKey,
                             contentHash,
                             codec,
                             rawSizeBytes,
-                        };
-                        this.snapshotSizeBySession.set(sessionId, metadata.sizeBytes);
-                        const metaBlob = this.containerClient.getBlockBlobClient(`${sessionId}.meta.json`);
-                        const metaJson = JSON.stringify(metadata);
-                        await metaBlob.upload(metaJson, metaJson.length);
+                            epoch,
+                        }),
+                    });
+                    faultPoint("store.commit.after-write");
+                    if (isLegacyEpoch(epoch)) {
+                        // Legacy compat: keep <sessionId>.meta.json fresh so
+                        // getSnapshotSizeBytes and older tooling keep working.
+                        // Unconditional + best-effort — it is informational only.
+                        // Epoch chains keep NO meta.json mirror: nothing
+                        // epoch-scoped may end `.meta.json` (key-shape invariant).
+                        try {
+                            const metadata = {
+                                ...buildMetadata(tarPath, sessionId, { reason: "turn-commit" }),
+                                version,
+                                turnKey: input.turnKey,
+                                contentHash,
+                                codec,
+                                rawSizeBytes,
+                            };
+                            this.snapshotSizeBySession.set(sessionId, metadata.sizeBytes);
+                            const metaBlob = this.containerClient.getBlockBlobClient(`${sessionId}.meta.json`);
+                            const metaJson = JSON.stringify(metadata);
+                            await metaBlob.upload(metaJson, metaJson.length);
+                        }
+                        catch (metaErr) {
+                            logBlobStore("warn", sessionId, "commit meta.json refresh failed (non-fatal)", {
+                                error: errorMessage(metaErr),
+                            });
+                        }
                     }
-                    catch (metaErr) {
-                        logBlobStore("warn", sessionId, "commit meta.json refresh failed (non-fatal)", {
-                            error: errorMessage(metaErr),
-                        });
+                    else {
+                        this.snapshotSizeBySession.set(this.sizeCacheKey(sessionId, epoch), body.length);
                     }
                     logBlobStore("info", sessionId, "commit complete", {
                         version,
@@ -529,6 +637,7 @@ export class SessionBlobStore {
                         rawSizeBytes,
                         codec,
                         attempt,
+                        ...(isLegacyEpoch(epoch) ? {} : { epoch }),
                     });
                     return { version, contentHash, sizeBytes: body.length, rawSizeBytes, alreadyCommitted: false };
                 }
@@ -558,9 +667,9 @@ export class SessionBlobStore {
             catch { }
         }
     }
-    async hydrateSnapshot(sessionId) {
+    async hydrateSnapshot(sessionId, epoch) {
         const sessionDir = path.join(this.sessionStateDir, sessionId);
-        const blob = this.containerClient.getBlockBlobClient(this.snapshotBlobName(sessionId));
+        const blob = this.containerClient.getBlockBlobClient(this.snapshotBlobName(sessionId, epoch));
         const tarPath = path.join(os.tmpdir(), `ps-hydrate-${sessionId}-${process.pid}-${Date.now()}.tar`);
         // One download response carries body + metadata consistently.
         let metadata;
@@ -599,6 +708,7 @@ export class SessionBlobStore {
         logBlobStore("info", sessionId, "versioned hydrate complete", {
             version: probe.version,
             legacy: probe.legacy,
+            ...(isLegacyEpoch(epoch) ? {} : { epoch }),
         });
         return {
             version: probe.version,