@granular-software/sdk 0.4.50 → 0.4.52

package/dist/cli/index.js

@@ -60,11 +60,11 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
+var __copyProps = (to, from2, except, desc) => {
+  if (from2 && typeof from2 === "object" || typeof from2 === "function") {
+    for (let key of __getOwnPropNames(from2))
       if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+        __defProp(to, key, { get: () => from2[key], enumerable: !(desc = __getOwnPropDesc(from2, key)) || desc.enumerable });
   }
   return to;
 };
@@ -7898,14 +7898,14 @@ var ApiClient = class {
   async getVersion(versionId) {
     return this.request(`/control/versions/${versionId}`);
   }
-  async triggerBuild(sandboxId, manifestId) {
+  async triggerBuild(sandboxId, manifestId, releaseKey) {
     return this.request(`/control/sandboxes/${sandboxId}/builds`, {
       method: "POST",
-      body: JSON.stringify({ manifestId })
+      body: JSON.stringify({ manifestId, releaseKey })
     });
   }
-  async createVersion(sandboxId, manifestId) {
-    return this.triggerBuild(sandboxId, manifestId);
+  async createVersion(sandboxId, manifestId, releaseKey) {
+    return this.triggerBuild(sandboxId, manifestId, releaseKey);
   }
   async listTags(sandboxId) {
     const result = await this.request(
@@ -8889,7 +8889,7 @@ createChalk({ level: stderrColor ? stderrColor.level : 0 });
 var source_default = chalk;
 
 // ../../node_modules/mimic-function/index.js
-var copyProperty = (to, from, property, ignoreNonConfigurable) => {
+var copyProperty = (to, from2, property, ignoreNonConfigurable) => {
   if (property === "length" || property === "prototype") {
     return;
   }
@@ -8897,7 +8897,7 @@ var copyProperty = (to, from, property, ignoreNonConfigurable) => {
     return;
   }
   const toDescriptor = Object.getOwnPropertyDescriptor(to, property);
-  const fromDescriptor = Object.getOwnPropertyDescriptor(from, property);
+  const fromDescriptor = Object.getOwnPropertyDescriptor(from2, property);
   if (!canCopyProperty(toDescriptor, fromDescriptor) && ignoreNonConfigurable) {
     return;
   }
@@ -8906,8 +8906,8 @@ var copyProperty = (to, from, property, ignoreNonConfigurable) => {
 var canCopyProperty = function(toDescriptor, fromDescriptor) {
   return toDescriptor === void 0 || toDescriptor.configurable || toDescriptor.writable === fromDescriptor.writable && toDescriptor.enumerable === fromDescriptor.enumerable && toDescriptor.configurable === fromDescriptor.configurable && (toDescriptor.writable || toDescriptor.value === fromDescriptor.value);
 };
-var changePrototype = (to, from) => {
-  const fromPrototype = Object.getPrototypeOf(from);
+var changePrototype = (to, from2) => {
+  const fromPrototype = Object.getPrototypeOf(from2);
   if (fromPrototype === Object.getPrototypeOf(to)) {
     return;
   }
@@ -8917,20 +8917,20 @@ var wrappedToString = (withName, fromBody) => `/* Wrapped ${withName}*/
 ${fromBody}`;
 var toStringDescriptor = Object.getOwnPropertyDescriptor(Function.prototype, "toString");
 var toStringName = Object.getOwnPropertyDescriptor(Function.prototype.toString, "name");
-var changeToString = (to, from, name) => {
+var changeToString = (to, from2, name) => {
   const withName = name === "" ? "" : `with ${name.trim()}() `;
-  const newToString = wrappedToString.bind(null, withName, from.toString());
+  const newToString = wrappedToString.bind(null, withName, from2.toString());
   Object.defineProperty(newToString, "name", toStringName);
   const { writable, enumerable, configurable } = toStringDescriptor;
   Object.defineProperty(to, "toString", { value: newToString, writable, enumerable, configurable });
 };
-function mimicFunction(to, from, { ignoreNonConfigurable = false } = {}) {
+function mimicFunction(to, from2, { ignoreNonConfigurable = false } = {}) {
   const { name } = to;
-  for (const property of Reflect.ownKeys(from)) {
-    copyProperty(to, from, property, ignoreNonConfigurable);
+  for (const property of Reflect.ownKeys(from2)) {
+    copyProperty(to, from2, property, ignoreNonConfigurable);
   }
-  changePrototype(to, from);
-  changeToString(to, from, name);
+  changePrototype(to, from2);
+  changeToString(to, from2, name);
   return to;
 }
 
@@ -15624,11 +15624,20 @@ function buildStateMachineModelMutations(modelPath, machines) {
   return mutations;
 }
 function buildMachineTypes(classSummary, machine) {
+  const stateGlossary = machine.states.map((state) => {
+    const label = state.label && state.label !== state.name ? state.label : null;
+    const meaning = [label, state.description].filter(Boolean).join(" \u2014 ");
+    const finalMarker = state.isFinal ? " Final state." : "";
+    return `${state.name}${meaning ? `: ${meaning}` : "."}${finalMarker}`;
+  });
   return [
     {
       kind: "union",
       name: stateTypeName(classSummary.name, machine.name),
-      docs: [`Allowed states for ${classSummary.name}.${machine.name}.`],
+      docs: [
+        `Allowed states for ${classSummary.name}.${machine.name}.`,
+        ...stateGlossary
+      ],
       members: machine.states.map((state) => state.name)
     },
     {
@@ -15976,7 +15985,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
           },
           add_transition: async (value, {
             name,
-            from,
+            from: from2,
             to,
             label,
             description,
@@ -15991,7 +16000,7 @@ var stateMachineMetamodelPackage = defineMetamodelPackage({
               value.target.add_state_machine_transition(
                 value.name,
                 name,
-                from,
+                from2,
                 to,
                 {
                   label,
@@ -16814,7 +16823,7 @@ ${effectMetamodelTable}
 | \`enqueueRecordImport\`, \`listRecordImports\`, \`getRecordImport\`, \`getRecordImportSummary\`, \u2026 | **Async** bulk import (worker queue + aggregate progress). Prefer when loads are huge, returning an \`importId\` is enough up front, and background processing is acceptable. |
 | \`graphql(query, variables?)\` | **GraphQL** \u2014 see dedicated subsection below. |
 | \`defineRelationship\`, \`getRelationships\`, \`attach\`, \`detach\`, \`listRelated\` | Imperative relationship operations (same ideas as manifest \`defineRelationship\`). |
-| \`sessions.list()\`, \`sessions.create()\`, \`sessions.connect()\`, \`sessions.reopen()\`, \`sessions.close()\` | Session lifecycle for this environment. |
+| \`sessions.list({ status?, sessionScope?, limit?, offset? })\`, \`sessions.create({ sessionScope? })\`, \`sessions.connect()\`, \`sessions.reopen()\`, \`sessions.close()\` | Scoped, bounded session history and lifecycle for this environment. |
 
 ### \`Session\` (live runtime connection)
 
@@ -16862,7 +16871,7 @@ Use \`environment.graphql(query, variables?)\` when you need **query/mutation ac
 | \`granular simulate\` | Open simulator in browser. |
 | \`granular simulate --print-url\` | Print a deep-linkable simulator URL without opening the browser. |
 | \`granular connect test --json\` | Verify auth and environment connectivity with a real session. |
-| \`granular session create/list/heap/doc --json\` | Create, enumerate, and inspect real session state. |
+| \`granular session create/list/heap/doc --json\` | Create, enumerate, and inspect real session state. \`session list\` defaults to 25 rows; use \`--session-scope\`, \`--subject-id\`, \`--limit\`, and \`--offset\` for deterministic paging. |
 | \`granular graphql --query '...' --json\` | Run a GraphQL query or mutation against the live graph. |
 | \`granular effects list/diff --json\` | Inspect declared versus live ready effects. |
 | \`granular job run --file ./job.ts --json\` | Execute a real runtime job from the terminal or CI. |
@@ -17542,8 +17551,8 @@ Use this for command execution, environment setup, and shipping flows.
 | \`granular graphql --query '...' --json\` | Query the live graph through the environment GraphQL API |
 | \`granular effects list --json\` | Inspect declared and live effects for an environment |
 | \`granular effects diff --json\` | Compare declared effects to live ready handlers |
-| \`granular session create --json\` | Create a fresh session for an environment |
-| \`granular session list --json\` | List indexed sessions for an environment |
+| \`granular session create --session-scope <scope> --json\` | Create a fresh, application-scoped session for an environment |
+| \`granular session list --session-scope <scope> --limit 25 --offset 0 --json\` | List one bounded page of indexed sessions |
 | \`granular session heap --json\` | Inspect session heap |
 | \`granular session doc --json\` | Inspect the Automerge-backed session document |
 | \`granular job run --file ./job.ts\` | Execute a real job against the ontology runtime |
@@ -17626,8 +17635,8 @@ Use this for runtime debugging after the ontology builds but behavior does not m
 
 | Goal | Preferred path |
 | --- | --- |
-| Create or rotate a session | \`granular session create --json\` |
-| List known sessions | \`granular session list --json\` |
+| Create or rotate a session | \`granular session create --session-scope <scope> --json\` |
+| List known sessions | \`granular session list --session-scope <scope> --limit 25 --offset 0 --json\` |
 | Inspect heap | \`granular session heap --json\` |
 | Inspect full document | \`granular session doc --json\` |
 | Verify connectivity | \`granular connect test\` |
@@ -18938,7 +18947,7 @@ async function deployCommand(options = {}) {
     ]);
     const devTag = tags.find((tag2) => tag2.name === "dev");
     const prodTag = tags.find((tag2) => tag2.name === "prod");
-    const existingVersion = versions.find(
+    const existingVersion = options.releaseKey ? null : versions.find(
       (version2) => version2.manifestDigest === uploadedManifest.digest
     ) || null;
     const existingVersionId = existingVersion?.buildId || null;
@@ -18956,19 +18965,27 @@ async function deployCommand(options = {}) {
     } else {
       const version2 = await api.createVersion(
         config.sandboxId,
-        uploadedManifest.manifestId
-      );
-      const startTime = Date.now();
-      building.text = `  Running build for version... ${brand.muted(version2.buildId)}`;
-      completed = await api.waitForVersionBuild(version2.buildId, (status) => {
-        const elapsed = Math.round((Date.now() - startTime) / 1e3);
-        building.text = `  Running build for version... ${brand.muted(`${status} (${elapsed}s)`)}`;
-      });
-      totalTime = Math.round((Date.now() - startTime) / 1e3);
-      deployedToDev = true;
-      building.succeed(
-        `  Dev now points to ${brand.secondary(completed.buildId)} (${totalTime}s)`
+        uploadedManifest.manifestId,
+        options.releaseKey
       );
+      if (version2.createdNewVersion === false && version2.status === "completed") {
+        completed = version2;
+        building.succeed(
+          `  Reused ${brand.secondary(version2.buildId)}; the release key is unchanged.`
+        );
+      } else {
+        const startTime = Date.now();
+        building.text = `  Running build for version... ${brand.muted(version2.buildId)}`;
+        completed = await api.waitForVersionBuild(version2.buildId, (status) => {
+          const elapsed = Math.round((Date.now() - startTime) / 1e3);
+          building.text = `  Running build for version... ${brand.muted(`${status} (${elapsed}s)`)}`;
+        });
+        totalTime = Math.round((Date.now() - startTime) / 1e3);
+        deployedToDev = true;
+        building.succeed(
+          `  Dev now points to ${brand.secondary(completed.buildId)} (${totalTime}s)`
+        );
+      }
     }
     if (!completed) {
       throw new Error("Could not resolve the current ontology version.");
@@ -18999,6 +19016,7 @@ async function deployCommand(options = {}) {
       Release: options.prod ? deployedToDev ? "dev and prod now point to this version" : "prod promoted to the version already on dev" : "dev updated to this version",
       "Agent doc": "GRANULAR_SANDBOX.md"
     });
+    console.log(`GRANULAR_RELEASE_CHANGED=${deployedToDev ? "true" : "false"}`);
     console.log();
     if (options.prod) {
       info(
@@ -19560,16 +19578,37 @@ var WSClient = class {
   tokenRefreshTimer = null;
   isExplicitlyDisconnected = false;
   reconnectAttempts = 0;
+  connectPromise = null;
+  connectionEpoch = 0;
+  cancelConnectAttempt = null;
   options;
   constructor(options) {
     this.options = options;
     this.url = options.url;
     this.sessionId = options.sessionId;
     this.token = options.token;
+    if (options.initialDocumentSnapshot) {
+      this.seedDocumentSnapshot(options.initialDocumentSnapshot);
+    }
   }
   get currentSessionId() {
     return this.sessionId;
   }
+  seedDocumentSnapshot(document) {
+    if (!document || typeof document !== "object" || Array.isArray(document)) {
+      return;
+    }
+    try {
+      this.doc = document instanceof Uint8Array ? Automerge__namespace.load(document) : Automerge__namespace.from(document);
+      this.syncState = Automerge__namespace.initSyncState();
+      this.emit("sync", this.doc);
+    } catch (error2) {
+      console.warn("[Granular] Failed to seed cached session document", error2);
+    }
+  }
+  saveDocumentSnapshot() {
+    return Automerge__namespace.save(this.doc);
+  }
   clearTokenRefreshTimer() {
     if (this.tokenRefreshTimer) {
       clearTimeout(this.tokenRefreshTimer);
@@ -19679,8 +19718,23 @@ var WSClient = class {
    * Connect to the WebSocket server
    * @returns {Promise<void>} Resolves when connection is open
    */
-  async connect() {
+  async connect(options = {}) {
+    if (this.ws?.readyState === READY_STATE_OPEN) return;
+    if (this.connectPromise) return this.connectPromise;
+    const connectPromise = this.connectAttempt(options.signal);
+    this.connectPromise = connectPromise;
+    try {
+      await connectPromise;
+    } finally {
+      if (this.connectPromise === connectPromise) {
+        this.connectPromise = null;
+      }
+    }
+  }
+  async connectAttempt(signal) {
+    if (signal?.aborted) throw new Error("WebSocket connect aborted");
     const token = await this.resolveTokenForConnect();
+    if (signal?.aborted) throw new Error("WebSocket connect aborted");
     this.isExplicitlyDisconnected = false;
     this.scheduleTokenRefresh();
     if (this.reconnectTimer) {
@@ -19692,7 +19746,7 @@ var WSClient = class {
       try {
         const wsModule = await import('ws');
         WebSocketClass = wsModule.default || wsModule;
-      } catch (e) {
+      } catch {
       }
     }
     if (!WebSocketClass) {
@@ -19700,83 +19754,97 @@ var WSClient = class {
         'No WebSocket implementation found. If using Node.js, please install "ws" and pass the constructor to the SDK options: { WebSocketCtor: WebSocket }.'
       );
     }
+    const epoch = ++this.connectionEpoch;
+    const wsUrl = new URL(this.url);
+    wsUrl.searchParams.set("sessionId", this.sessionId);
+    wsUrl.searchParams.set("token", token);
+    const socket = new WebSocketClass(wsUrl.toString());
+    this.ws = socket;
     return new Promise((resolve2, reject) => {
-      try {
-        const wsUrl = new URL(this.url);
-        wsUrl.searchParams.set("sessionId", this.sessionId);
-        wsUrl.searchParams.set("token", token);
-        this.ws = new WebSocketClass(wsUrl.toString());
-        if (!this.ws) throw new Error("Failed to create WebSocket");
-        const socket = this.ws;
-        if (typeof socket.on === "function") {
-          socket.on("open", () => {
-            if (this.reconnectTimer) {
-              clearTimeout(this.reconnectTimer);
-              this.reconnectTimer = null;
-            }
-            this.reconnectAttempts = 0;
-            this.emit("open", {});
-            resolve2();
-          });
-          socket.on("message", (data) => {
-            try {
-              const message = JSON.parse(data.toString());
-              this.handleMessage(message);
-            } catch (error2) {
-              console.error("[Granular] Failed to parse message:", error2);
-            }
-          });
-          socket.on("error", (error2) => {
-            this.emit("error", error2);
-            if (socket.readyState !== READY_STATE_OPEN) {
-              reject(error2);
-            }
-          });
-          socket.on("close", (code, reason) => {
-            this.handleDisconnect({
-              code,
-              reason: this.normalizeReason(reason),
-              // ws does not provide wasClean on Node-style close callback
-              wasClean: code === 1e3
-            });
-          });
+      let settled = false;
+      const isCurrent = () => this.connectionEpoch === epoch && this.ws === socket;
+      const finish = (error2) => {
+        if (settled) return;
+        settled = true;
+        if (this.cancelConnectAttempt === handleAbort) {
+          this.cancelConnectAttempt = null;
+        }
+        signal?.removeEventListener("abort", handleAbort);
+        if (error2) {
+          reject(error2 instanceof Error ? error2 : new Error(String(error2)));
         } else {
-          this.ws.onopen = () => {
-            if (this.reconnectTimer) {
-              clearTimeout(this.reconnectTimer);
-              this.reconnectTimer = null;
-            }
-            this.reconnectAttempts = 0;
-            this.emit("open", {});
-            resolve2();
-          };
-          this.ws.onmessage = (event) => {
-            try {
-              const data = event.data;
-              const message = JSON.parse(data.toString());
-              this.handleMessage(message);
-            } catch (error2) {
-              console.error("[Granular] Failed to parse message:", error2);
-            }
-          };
-          this.ws.onerror = (event) => {
-            const error2 = new Error("WebSocket error");
-            error2.event = event;
-            this.emit("error", error2);
-            if (this.ws?.readyState !== READY_STATE_OPEN) {
-              reject(error2);
-            }
-          };
-          this.ws.onclose = (event) => {
-            this.handleDisconnect({
-              code: event.code,
-              reason: event.reason,
-              wasClean: event.wasClean
-            });
-          };
+          resolve2();
         }
-      } catch (error2) {
-        reject(error2);
+      };
+      const closeStaleSocket = () => {
+        try {
+          socket.close(1e3, "Stale connection attempt");
+        } catch {
+        }
+      };
+      const handleAbort = () => {
+        if (isCurrent()) {
+          this.connectionEpoch += 1;
+          this.ws = null;
+        }
+        closeStaleSocket();
+        finish(new Error("WebSocket connect aborted"));
+      };
+      this.cancelConnectAttempt = handleAbort;
+      const handleOpen = () => {
+        if (!isCurrent()) {
+          closeStaleSocket();
+          return;
+        }
+        this.reconnectAttempts = 0;
+        this.emit("open", {});
+        finish();
+      };
+      const handleMessage = (data) => {
+        if (!isCurrent()) return;
+        try {
+          const text = typeof data === "string" ? data : data && typeof data === "object" && "toString" in data ? String(data.toString()) : "";
+          this.handleMessage(JSON.parse(text));
+        } catch (error2) {
+          console.error("[Granular] Failed to parse message:", error2);
+        }
+      };
+      const handleError = (error2) => {
+        if (!isCurrent()) return;
+        const typedError = error2 instanceof Error ? error2 : new Error("WebSocket error");
+        this.emit("error", typedError);
+        if (socket.readyState !== READY_STATE_OPEN) finish(typedError);
+      };
+      const handleClose = (close) => {
+        if (!isCurrent()) return;
+        if (!settled) {
+          finish(
+            new Error(
+              `WebSocket closed before ready${close.code ? ` (code=${close.code})` : ""}`
+            )
+          );
+        }
+        this.handleDisconnect({
+          code: close.code,
+          reason: this.normalizeReason(close.reason),
+          wasClean: close.wasClean
+        });
+      };
+      signal?.addEventListener("abort", handleAbort, { once: true });
+      const nodeSocket = socket;
+      if (typeof nodeSocket.on === "function") {
+        nodeSocket.on("open", handleOpen);
+        nodeSocket.on("message", handleMessage);
+        nodeSocket.on("error", handleError);
+        nodeSocket.on(
+          "close",
+          (code, reason) => handleClose({ code, reason, wasClean: code === 1e3 })
+        );
+      } else {
+        socket.onopen = handleOpen;
+        socket.onmessage = (event) => handleMessage(event.data);
+        socket.onerror = handleError;
+        socket.onclose = (event) => handleClose(event);
       }
     });
   }
@@ -19794,9 +19862,58 @@ var WSClient = class {
     return void 0;
   }
   rejectPending(error2) {
-    this.messageQueue.forEach((pending) => pending.reject(error2));
+    this.messageQueue.forEach((pending) => {
+      clearTimeout(pending.timeout);
+      pending.reject(error2);
+    });
     this.messageQueue = [];
   }
+  emitReconnectErrorMessage(error2) {
+    const reconnectInfo = {
+      error: error2,
+      sessionId: this.sessionId,
+      timestamp: Date.now()
+    };
+    this.emit("reconnect_error", reconnectInfo);
+    if (this.options.onReconnectError) {
+      try {
+        this.options.onReconnectError(reconnectInfo);
+      } catch (callbackError) {
+        console.error(
+          "[Granular] onReconnectError callback failed:",
+          callbackError
+        );
+      }
+    }
+  }
+  scheduleReconnectAttempt() {
+    if (this.isExplicitlyDisconnected || this.reconnectTimer) return null;
+    const baseReconnectDelayMs = typeof this.options.reconnectDelayMs === "number" && Number.isFinite(this.options.reconnectDelayMs) && this.options.reconnectDelayMs > 0 ? this.options.reconnectDelayMs : DEFAULT_RECONNECT_DELAY_MS;
+    const maxReconnectAttempts = typeof this.options.maxReconnectAttempts === "number" && Number.isFinite(this.options.maxReconnectAttempts) && this.options.maxReconnectAttempts >= 0 ? Math.floor(this.options.maxReconnectAttempts) : DEFAULT_MAX_RECONNECT_ATTEMPTS;
+    if (this.reconnectAttempts >= maxReconnectAttempts) {
+      this.emitReconnectErrorMessage(
+        `WebSocket reconnect attempts exhausted after ${maxReconnectAttempts} attempt(s).`
+      );
+      return null;
+    }
+    this.reconnectAttempts += 1;
+    const reconnectDelayMs = Math.min(
+      3e4,
+      baseReconnectDelayMs * 2 ** Math.max(0, this.reconnectAttempts - 1)
+    );
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      console.log("[Granular] Attempting reconnect...");
+      this.connect().catch((error2) => {
+        console.error("[Granular] Reconnect failed:", error2);
+        this.emitReconnectErrorMessage(
+          error2 instanceof Error ? error2.message : String(error2)
+        );
+        this.scheduleReconnectAttempt();
+      });
+    }, reconnectDelayMs);
+    return reconnectDelayMs;
+  }
   buildDisconnectError(info2) {
     const details = [
       info2.code !== void 0 ? `code=${info2.code}` : void 0,
@@ -19806,8 +19923,6 @@ var WSClient = class {
     return new Error(`WebSocket disconnected${suffix}`);
   }
   handleDisconnect(close = {}) {
-    const baseReconnectDelayMs = typeof this.options.reconnectDelayMs === "number" && Number.isFinite(this.options.reconnectDelayMs) && this.options.reconnectDelayMs > 0 ? this.options.reconnectDelayMs : DEFAULT_RECONNECT_DELAY_MS;
-    const maxReconnectAttempts = typeof this.options.maxReconnectAttempts === "number" && Number.isFinite(this.options.maxReconnectAttempts) && this.options.maxReconnectAttempts >= 0 ? Math.floor(this.options.maxReconnectAttempts) : DEFAULT_MAX_RECONNECT_ATTEMPTS;
     const unexpected = !this.isExplicitlyDisconnected;
     const info2 = {
       code: close.code,
@@ -19827,32 +19942,9 @@ var WSClient = class {
       const disconnectError = this.buildDisconnectError(info2);
       this.rejectPending(disconnectError);
       this.emit("disconnect", info2);
-      if (this.reconnectAttempts >= maxReconnectAttempts) {
-        const reconnectInfo = {
-          error: `WebSocket reconnect attempts exhausted after ${maxReconnectAttempts} attempt(s).`,
-          sessionId: this.sessionId,
-          timestamp: Date.now()
-        };
-        this.emit("reconnect_error", reconnectInfo);
-        if (this.options.onReconnectError) {
-          try {
-            this.options.onReconnectError(reconnectInfo);
-          } catch (callbackError) {
-            console.error(
-              "[Granular] onReconnectError callback failed:",
-              callbackError
-            );
-          }
-        }
-        return;
-      }
-      this.reconnectAttempts += 1;
-      const reconnectDelayMs = Math.min(
-        3e4,
-        baseReconnectDelayMs * 2 ** Math.max(0, this.reconnectAttempts - 1)
-      );
-      info2.reconnectScheduled = true;
-      info2.reconnectDelayMs = reconnectDelayMs;
+      const reconnectDelayMs = this.scheduleReconnectAttempt();
+      info2.reconnectScheduled = reconnectDelayMs !== null;
+      if (reconnectDelayMs !== null) info2.reconnectDelayMs = reconnectDelayMs;
       if (this.options.onUnexpectedClose) {
         try {
           this.options.onUnexpectedClose(info2);
@@ -19863,28 +19955,6 @@ var WSClient = class {
           );
         }
       }
-      this.reconnectTimer = setTimeout(() => {
-        console.log("[Granular] Attempting reconnect...");
-        this.connect().catch((error2) => {
-          console.error("[Granular] Reconnect failed:", error2);
-          const reconnectInfo = {
-            error: error2 instanceof Error ? error2.message : String(error2),
-            sessionId: this.sessionId,
-            timestamp: Date.now()
-          };
-          this.emit("reconnect_error", reconnectInfo);
-          if (this.options.onReconnectError) {
-            try {
-              this.options.onReconnectError(reconnectInfo);
-            } catch (callbackError) {
-              console.error(
-                "[Granular] onReconnectError callback failed:",
-                callbackError
-              );
-            }
-          }
-        });
-      }, reconnectDelayMs);
     }
   }
   handleMessage(message) {
@@ -19995,6 +20065,7 @@ var WSClient = class {
       const response = message;
       const pending = this.messageQueue.find((q) => q.id === response.id);
       if (pending) {
+        clearTimeout(pending.timeout);
         if (response.type === "rpc_error") {
           pending.reject(
             new Error(
@@ -20040,16 +20111,22 @@ var WSClient = class {
       id
     };
     return new Promise((resolve2, reject) => {
-      this.messageQueue.push({ resolve: resolve2, reject, id });
-      this.ws.send(JSON.stringify(request));
       const timeoutMs = rpcTimeoutMsForMethod(method);
-      setTimeout(() => {
+      const timeout = setTimeout(() => {
         const pending = this.messageQueue.find((q) => q.id === id);
         if (pending) {
           this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
           reject(new Error(`RPC timeout: ${method}`));
         }
       }, timeoutMs);
+      this.messageQueue.push({ resolve: resolve2, reject, id, timeout });
+      try {
+        this.ws.send(JSON.stringify(request));
+      } catch (error2) {
+        clearTimeout(timeout);
+        this.messageQueue = this.messageQueue.filter((q) => q.id !== id);
+        reject(error2 instanceof Error ? error2 : new Error(String(error2)));
+      }
     });
   }
   async handleIncomingRpc(request) {
@@ -20135,15 +20212,18 @@ var WSClient = class {
   /**
    * Disconnect the WebSocket and clear state
    */
-  disconnect() {
+  disconnect(options = {}) {
     this.isExplicitlyDisconnected = true;
+    this.cancelConnectAttempt?.();
+    this.cancelConnectAttempt = null;
+    this.connectionEpoch += 1;
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
     this.clearTokenRefreshTimer();
     if (this.ws) {
-      this.ws.close(1e3, "Client disconnect");
+      this.ws.close(1e3, options.reason || "Client disconnect");
       this.ws = null;
     }
     this.rejectPending(new Error("Client explicitly disconnected"));
@@ -20239,8 +20319,12 @@ function normalizePrompt(rawValue) {
   const source = promptRecord || raw;
   const id = typeof source.id === "string" ? source.id : typeof raw.id === "string" ? raw.id : typeof raw.promptId === "string" ? raw.promptId : "";
   if (!id) return null;
+  const jobId = typeof source.jobId === "string" && source.jobId.trim() ? source.jobId.trim() : typeof raw.jobId === "string" && raw.jobId.trim() ? raw.jobId.trim() : void 0;
+  const turnId = typeof source.turnId === "string" && source.turnId.trim() ? source.turnId.trim() : typeof raw.turnId === "string" && raw.turnId.trim() ? raw.turnId.trim() : void 0;
   return {
     id,
+    ...jobId ? { jobId } : {},
+    ...turnId ? { turnId } : {},
     type: normalizePromptType(source === raw ? raw : { ...raw, ...source }),
     title: typeof source.title === "string" ? source.title : "Input required",
     message: typeof source.message === "string" ? source.message : "",
@@ -20327,6 +20411,9 @@ var Session = class {
     this.initialQuota = options.initialQuota || null;
     this.setupEventHandlers();
     this.setupToolInvokeHandler();
+    this.currentDomainRevision = this.extractDomainRevisionFromDoc(
+      this.client.doc
+    );
   }
   extractDomainRevisionFromDoc(doc) {
     const domain = doc?.domain;
@@ -21232,6 +21319,7 @@ function normalizeJobAgentMessageEnvelope(data) {
   }
   return {
     jobId: d.jobId,
+    ...typeof d.turnId === "string" && d.turnId.trim() ? { turnId: d.turnId.trim() } : {},
     message: {
       messageId: d.messageId,
       kind: d.kind === "artifacts" ? "artifacts" : "text",
@@ -21890,9 +21978,14 @@ function normalizeShowRefs(value) {
     variableNames: normalizeRefs(record.variableNames),
     fileIds: normalizeRefs(record.fileIds),
     sessionArtifactIds: normalizeRefs(record.sessionArtifactIds),
-    actionSuggestions: normalizeActionSuggestions(record.actionSuggestions)
+    actionSuggestions: normalizeActionSuggestions(record.actionSuggestions),
+    tables: Array.isArray(record.tables) ? record.tables.filter(
+      (table2) => Boolean(
+        table2 && typeof table2 === "object" && !Array.isArray(table2) && Array.isArray(table2.columns) && Array.isArray(table2.rows)
+      )
+    ) : void 0
   };
-  return show.entryPaths || show.listNames || show.variableNames || show.fileIds || show.sessionArtifactIds || show.actionSuggestions ? show : void 0;
+  return show.entryPaths || show.listNames || show.variableNames || show.fileIds || show.sessionArtifactIds || show.actionSuggestions || show.tables ? show : void 0;
 }
 function normalizeActionSuggestions(value) {
   if (!Array.isArray(value)) return void 0;
@@ -21914,6 +22007,76 @@ function normalizeActionSuggestions(value) {
   }
   return suggestions.length ? suggestions : void 0;
 }
+var TRANSCRIPT_MESSAGE_PART_LIMIT = 128;
+var TRANSCRIPT_MESSAGE_PART_TEXT_LIMIT = 2e5;
+var TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT = 1e3;
+var TRANSCRIPT_MESSAGE_ACTION_LIMIT = 64;
+function normalizeConversationMessageActions(value) {
+  if (!Array.isArray(value) || value.length === 0) return void 0;
+  const actions = [];
+  for (const item of value.slice(0, TRANSCRIPT_MESSAGE_ACTION_LIMIT)) {
+    const record = asRecord3(item);
+    const kind = record?.kind;
+    const label = trimString(record?.label ?? record?.title);
+    const status = record?.status;
+    if (kind !== "frontend" && kind !== "backend" && kind !== "system" || !label || label.length > TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT) {
+      continue;
+    }
+    actions.push({
+      kind,
+      label,
+      ...status === "done" || status === "queued" || status === "failed" ? { status } : {}
+    });
+  }
+  return actions.length ? actions : void 0;
+}
+function normalizeConversationMessageParts(value, canonicalContent, canonicalActions) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > TRANSCRIPT_MESSAGE_PART_LIMIT) {
+    return void 0;
+  }
+  const parts = [];
+  const canonicalActionsById = new Map(
+    (canonicalActions || []).map((action) => [
+      `${action.kind}:${action.label}`,
+      action
+    ])
+  );
+  const seenActionIds = /* @__PURE__ */ new Set();
+  let textLength = 0;
+  for (const item of value) {
+    const record = asRecord3(item);
+    if (!record) return void 0;
+    if (record.type === "text") {
+      if (typeof record.text !== "string" || record.text.length === 0) {
+        return void 0;
+      }
+      textLength += record.text.length;
+      if (textLength > TRANSCRIPT_MESSAGE_PART_TEXT_LIMIT) return void 0;
+      parts.push({ type: "text", text: record.text });
+      continue;
+    }
+    if (record.type !== "action") return void 0;
+    const action = asRecord3(record.action);
+    const kind = action?.kind;
+    const label = trimString(action?.label);
+    if (kind !== "frontend" && kind !== "backend" && kind !== "system" || !label || label.length > TRANSCRIPT_MESSAGE_PART_ACTION_LABEL_LIMIT) {
+      return void 0;
+    }
+    const actionId = `${kind}:${label}`;
+    const canonicalAction = canonicalActionsById.get(actionId);
+    if (!canonicalAction) return void 0;
+    if (seenActionIds.has(actionId)) continue;
+    seenActionIds.add(actionId);
+    parts.push({
+      type: "action",
+      action: canonicalAction
+    });
+  }
+  const orderedText = parts.filter(
+    (part) => part.type === "text"
+  ).map((part) => part.text).join("");
+  return orderedText === canonicalContent ? parts : void 0;
+}
 function stringifyTranscriptValue(value, fallback2 = "") {
   if (typeof value === "string") {
     return value.trim() || fallback2;
@@ -22072,10 +22235,12 @@ function normalizeConversationMessage(raw, artifactsById) {
   const content = trimString(
     record.content ?? record.reply ?? record.message ?? record.text
   );
+  const actions = role === "assistant" ? normalizeConversationMessageActions(record.actions) : void 0;
+  const parts = role === "assistant" ? normalizeConversationMessageParts(record.parts, content, actions) : void 0;
   const show = normalizeShowRefs(record.show);
   const id = asString(record.id) || crypto.randomUUID();
   const timestamp = asNumber(record.timestamp) || asNumber(record.ts) || 0;
-  if (!content && !show) return null;
+  if (!content && !show && !actions?.length) return null;
   const artifactHistory = buildArtifactHistory(show, artifactsById);
   const historyContent = role === "assistant" ? content && artifactHistory ? `[Assistant reply]
 ${content}
@@ -22090,6 +22255,8 @@ ${content}` : artifactHistory : void 0;
     jobId: asString(record.jobId),
     promptId: asString(record.promptId),
     show,
+    actions,
+    parts,
     historyContent,
     source: "conversation"
   };
@@ -22738,7 +22905,12 @@ async function recordOpenAIUsageSpend(options) {
   const metadata = {
     ...options.metadata || {},
     ...options.usage.rawUsage !== void 0 ? { openaiUsage: options.usage.rawUsage } : {},
-    usageContext: context
+    usageContext: context,
+    pricingContextTier: options.usage.pricingContextTier,
+    cacheWritePricePerMillionMicros: options.usage.cacheWritePricePerMillionMicros,
+    cacheWriteTokens: options.usage.cacheWriteTokens,
+    cacheWriteCostMicros: options.usage.cacheWriteCostMicros,
+    longContextThresholdTokens: options.usage.longContextThresholdTokens
   };
   const response = await fetch(
     `${toGranularHttpBase(options.apiUrl)}/control/spend/events`,
@@ -22809,6 +22981,18 @@ function buildEffectMetamodelMutations(toolPath, spec) {
 }
 
 // src/client.ts
+var DEFAULT_CONVERSATION_SESSION_LIST_LIMIT = 100;
+var MAX_CONVERSATION_SESSION_LIST_LIMIT = 500;
+var MAX_CONVERSATION_SESSION_LIST_OFFSET = 1e5;
+function boundedSessionListInteger(value, name, fallback2, minimum, maximum) {
+  if (value === void 0) return fallback2;
+  if (!Number.isInteger(value) || value < minimum || value > maximum) {
+    throw new RangeError(
+      `Session list ${name} must be an integer between ${minimum} and ${maximum}.`
+    );
+  }
+  return value;
+}
 var STANDARD_MODULES_OPERATIONS = [
   {
     create: "entity",
@@ -23026,7 +23210,8 @@ function normalizeEnvironmentSetupSummary(setup) {
     environmentId: String(setup.environmentId || ""),
     sandboxId: String(setup.sandboxId || ""),
     subjectId: String(setup.subjectId || ""),
-    triggerReason: setup.triggerReason === "fresh_after_version_update" ? "fresh_after_version_update" : "new_environment",
+    triggerReason: setup.triggerReason === "fresh_after_version_update" ? "fresh_after_version_update" : setup.triggerReason === "explicit_reset" ? "explicit_reset" : "new_environment",
+    operationKey: typeof setup.operationKey === "string" ? setup.operationKey : null,
     lifecycleStatus: setup.lifecycleStatus === "completed" || setup.lifecycleStatus === "failed" ? setup.lifecycleStatus : "running",
     stage: typeof setup.stage === "string" ? setup.stage : null,
     totalObjectsToImport: Number(setup.totalObjectsToImport || 0),
@@ -23147,7 +23332,7 @@ var Environment = class _Environment {
   }
   get sessions() {
     return {
-      list: async (options) => this.listSessions(options?.status || "active"),
+      list: async (options = {}) => this.listSessions(options),
       create: async (options) => this.createSession(options),
       connect: async (sessionId, options) => this.connectSession(sessionId, options),
       reopen: async (sessionId, options) => this.reopenSession(sessionId, options),
@@ -23282,17 +23467,12 @@ var Environment = class _Environment {
    */
   async disconnect() {
   }
-  async listSessions(status = "active") {
-    if (status === "all") {
-      const [active, closed] = await Promise.all([
-        this.granular.listOpenSessions({ environmentId: this.environmentId }),
-        this.granular.listClosedSessions({ environmentId: this.environmentId })
-      ]);
-      return [...active, ...closed].sort(
-        (left, right) => Date.parse(right.lastSeenAt) - Date.parse(left.lastSeenAt)
-      );
-    }
-    return status === "closed" ? this.granular.listClosedSessions({ environmentId: this.environmentId }) : this.granular.listOpenSessions({ environmentId: this.environmentId });
+  async listSessions(optionsOrStatus = {}) {
+    const options = typeof optionsOrStatus === "string" ? { status: optionsOrStatus } : optionsOrStatus;
+    return this.granular.listSessions({
+      ...options,
+      environmentId: this.environmentId
+    });
   }
   async getUserEnvironmentState(options = {}) {
     return this.granular.getUserEnvironmentState({
@@ -23310,6 +23490,7 @@ var Environment = class _Environment {
     return this.granular.createSession({
       environmentId: this.environmentId,
       clientId: options?.clientId,
+      sessionScope: options?.sessionScope,
       initialHeap: options?.initialHeap
     });
   }
@@ -24312,6 +24493,7 @@ var Environment = class _Environment {
           records: recordsToImport,
           batchSize: options.batchSize,
           setupRunId: options.setupRunId,
+          operationKey: options.operationKey,
           writeMode: options.writeMode
         })
       }
@@ -24872,7 +25054,7 @@ var EnvironmentSession = class extends Session {
    * Close only the socket transport without sending `client.goodbye`.
    */
   disconnectTransport() {
-    this.client.disconnect();
+    this.client.disconnect({ reason: "Transport detach" });
   }
   /**
    * Backwards-compatible alias for `disconnect()`.
@@ -25116,6 +25298,107 @@ var Granular = class _Granular {
     await this.maybeRunEnvironmentImporter(resolved, environment);
     return environment;
   }
+  /**
+   * Read the active environment selected by Granular for an already-recorded
+   * external user. This is intentionally read-only: browser/login code must
+   * not create subjects or environments as a side effect.
+   */
+  async getActiveEnvironmentForUser(options) {
+    const sandboxId = options.sandboxId.trim();
+    const tagName = options.tag.trim();
+    const userId = options.userId.trim();
+    if (!sandboxId || !tagName || !userId) {
+      throw new Error(
+        "getActiveEnvironmentForUser() requires sandboxId, tag, and userId."
+      );
+    }
+    const subjects = await this.request(
+      `/control/subjects?identityId=${encodeURIComponent(userId)}`
+    );
+    const subject = (subjects.items || []).find(
+      (item) => item.identityId === userId || item.userId === userId
+    );
+    if (!subject?.subjectId && !subject?.granularId) {
+      return null;
+    }
+    const subjectId = subject.subjectId || subject.granularId;
+    const tags = await this.request(
+      `/control/sandboxes/${encodeURIComponent(sandboxId)}/tags`
+    );
+    const tag2 = (tags.items || []).find(
+      (item) => item?.name === tagName
+    );
+    if (!tag2) return null;
+    const query = new URLSearchParams({
+      tagId: tag2.tagId,
+      slot: options.slot?.trim() || "default"
+    });
+    try {
+      const payload = await this.request(
+        `/control/sandboxes/${encodeURIComponent(sandboxId)}/subjects/${encodeURIComponent(subjectId)}/active-environment?${query.toString()}`
+      );
+      return payload.environment ? this.bindEnvironmentHandle(
+        normalizeEnvironmentData(payload.environment)
+      ) : null;
+    } catch (error2) {
+      const message = error2 instanceof Error ? error2.message : String(error2);
+      if (message.includes("404") || message.includes("not found")) {
+        return null;
+      }
+      throw error2;
+    }
+  }
+  /**
+   * Register one reviewed, pre-existing environment as the active workspace
+   * for an external user. This is for a controlled migration only: it does
+   * not create an environment and it does not run an importer.
+   */
+  async adoptEnvironmentForUser(options) {
+    const sandboxId = options.sandboxId.trim();
+    const tagName = options.tag.trim();
+    const userId = options.userId.trim();
+    const environmentId = options.environmentId.trim();
+    if (!sandboxId || !tagName || !userId || !environmentId) {
+      throw new Error(
+        "adoptEnvironmentForUser() requires sandboxId, tag, userId, and environmentId."
+      );
+    }
+    const subjects = await this.request(
+      `/control/subjects?identityId=${encodeURIComponent(userId)}`
+    );
+    const subject = (subjects.items || []).find(
+      (item) => item.identityId === userId || item.userId === userId
+    );
+    if (!subject?.subjectId && !subject?.granularId) {
+      throw new Error(`No Granular subject exists for user ${userId}.`);
+    }
+    const tags = await this.request(`/control/sandboxes/${encodeURIComponent(sandboxId)}/tags`);
+    const tag2 = (tags.items || []).find(
+      (item) => item?.name === tagName
+    );
+    if (!tag2) {
+      throw new Error(`Tag ${tagName} was not found in sandbox ${sandboxId}.`);
+    }
+    const payload = await this.request(
+      "/control/environment-activations/adopt",
+      {
+        method: "POST",
+        body: JSON.stringify({
+          environmentId,
+          subjectId: subject.subjectId || subject.granularId,
+          tagId: tag2.tagId,
+          slot: options.slot?.trim() || "default",
+          confirmExistingData: true
+        })
+      }
+    );
+    if (!payload.environment) {
+      throw new Error("Granular did not return the adopted environment.");
+    }
+    return this.bindEnvironmentHandle(
+      normalizeEnvironmentData(payload.environment)
+    );
+  }
   /**
    * Deprecated compatibility alias for `openEnvironment()`.
    *
@@ -25147,7 +25430,9 @@ var Granular = class _Granular {
         requestedOntology,
         sandboxId: environmentData.sandboxId,
         subjectId: environmentData.subjectId,
-        setupTriggerReason: options.reason || "new_environment"
+        externalUserId: environmentData.subjectId,
+        setupTriggerReason: options.reason || "new_environment",
+        setupOperationKey: options.operationKey
       },
       environment
     );
@@ -25159,20 +25444,17 @@ var Granular = class _Granular {
     }
     return tag2;
   }
-  buildManagedEnvironmentName(tag2, versionId) {
-    return `__sdk__${tag2}__${versionId}__pinned`;
+  buildManagedEnvironmentName(tag2, versionId, resetKey) {
+    if (!resetKey) {
+      return `__sdk__${tag2}__${versionId}__tracked`;
+    }
+    const safeResetKey = resetKey.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
+    return `__sdk__${tag2}__${versionId}__reset__${safeResetKey}`;
   }
   isManagedEnvironmentName(environment, tagName) {
     const name = environment.environment || environment.envName || "";
     return name.startsWith(`__sdk__${tagName}__`);
   }
-  isPinnedToVersion(environment, versionId) {
-    return environment.buildPolicy.mode === "pinned" && (environment.versionId === versionId || environment.buildPolicy.versionId === versionId || environment.buildPolicy.buildId === versionId);
-  }
-  matchesTagTrackedEnvironment(environment, tagName, tagId) {
-    const environmentTagName = environment.tag?.name || environment.buildPolicy.tagName || null;
-    return environment.tagId === tagId || environmentTagName === tagName || environment.environment === tagName || environment.envName === tagName || environment.environment === this.buildManagedEnvironmentName(tagName, environment.versionId) || environment.envName === this.buildManagedEnvironmentName(tagName, environment.versionId);
-  }
   sortEnvironmentsByRecency(environments) {
     return [...environments].sort(
       (left, right) => right.updatedAt - left.updatedAt
@@ -25222,61 +25504,187 @@ var Granular = class _Granular {
         `Tag "${tagName}" does not currently point to a build/version.`
       );
     }
+    const slot = options.slot?.trim() || "default";
+    const resetKey = options.resetKey?.trim() || void 0;
+    const resolveActive = async (operationKey) => {
+      const query = new URLSearchParams({ tagId: tag2.tagId, slot });
+      if (operationKey) query.set("operationKey", operationKey);
+      try {
+        const payload = await this.request(
+          `/control/sandboxes/${encodeURIComponent(sandbox.sandboxId)}/subjects/${encodeURIComponent(user.granularId)}/active-environment?${query.toString()}`
+        );
+        return payload.environment ? normalizeEnvironmentData(payload.environment) : null;
+      } catch (error2) {
+        const message = error2 instanceof Error ? error2.message : String(error2);
+        if (message.includes("404") || message.includes("not found")) {
+          return null;
+        }
+        throw error2;
+      }
+    };
+    const activate = async (environment2) => {
+      const payload = await this.request(
+        "/control/environment-activations",
+        {
+          method: "POST",
+          body: JSON.stringify({
+            environmentId: environment2.environmentId,
+            tagId: tag2.tagId,
+            slot,
+            operationKey: resetKey,
+            operation: resetKey ? "explicit_reset" : void 0
+          })
+        }
+      );
+      return normalizeEnvironmentData(payload.environment);
+    };
+    if (resetKey) {
+      const resetEnvironment = await resolveActive(resetKey);
+      if (resetEnvironment) {
+        return {
+          environment: resetEnvironment,
+          requestedOntology: ontology,
+          sandboxId: sandbox.sandboxId,
+          subjectId: user.granularId,
+          externalUserId: user.userId,
+          // Retrying an explicit reset must also resume its durable setup run.
+          // Otherwise a Container crash after queue submission would leave a
+          // valid environment permanently marked as "running".
+          setupTriggerReason: "explicit_reset",
+          setupOperationKey: resetKey
+        };
+      }
+    } else {
+      const active = await resolveActive();
+      if (active && (active.versionId === targetVersionId || options.createFreshIfOutdated !== true)) {
+        return {
+          environment: active,
+          requestedOntology: ontology,
+          sandboxId: sandbox.sandboxId,
+          subjectId: user.granularId,
+          externalUserId: user.userId
+        };
+      }
+    }
     const allEnvironments = await this.environments.list(sandbox.sandboxId);
     const userEnvironments = allEnvironments.filter(
-      (environment) => environment.subjectId === user.granularId
+      (environment2) => environment2.subjectId === user.granularId
     );
     const currentMatches = this.sortEnvironmentsByRecency(
       userEnvironments.filter(
-        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag2.tagId) && environment.versionId === targetVersionId && (!this.isManagedEnvironmentName(environment, tagName) || this.isPinnedToVersion(environment, targetVersionId))
+        (environment2) => environment2.tagId === tag2.tagId && environment2.versionId === targetVersionId
       )
     );
-    if (currentMatches.length > 0) {
+    if (!resetKey && currentMatches.length > 0) {
+      const environment2 = await activate(currentMatches[0]);
       return {
-        environment: currentMatches[0],
+        environment: environment2,
         requestedOntology: ontology,
         sandboxId: sandbox.sandboxId,
-        subjectId: user.granularId
+        subjectId: user.granularId,
+        externalUserId: user.userId
       };
     }
     const outdatedMatches = this.sortEnvironmentsByRecency(
-      userEnvironments.filter(
-        (environment) => this.matchesTagTrackedEnvironment(environment, tagName, tag2.tagId)
-      )
+      userEnvironments.filter((environment2) => environment2.tagId === tag2.tagId)
     );
     if (outdatedMatches.length > 0 && options.createFreshIfOutdated !== true) {
+      const environment2 = await activate(outdatedMatches[0]);
       return {
-        environment: outdatedMatches[0],
+        environment: environment2,
         requestedOntology: ontology,
         sandboxId: sandbox.sandboxId,
-        subjectId: user.granularId
+        subjectId: user.granularId,
+        externalUserId: user.userId
       };
     }
+    const created = await this.environments.create(sandbox.sandboxId, {
+      subjectId: user.granularId,
+      environment: this.buildManagedEnvironmentName(
+        tagName,
+        targetVersionId,
+        resetKey
+      ),
+      tagId: tag2.tagId,
+      permissionProfileId: null
+    });
+    const environment = await activate(created);
     return {
-      environment: await this.environments.create(sandbox.sandboxId, {
-        subjectId: user.granularId,
-        environment: this.buildManagedEnvironmentName(tagName, targetVersionId),
-        tagId: tag2.tagId,
-        versionId: targetVersionId,
-        permissionProfileId: null
-      }),
+      environment,
       requestedOntology: ontology,
       sandboxId: sandbox.sandboxId,
       subjectId: user.granularId,
-      setupTriggerReason: outdatedMatches.length > 0 ? "fresh_after_version_update" : "new_environment"
+      externalUserId: user.userId,
+      setupTriggerReason: resetKey ? "explicit_reset" : outdatedMatches.length > 0 ? "fresh_after_version_update" : "new_environment",
+      setupOperationKey: resetKey
     };
   }
   /**
-   * List active (open) sessions for an environment — each session is one agent conversation thread.
+   * List indexed sessions using ownership filters and bounded pagination.
+   */
+  async listSessions(options) {
+    const environmentId = options.environmentId?.trim();
+    const sandboxId = options.sandboxId?.trim();
+    const subjectId = options.subjectId?.trim();
+    if (!environmentId && !sandboxId && !subjectId) {
+      throw new Error(
+        "listSessions() requires environmentId, sandboxId, or subjectId so history cannot be scanned accidentally."
+      );
+    }
+    const status = options.status || "active";
+    const allowedStatuses = /* @__PURE__ */ new Set([
+      "active",
+      "closed",
+      "expired",
+      "failed",
+      "timeout",
+      "all"
+    ]);
+    if (!allowedStatuses.has(status)) {
+      throw new Error(`Unsupported session status: ${String(status)}`);
+    }
+    const limit = boundedSessionListInteger(
+      options.limit,
+      "limit",
+      DEFAULT_CONVERSATION_SESSION_LIST_LIMIT,
+      1,
+      MAX_CONVERSATION_SESSION_LIST_LIMIT
+    );
+    const offset = boundedSessionListInteger(
+      options.offset,
+      "offset",
+      0,
+      0,
+      MAX_CONVERSATION_SESSION_LIST_OFFSET
+    );
+    const query = new URLSearchParams({
+      limit: String(limit),
+      offset: String(offset)
+    });
+    if (environmentId) query.set("environmentId", environmentId);
+    if (sandboxId) query.set("sandboxId", sandboxId);
+    if (subjectId) query.set("userId", subjectId);
+    if (options.sessionScope?.trim()) {
+      query.set("sessionScope", options.sessionScope.trim());
+    }
+    if (status !== "all") query.set("status", status);
+    const res = await this.request(
+      `/control/sessions?${query.toString()}`
+    );
+    const items = Array.isArray(res.items) ? res.items : [];
+    return items.map((row) => this.normalizeConversationSession(row));
+  }
+  /**
+   * List active (open) sessions for an environment.
    */
   async listOpenSessions(filters) {
-    return this.listSessionsForEnvironment(filters.environmentId, "active");
+    return this.listSessions({ ...filters, status: "active" });
   }
   /**
    * List closed sessions for an environment (conversations that have disconnected).
    */
   async listClosedSessions(filters) {
-    return this.listSessionsForEnvironment(filters.environmentId, "closed");
+    return this.listSessions({ ...filters, status: "closed" });
   }
   async getUserEnvironmentState(options) {
     const query = new URLSearchParams({
@@ -25311,14 +25719,6 @@ var Granular = class _Granular {
     });
     return result.readAtBySessionId || {};
   }
-  async listSessionsForEnvironment(environmentId, status) {
-    const query = new URLSearchParams({ environmentId, status });
-    const res = await this.request(
-      `/control/sessions?${query.toString()}`
-    );
-    const items = Array.isArray(res.items) ? res.items : [];
-    return items.map((row) => this.normalizeConversationSession(row));
-  }
   normalizeConversationSession(row) {
     const sessionId = String(row.sessionId ?? row.session_id ?? "");
     const environmentId = String(row.environmentId ?? row.environment_id ?? "");
@@ -25377,6 +25777,7 @@ var Granular = class _Granular {
    */
   async createSession(options) {
     const clientId = options.clientId || `client_${Date.now()}`;
+    const sessionScope = options.sessionScope?.trim() || void 0;
     await this.activateEnvironment(options.environmentId);
     const envData = await this.environments.get(options.environmentId);
     const environment = this.bindEnvironmentHandle(envData);
@@ -25385,6 +25786,8 @@ var Granular = class _Granular {
       body: JSON.stringify({
         environmentId: options.environmentId,
         clientId,
+        sessionScope,
+        capabilities: sessionScope ? { sessionScope } : void 0,
         initialHeap: options.initialHeap
       })
     });
@@ -25492,11 +25895,24 @@ var Granular = class _Granular {
       {
         method: "POST",
         body: JSON.stringify({
-          triggerReason: resolved.setupTriggerReason
+          triggerReason: resolved.setupTriggerReason,
+          operationKey: resolved.setupOperationKey
         })
       }
     );
     const setupRunId = setupRun.setupRunId;
+    let claim = null;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      claim = await this.request(
+        `/control/environment-setup-runs/${setupRunId}/importer-claim`,
+        { method: "POST", body: JSON.stringify({}) }
+      );
+      if (claim.action !== "busy") break;
+      await sleep(Math.min(3e4, Math.max(250, claim.retryAfterMs || 1e3)));
+    }
+    if (!claim) {
+      throw new Error(`Unable to claim environment setup run ${setupRunId}.`);
+    }
     const updateSetupRun = async (patch) => {
       await this.request(
         `/control/environment-setup-runs/${setupRunId}`,
@@ -25506,10 +25922,26 @@ var Granular = class _Granular {
         }
       );
     };
+    if (claim.action === "submitted") {
+      const completedSetupRun = await this.request(
+        `/control/environment-setup-runs/${setupRunId}`,
+        { method: "PATCH", body: JSON.stringify({ markHookCompleted: true }) }
+      );
+      const refreshedEnvironment = await this.environments.get(
+        environment.environmentId
+      );
+      environment.syncEnvironmentData(refreshedEnvironment);
+      return completedSetupRun;
+    }
+    if (claim.action === "busy" || claim.action === "terminal") {
+      return claim.summary;
+    }
+    let importSequence = 0;
     const importerContext = {
       environmentId: environment.environmentId,
       sandboxId: environment.sandboxId,
       subjectId: environment.subjectId,
+      externalUserId: resolved.externalUserId,
       reason: resolved.setupTriggerReason,
       incrementTotalObjectsToImportCount: async (n) => {
         const safeIncrement = Math.max(0, Math.trunc(n));
@@ -25526,7 +25958,10 @@ var Granular = class _Granular {
       importRecords: async (records, options) => environment.enqueueRecordImport(records, {
         batchSize: options?.batchSize,
         writeMode: options?.writeMode,
-        setupRunId
+        setupRunId,
+        // Sequence is deterministic for a retry of one importer hook. It
+        // prevents a Container restart from creating a second queue import.
+        operationKey: `${setupRunId}:import:${importSequence++}`
       })
     };
     try {
@@ -26706,15 +27141,22 @@ async function resolveEnvironmentData(granular, options) {
   const ontologyId = await resolveOntologyId(granular, options.ontology);
   const environmentName = options.environment ?? "dev";
   const environments = await granular.environments.list(ontologyId);
-  const existing = environments.find(
-    (environment) => matchesEnvironmentName(environment, environmentName)
+  const matchingEnvironments = environments.filter(
+    (environment) => matchesEnvironmentName(environment, environmentName) && (!options.subjectId || environment.subjectId === options.subjectId)
   );
+  if (matchingEnvironments.length > 1) {
+    throw new Error(
+      `Environment slot \`${environmentName}\` matches ${matchingEnvironments.length} subject environments. Pass --environment-id or --subject-id so session history cannot resolve to an arbitrary user.`
+    );
+  }
+  const existing = matchingEnvironments[0];
   if (existing) {
     return existing;
   }
   if (!options.createIfMissing) {
+    const subjectSuffix = options.subjectId ? ` for subject \`${options.subjectId}\`` : "";
     throw new Error(
-      `No environment named \`${environmentName}\` found for ontology \`${ontologyId}\`. Run \`granular connect test\` or \`granular session create\` first, or pass \`--environment-id\`.`
+      `No environment named \`${environmentName}\`${subjectSuffix} found for ontology \`${ontologyId}\`. Run \`granular connect test\` or \`granular session create\` first, or pass \`--environment-id\`.`
     );
   }
   const connection = await granular.connect({
@@ -26725,17 +27167,15 @@ async function resolveEnvironmentData(granular, options) {
   });
   return await granular.environments.get(connection.environmentId);
 }
-async function listSessionsForEnvironment(granular, environmentId, status) {
-  if (status === "all") {
-    const [active, closed] = await Promise.all([
-      granular.listOpenSessions({ environmentId }),
-      granular.listClosedSessions({ environmentId })
-    ]);
-    return [...active, ...closed].sort((left, right) => {
-      return Date.parse(right.lastSeenAt) - Date.parse(left.lastSeenAt);
-    });
-  }
-  return status === "closed" ? granular.listClosedSessions({ environmentId }) : granular.listOpenSessions({ environmentId });
+async function listSessionsForEnvironment(granular, environmentId, options) {
+  return granular.listSessions({
+    environmentId,
+    status: options.status,
+    sessionScope: options.sessionScope,
+    subjectId: options.subjectId,
+    limit: options.limit,
+    offset: options.offset
+  });
 }
 async function connectRuntime(options) {
   if (options.sessionId) {
@@ -26848,6 +27288,19 @@ async function connectTestCommand(options) {
 }
 
 // src/cli/commands/session.ts
+function parseSessionListInteger(value, name) {
+  const fallback2 = name === "limit" ? 25 : 0;
+  const minimum = name === "limit" ? 1 : 0;
+  const maximum = name === "limit" ? 500 : 1e5;
+  if (value === void 0 || value === "") return fallback2;
+  const parsed = typeof value === "number" ? value : Number.parseInt(value.trim(), 10);
+  if (!Number.isInteger(parsed) || String(parsed) !== String(value).trim() || parsed < minimum || parsed > maximum) {
+    throw new Error(
+      `--${name} must be an integer between ${minimum} and ${maximum}.`
+    );
+  }
+  return parsed;
+}
 function printValue(value, emitJson) {
   const json = JSON.stringify(value, null, 2);
   if (emitJson) {
@@ -26932,7 +27385,8 @@ async function sessionCreateCommand(options) {
     createIfMissing: true
   });
   const environment = await granular.createSession({
-    environmentId: envData.environmentId
+    environmentId: envData.environmentId,
+    sessionScope: options.sessionScope
   });
   try {
     const payload = {
@@ -26941,6 +27395,7 @@ async function sessionCreateCommand(options) {
       environmentId: environment.environmentId,
       environment: environment.tag || envData.tag?.name || envData.buildPolicy.tagName || requestedEnvironment,
       sessionId: environment.sessionId,
+      sessionScope: options.sessionScope?.trim() || null,
       subjectId: environment.subjectId,
       versionId: environment.versionId
     };
@@ -26955,6 +27410,7 @@ async function sessionCreateCommand(options) {
       Environment: payload.environment,
       "Environment ID": payload.environmentId,
       "Session ID": payload.sessionId,
+      "Session scope": payload.sessionScope || "unscoped",
       "Subject ID": payload.subjectId,
       "Version ID": payload.versionId
     });
@@ -26970,6 +27426,21 @@ async function sessionCreateCommand(options) {
 async function sessionListCommand(options) {
   const emitJson = options.json === true;
   const status = options.status ?? "active";
+  const allowedStatuses = /* @__PURE__ */ new Set([
+    "active",
+    "closed",
+    "expired",
+    "failed",
+    "timeout",
+    "all"
+  ]);
+  if (!allowedStatuses.has(status)) {
+    throw new Error(
+      "--status must be one of active, closed, expired, failed, timeout, or all."
+    );
+  }
+  const limit = parseSessionListInteger(options.limit, "limit");
+  const offset = parseSessionListInteger(options.offset, "offset");
   const requestedEnvironment = options.environment ?? "dev";
   if (!emitJson) {
     printHeader();
@@ -26979,18 +27450,33 @@ async function sessionListCommand(options) {
     ontology: options.ontology,
     environment: requestedEnvironment,
     environmentId: options.environmentId,
+    subjectId: options.subjectId,
     createIfMissing: false
   });
   const items = await listSessionsForEnvironment(
     granular,
     environmentData.environmentId,
-    status
+    {
+      status,
+      sessionScope: options.sessionScope?.trim() || void 0,
+      subjectId: options.subjectId?.trim() || void 0,
+      limit,
+      offset
+    }
   );
   const payload = {
     ontologyId: environmentData.sandboxId,
     environmentId: environmentData.environmentId,
     environment: environmentData.tag?.name || environmentData.buildPolicy.tagName || requestedEnvironment,
     status,
+    sessionScope: options.sessionScope?.trim() || null,
+    page: {
+      limit,
+      offset,
+      returned: items.length,
+      mayHaveMore: items.length === limit,
+      nextOffset: items.length === limit ? offset + items.length : null
+    },
     items
   };
   if (emitJson) {
@@ -27013,6 +27499,9 @@ async function sessionListCommand(options) {
       item.lastSeenAt
     ])
   );
+  info(
+    `Showing ${items.length} session${items.length === 1 ? "" : "s"} from offset ${offset}.` + (items.length === limit ? ` Use --offset ${offset + items.length} for the next page.` : "")
+  );
   console.log();
 }
 
@@ -27689,9 +28178,12 @@ program2.command("build").description(
 });
 program2.command("deploy").description(
   "Push the current revision to dev; use --prod to move prod there too"
-).option("--prod", "Also point prod to the current version").action(async (opts) => {
+).option("--prod", "Also point prod to the current version").option(
+  "--release-key <key>",
+  "Version data/importer changes with this immutable release key"
+).action(async (opts) => {
   try {
-    await deployCommand({ prod: opts.prod });
+    await deployCommand({ prod: opts.prod, releaseKey: opts.releaseKey });
   } catch (err) {
     error(err.message);
     process.exit(1);
@@ -27919,6 +28411,9 @@ session.command("create").description(
   "--permissions <list>",
   "Comma-separated permission profile to ensure when a named environment needs to be created",
   "allow-all"
+).option(
+  "--session-scope <scope>",
+  "Application-owned history scope to persist on the new session"
 ).option("--json", "Print machine-readable JSON").action(
   async (options) => {
     try {
@@ -27929,7 +28424,7 @@ session.command("create").description(
     }
   }
 );
-session.command("list").description("List indexed sessions for an environment").option(
+session.command("list").description("List one bounded page of indexed sessions for an environment").option(
   "--ontology <ontologyId>",
   "Override the ontology id from .granularrc"
 ).option(
@@ -27939,11 +28434,17 @@ session.command("list").description("List indexed sessions for an environment").
 ).option(
   "--environment-id <environmentId>",
   "List sessions for this exact environment id"
+).option(
+  "--subject-id <subjectId>",
+  "Resolve and constrain history to this internal Granular subject id"
+).option(
+  "--session-scope <scope>",
+  "Return only sessions owned by this application history scope"
 ).option(
   "--status <status>",
-  "Session status filter: active|closed|all",
+  "Session status: active|closed|expired|failed|timeout|all",
   "active"
-).option("--json", "Print machine-readable JSON").action(
+).option("--limit <count>", "Rows to return (1-500)", "25").option("--offset <count>", "Rows to skip (0-100000)", "0").option("--json", "Print machine-readable JSON").action(
   async (options) => {
     try {
       await sessionListCommand(options);