@granular-software/sdk 0.4.57 → 0.4.59

package/dist/cli/index.js

@@ -7917,12 +7917,12 @@ var ApiClient = class {
       targetVersionId: tag2.targetVersionId ?? tag2.targetBuildId ?? null
     }));
   }
-  async moveTag(tagId, targetBuildId) {
+  async moveTag(tagId, targetBuildId, expectedProdBuildId) {
     const moved = await this.request(
       `/control/tags/${tagId}/move`,
       {
         method: "POST",
-        body: JSON.stringify({ targetBuildId })
+        body: JSON.stringify({ targetBuildId, expectedProdBuildId })
       }
     );
     return {
@@ -7930,22 +7930,24 @@ var ApiClient = class {
       targetVersionId: moved.targetVersionId ?? moved.targetBuildId ?? null
     };
   }
-  async moveVersionTag(tagId, targetVersionId) {
-    return this.moveTag(tagId, targetVersionId);
+  async moveVersionTag(tagId, targetVersionId, expectedProdBuildId) {
+    return this.moveTag(tagId, targetVersionId, expectedProdBuildId);
   }
-  async promoteToProd(buildId) {
+  async promoteToProd(buildId, expectedProdBuildId) {
     return this.request(
       `/control/builds/${buildId}/promote`,
       {
-        method: "POST"
+        method: "POST",
+        body: JSON.stringify({ expectedProdBuildId })
       }
     );
   }
-  async promoteVersionToProd(versionId) {
+  async promoteVersionToProd(versionId, expectedProdBuildId) {
     return this.request(
       `/control/versions/${versionId}/promote`,
       {
-        method: "POST"
+        method: "POST",
+        body: JSON.stringify({ expectedProdBuildId })
       }
     );
   }
@@ -16831,12 +16833,13 @@ ${effectMetamodelTable}
 | API | Purpose |
 |-----|---------|
 | \`submitJob(code)\` | Run code in the sandbox; import generated classes from \`@granular/domain/<Class>\` and actions from \`@granular/actions/backend\` or \`@granular/actions/frontend\`. |
-| \`answerPrompt(...)\`, \`appendMessage(...)\` | Human-in-the-loop and conversation APIs. |
+| \`answerPrompt(...)\`, \`appendUserMessage(...)\` | Human-in-the-loop user ingress APIs. Assistant and component output is authored through trusted runtime/feed paths. |
 | \`getDomain()\`, \`getDomainTypes()\`, \`getDomainDocs()\`, \`getDomainDocumentation()\` | Domain summary and generated TypeScript / docs. |
 | \`getEffects()\` / \`getTools()\`, \`session.on("effects:changed", ...)\` | Effect catalog and live updates. |
 | \`checkReadiness()\`, \`on('readiness', ...)\` | Runtime readiness. |
 | \`document\`, \`getHeap()\` | Current live session state from the WebSocket. |
-| \`messages.list()\`, \`timeline.list()\`, \`jobs.list/get()\`, \`heap.entries.list/get()\`, \`heap.lists.list/get()\`, \`transcript.list()\` | Durable session history and saved artifacts. |
+| \`feed.list()\`, \`transcript.list()\`, \`heap.entries.list/get()\`, \`heap.lists.list/get()\` | Canonical presentation history and saved artifacts. \`transcript.list()\` is projected only from feed-v1. |
+| \`timeline.list()\`, \`jobs.list/get()\` | Diagnostics and execution state; never reconstruct customer-visible chronology from these collections. |
 | \`disconnect()\` | Close the live runtime session. |
 | \`rpc(method, params)\` | Low-level session RPC (advanced). |
 | \`disconnect()\` | End the session. |
@@ -18993,7 +18996,10 @@ async function deployCommand(options = {}) {
     }
     if (options.prod) {
       const promoting = spinner("Promoting prod...");
-      await api.promoteVersionToProd(completed.buildId);
+      await api.promoteVersionToProd(
+        completed.buildId,
+        prodTag?.targetVersionId || prodTag?.targetBuildId || null
+      );
       promoting.succeed(
         `  Prod now points to ${brand.secondary(completed.buildId)}`
       );
@@ -19525,168 +19531,1459 @@ async function simulateCommand(sandboxIdArg, options) {
   info(`Opening simulator: ${url}`);
   openUrl(url);
 }
-var GlobalWebSocket = void 0;
-if (typeof globalThis !== "undefined" && globalThis.WebSocket) {
-  GlobalWebSocket = globalThis.WebSocket;
+
+// src/feed.ts
+function requirePositiveFeedPosition(value) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1) {
+    throw new Error("Invalid feed chronology.");
+  }
+  return value;
 }
-var READY_STATE_OPEN = 1;
-var TOKEN_REFRESH_LEEWAY_MS = 2 * 60 * 1e3;
-var TOKEN_REFRESH_RETRY_MS = 30 * 1e3;
-var MAX_TIMER_DELAY_MS = 2147483647;
-var DEBUG_WS = process.env.GRANULAR_DEBUG_WS === "1";
-var DEFAULT_RPC_TIMEOUT_MS = 3e4;
-var DOMAIN_PACKAGE_RPC_TIMEOUT_MS = 12e4;
-var EFFECT_CONTROL_RPC_TIMEOUT_MS = 12e4;
-var HARNESS_RUN_RPC_TIMEOUT_MS = 6e5;
-var DEFAULT_RECONNECT_DELAY_MS = 3e3;
-var DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
-function debugWs(...args) {
-  if (DEBUG_WS) {
-    console.log(...args);
+function orderTransientFeedItems(items) {
+  const byId = /* @__PURE__ */ new Map();
+  const ordinalById = /* @__PURE__ */ new Map();
+  const idByOrdinal = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const id = String(item.id || "");
+    const ordinal = requirePositiveFeedPosition(item.ordinal);
+    const knownOrdinal = ordinalById.get(id);
+    const ordinalOwner = idByOrdinal.get(ordinal);
+    if (!id || knownOrdinal !== void 0 && knownOrdinal !== ordinal || ordinalOwner && ordinalOwner !== id) {
+      throw new Error("Invalid feed chronology.");
+    }
+    ordinalById.set(id, ordinal);
+    idByOrdinal.set(ordinal, id);
+    const existing = byId.get(id);
+    if (existing && item.revision === existing.revision && stableValueFingerprint(item) !== stableValueFingerprint(existing)) {
+      throw new Error(
+        "Invalid feed chronology: conflicting transient revision."
+      );
+    }
+    if (!existing || item.revision > existing.revision) byId.set(id, item);
   }
+  return [...byId.values()].sort((left, right) => left.ordinal - right.ordinal);
 }
-function rpcTimeoutMsForMethod(method) {
-  switch (method) {
-    case "domain.fetchPackagePart":
-    case "domain.getSummary":
-      return DOMAIN_PACKAGE_RPC_TIMEOUT_MS;
-    case "client.heartbeat":
-    case "effects.publishCatalog":
-    case "effects.resetCatalog":
-    case "effects.addCatalog":
-    case "effects.removeCatalog":
-    case "effects.refresh":
-    case "harness.prepare":
-      return EFFECT_CONTROL_RPC_TIMEOUT_MS;
-    case "harness.run":
-      return HARNESS_RUN_RPC_TIMEOUT_MS;
+var GRANULAR_FEED_DIAGNOSTIC_EVENT = "granular:feed-diagnostic";
+function normalizeFeedDiagnosticKind(kind) {
+  return /^[a-z][a-z0-9_]{0,63}$/.test(kind) ? kind : "invalid_unknown_kind";
+}
+function normalizeFeedDiagnostic(diagnostic) {
+  if (diagnostic.type !== "unknown_kind") return diagnostic;
+  const kind = normalizeFeedDiagnosticKind(diagnostic.kind);
+  return kind === diagnostic.kind ? diagnostic : { ...diagnostic, kind };
+}
+function emitFeedDiagnosticToDefaultSink(diagnostic, target = globalThis) {
+  try {
+    const normalized = normalizeFeedDiagnostic(diagnostic);
+    const EventConstructor = target.CustomEvent || globalThis.CustomEvent;
+    if (typeof target.dispatchEvent !== "function" || typeof EventConstructor !== "function") {
+      return;
+    }
+    target.dispatchEvent(
+      new EventConstructor(GRANULAR_FEED_DIAGNOSTIC_EVENT, {
+        detail: Object.freeze({ ...normalized })
+      })
+    );
+  } catch {
+  }
+}
+function emitFeedDiagnostic(diagnostic, listener) {
+  const normalized = normalizeFeedDiagnostic(diagnostic);
+  emitFeedDiagnosticToDefaultSink(normalized);
+  if (!listener) return;
+  try {
+    listener(normalized);
+  } catch {
+    console.warn("[Granular] Session feed diagnostic listener failed");
+  }
+}
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function isSafeInteger(value, minimum = 0) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
+}
+function finiteInteger(value, fallback2, minimum = 0) {
+  return isSafeInteger(value, minimum) ? value : fallback2;
+}
+function cloneAndFreeze(value, seen = /* @__PURE__ */ new WeakMap()) {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  const object = value;
+  const cached = seen.get(object);
+  if (cached) {
+    return cached;
+  }
+  if (Array.isArray(value)) {
+    const result2 = [];
+    seen.set(object, result2);
+    for (const entry of value) {
+      result2.push(cloneAndFreeze(entry, seen));
+    }
+    return Object.freeze(result2);
+  }
+  const result = /* @__PURE__ */ Object.create(null);
+  seen.set(object, result);
+  for (const [key, entry] of Object.entries(value)) {
+    result[key] = cloneAndFreeze(entry, seen);
+  }
+  return Object.freeze(result);
+}
+function snapshotWith(snapshot, patch) {
+  return Object.freeze({ ...snapshot, ...patch });
+}
+function emptyFeedSnapshot(isHydrated = false) {
+  return Object.freeze({
+    tail: Object.freeze([]),
+    transients: Object.freeze([]),
+    revision: 0,
+    documentEpoch: 0,
+    documentRevision: 0,
+    lastSequence: 0,
+    archivedThroughSequence: 0,
+    hasOlder: false,
+    isHydrated,
+    isRepairing: false,
+    error: null
+  });
+}
+function hasCanonicalSessionFeedActivation(document) {
+  const documentRecord = asRecord(document);
+  const feed = asRecord(documentRecord?.feed);
+  const activation = asRecord(feed?.activation);
+  return activation?.mode === "canonical";
+}
+function isCanonicalSessionFeedDocument(document) {
+  return hasCanonicalSessionFeedActivation(document);
+}
+function canonicalSessionFeedStructureError(document) {
+  if (!hasCanonicalSessionFeedActivation(document)) return null;
+  const documentRecord = asRecord(document);
+  const feed = asRecord(documentRecord?.feed);
+  const activation = asRecord(feed?.activation);
+  if (feed?.schemaVersion !== 1) {
+    return new Error("Canonical feed schemaVersion must be 1.");
+  }
+  if (!isSafeInteger(activation?.activatedAt)) {
+    return new Error("Canonical feed activation timestamp is invalid.");
+  }
+  if (!Array.isArray(feed.tail)) {
+    return new Error("Canonical feed tail is not an array.");
+  }
+  if (!asRecord(feed.transientById)) {
+    return new Error("Canonical feed transientById is not an object.");
+  }
+  if ([
+    feed.revision,
+    feed.lastSequence,
+    feed.archivedThroughSequence,
+    feed.lastTransientOrdinal,
+    documentRecord?.documentEpoch,
+    documentRecord?.documentRevision
+  ].some((value) => !isSafeInteger(value))) {
+    return new Error("Canonical feed chronology scalar is invalid.");
+  }
+  if (!isSafeInteger(documentRecord?.documentEpoch, 1)) {
+    return new Error("Canonical feed documentEpoch must be positive.");
+  }
+  return null;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isKnownDurableFeedKind(kind) {
+  return kind === "message" || kind === "feedback" || kind === "objects" || kind === "table" || kind === "artifact" || kind === "file" || kind === "action_suggestion" || kind === "prompt";
+}
+function hasValidKnownFeedPayload(kind, value) {
+  const payload = asRecord(value);
+  if (!payload) return false;
+  switch (kind) {
+    case "message":
+      return (payload.role === "user" || payload.role === "assistant" || payload.role === "system") && typeof payload.text === "string";
+    case "feedback":
+      return typeof payload.text === "string" && payload.audience === "customer" && (payload.tone === "info" || payload.tone === "working" || payload.tone === "awaiting" || payload.tone === "success" || payload.tone === "warning" || payload.tone === "error");
+    case "objects":
+      return Array.isArray(payload.refs) && payload.refs.every((value2) => {
+        const ref = asRecord(value2);
+        return ref?.type === "entry" && isNonEmptyString(ref.path) || ref?.type === "list" && isNonEmptyString(ref.name) || ref?.type === "variable" && isNonEmptyString(ref.name);
+      });
+    case "table":
+      return isNonEmptyString(payload.tableId) && Array.isArray(payload.columns) && Array.isArray(payload.rows);
+    case "artifact": {
+      const fallback2 = asRecord(payload.fallback);
+      return isNonEmptyString(payload.artifactId) && Boolean(fallback2) && isNonEmptyString(fallback2?.label) && (fallback2?.kind === "effect" || fallback2?.kind === "batch" || fallback2?.kind === "state_path");
+    }
+    case "file": {
+      const fallback2 = asRecord(payload.fallback);
+      return isNonEmptyString(payload.fileId) && Boolean(fallback2) && isNonEmptyString(fallback2?.filename);
+    }
+    case "action_suggestion":
+      return isNonEmptyString(payload.suggestionId) && isNonEmptyString(payload.label);
+    case "prompt":
+      return isNonEmptyString(payload.promptId) && (payload.type === "choice" || payload.type === "confirm" || payload.type === "input") && typeof payload.title === "string" && typeof payload.message === "string" && typeof payload.openedAt === "number" && Number.isFinite(payload.openedAt);
     default:
-      return DEFAULT_RPC_TIMEOUT_MS;
+      return true;
   }
 }
-var WSClient = class {
-  ws = null;
-  url;
-  sessionId;
-  token;
-  messageQueue = [];
-  syncHandlers = [];
-  rpcHandlers = /* @__PURE__ */ new Map();
-  eventHandlers = /* @__PURE__ */ new Map();
-  nextRpcId = 1;
-  doc = Automerge__namespace.init();
-  syncState = Automerge__namespace.initSyncState();
-  reconnectTimer = null;
-  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);
+function normalizeFeedItem(value) {
+  const item = asRecord(value);
+  if (!item || typeof item.id !== "string" || !item.id || !isSafeInteger(item.sequence, 1) || typeof item.kind !== "string" || !item.kind || typeof item.occurredAt !== "number" || !Number.isFinite(item.occurredAt) || !isNonEmptyString(item.operationId) || !isSafeInteger(item.batchIndex) || !hasValidKnownFeedPayload(item.kind, item.payload)) {
+    return null;
+  }
+  return cloneAndFreeze(item);
+}
+function normalizeTransientFeedItem(value) {
+  const item = asRecord(value);
+  const payload = asRecord(item?.payload);
+  if (!item || typeof item.id !== "string" || !item.id || item.kind !== "message" && item.kind !== "feedback" || !isSafeInteger(item.ordinal, 1) || !isSafeInteger(item.revision, 1) || typeof item.createdAt !== "number" || !Number.isFinite(item.createdAt) || typeof item.updatedAt !== "number" || !Number.isFinite(item.updatedAt) || !payload || typeof payload.text !== "string" || item.kind === "message" && (payload.role !== "assistant" || !isSafeInteger(item.producerRevision, 0)) || item.kind === "feedback" && (Object.prototype.hasOwnProperty.call(item, "producerRevision") || payload.audience !== "customer" || !isFeedTransientFeedbackTone(payload.tone))) {
+    return null;
+  }
+  return cloneAndFreeze(item);
+}
+var FEED_TRANSIENT_FEEDBACK_TONES = /* @__PURE__ */ new Set(["info", "working", "awaiting", "warning", "error"]);
+function isFeedTransientFeedbackTone(value) {
+  return typeof value === "string" && FEED_TRANSIENT_FEEDBACK_TONES.has(value);
+}
+function normalizeFeedItems(values) {
+  if (!Array.isArray(values)) {
+    return {
+      items: [],
+      error: new Error("Canonical feed tail is not an array.")
+    };
+  }
+  const items = [];
+  const ids = /* @__PURE__ */ new Map();
+  const sequences = /* @__PURE__ */ new Map();
+  const itemBySequence = /* @__PURE__ */ new Map();
+  let error2 = null;
+  for (const value of values) {
+    const item = normalizeFeedItem(value);
+    if (!item) {
+      error2 ||= new Error("Canonical feed contains an invalid durable item.");
+      continue;
+    }
+    const idSequence = ids.get(item.id);
+    const sequenceId = sequences.get(item.sequence);
+    if (idSequence !== void 0 && idSequence !== item.sequence || sequenceId !== void 0 && sequenceId !== item.id) {
+      error2 ||= new Error(
+        `Canonical feed identity conflict at sequence ${item.sequence}.`
+      );
+      continue;
+    }
+    if (idSequence === item.sequence || sequenceId === item.id) {
+      const duplicate = itemBySequence.get(item.sequence);
+      if (duplicate && !sameDurableItem(duplicate, item)) {
+        error2 ||= new Error(
+          `Immutable feed item ${item.id} has conflicting payloads.`
+        );
+      }
+      continue;
     }
+    ids.set(item.id, item.sequence);
+    sequences.set(item.sequence, item.id);
+    itemBySequence.set(item.sequence, item);
+    items.push(item);
   }
-  get currentSessionId() {
-    return this.sessionId;
+  items.sort((left, right) => left.sequence - right.sequence);
+  return { items: Object.freeze(items), error: error2 };
+}
+function normalizeTransients(values) {
+  const record = asRecord(values);
+  if (!record) {
+    return {
+      items: [],
+      error: new Error("Canonical feed transientById is not an object.")
+    };
   }
-  seedDocumentSnapshot(document) {
-    if (!document || typeof document !== "object" || Array.isArray(document)) {
-      return;
+  let error2 = null;
+  const byId = /* @__PURE__ */ new Map();
+  const idByOrdinal = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(record)) {
+    const item = normalizeTransientFeedItem(value);
+    if (!item || item.id !== key) {
+      error2 ||= new Error("Canonical feed contains an invalid transient item.");
+      continue;
     }
-    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);
+    const ordinalOwner = idByOrdinal.get(item.ordinal);
+    if (ordinalOwner && ordinalOwner !== item.id) {
+      error2 ||= new Error(
+        `Canonical feed transient ordinal ${item.ordinal} is not unique.`
+      );
+    } else {
+      idByOrdinal.set(item.ordinal, item.id);
+    }
+    const current = byId.get(item.id);
+    if (!current || item.revision > current.revision) {
+      byId.set(item.id, item);
     }
   }
-  saveDocumentSnapshot() {
-    return Automerge__namespace.save(this.doc);
+  const items = [...byId.values()].sort(
+    (left, right) => left.ordinal - right.ordinal || left.id.localeCompare(right.id)
+  );
+  return {
+    items: Object.freeze(items),
+    error: error2
+  };
+}
+function readSessionFeedSnapshot(document, options = {}) {
+  const isHydrated = options.isHydrated ?? true;
+  if (!hasCanonicalSessionFeedActivation(document)) {
+    return snapshotWith(emptyFeedSnapshot(isHydrated), {
+      isRepairing: options.isRepairing || false,
+      error: options.error || (isHydrated ? new Error("Canonical session feed-v1 is required.") : null)
+    });
   }
-  clearTokenRefreshTimer() {
-    if (this.tokenRefreshTimer) {
-      clearTimeout(this.tokenRefreshTimer);
-      this.tokenRefreshTimer = null;
+  const documentRecord = asRecord(document);
+  const feed = asRecord(documentRecord.feed);
+  const structureError = canonicalSessionFeedStructureError(document);
+  if (structureError) {
+    const lastSequence2 = finiteInteger(feed.lastSequence, 0);
+    const archivedThroughSequence2 = finiteInteger(
+      feed.archivedThroughSequence,
+      0
+    );
+    return snapshotWith(emptyFeedSnapshot(isHydrated), {
+      revision: finiteInteger(feed.revision, 0),
+      documentEpoch: finiteInteger(documentRecord.documentEpoch, 0),
+      documentRevision: finiteInteger(documentRecord.documentRevision, 0),
+      lastSequence: lastSequence2,
+      archivedThroughSequence: archivedThroughSequence2,
+      hasOlder: archivedThroughSequence2 > 0,
+      isRepairing: options.isRepairing || false,
+      error: options.error || structureError
+    });
+  }
+  const normalizedTail = normalizeFeedItems(feed.tail);
+  const normalizedTransients = normalizeTransients(feed.transientById);
+  const lastSequence = finiteInteger(feed.lastSequence, 0);
+  const archivedThroughSequence = finiteInteger(
+    feed.archivedThroughSequence,
+    0
+  );
+  let error2 = options.error || normalizedTail.error || normalizedTransients.error;
+  let expected = archivedThroughSequence + 1;
+  for (const item of normalizedTail.items) {
+    if (item.sequence !== expected) {
+      error2 ||= new Error(
+        `Canonical feed tail has a sequence gap before ${item.sequence}; expected ${expected}.`
+      );
+      break;
     }
+    expected += 1;
   }
-  decodeBase64Url(payload) {
-    const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
-    const padded = base64 + "=".repeat((4 - (base64.length % 4 || 4)) % 4);
-    if (typeof atob === "function") {
-      return atob(padded);
+  const tailLastSequence = normalizedTail.items[normalizedTail.items.length - 1]?.sequence || archivedThroughSequence;
+  if (tailLastSequence !== lastSequence) {
+    error2 ||= new Error(
+      `Canonical feed tail ends at ${tailLastSequence}, but lastSequence is ${lastSequence}.`
+    );
+  }
+  if (archivedThroughSequence > lastSequence) {
+    error2 ||= new Error(
+      "Canonical feed archivedThroughSequence exceeds lastSequence."
+    );
+  }
+  return Object.freeze({
+    tail: normalizedTail.items,
+    transients: normalizedTransients.items,
+    revision: finiteInteger(feed.revision, 0),
+    documentEpoch: finiteInteger(documentRecord.documentEpoch, 0),
+    documentRevision: finiteInteger(documentRecord.documentRevision, 0),
+    lastSequence,
+    archivedThroughSequence,
+    hasOlder: archivedThroughSequence > 0,
+    isHydrated,
+    isRepairing: options.isRepairing || false,
+    error: error2
+  });
+}
+function validateFeedListOptions(options) {
+  if (options.afterSequence !== void 0 && options.beforeSequence !== void 0) {
+    throw new RangeError(
+      "Feed list accepts afterSequence or beforeSequence, not both."
+    );
+  }
+  for (const [name, value] of [
+    ["afterSequence", options.afterSequence],
+    ["beforeSequence", options.beforeSequence]
+  ]) {
+    if (value !== void 0 && !isSafeInteger(value)) {
+      throw new RangeError(`${name} must be a non-negative integer.`);
     }
-    const maybeBuffer = globalThis.Buffer;
-    if (maybeBuffer) {
-      return maybeBuffer.from(padded, "base64").toString("utf8");
+  }
+  if (options.limit !== void 0 && (!isSafeInteger(options.limit, 1) || options.limit > 500)) {
+    throw new RangeError("Feed list limit must be an integer from 1 to 500.");
+  }
+  return { ...options };
+}
+function normalizeFeedPage(value) {
+  const page = asRecord(value);
+  if (!page) {
+    throw new Error("Feed list transport returned an invalid page.");
+  }
+  const normalized = normalizeFeedItems(page.items);
+  if (normalized.error) {
+    throw normalized.error;
+  }
+  const first = normalized.items[0]?.sequence || null;
+  const last = normalized.items[normalized.items.length - 1]?.sequence || null;
+  for (let index = 1; index < normalized.items.length; index += 1) {
+    if (normalized.items[index].sequence !== normalized.items[index - 1].sequence + 1) {
+      throw new Error("Feed list page contains a sequence gap.");
     }
-    throw new Error("No base64 decoder available");
   }
-  getTokenExpiryMs(token) {
-    const parts = token.split(".");
-    if (parts.length < 2) {
-      return null;
+  if (first === null && (page.firstSequence !== null || page.lastSequence !== null) || first !== null && (!isSafeInteger(page.firstSequence, 1) || !isSafeInteger(page.lastSequence, 1) || page.firstSequence !== first || page.lastSequence !== last) || typeof page.hasMoreBefore !== "boolean" || typeof page.hasMoreAfter !== "boolean") {
+    throw new Error(
+      "Feed list page sequence metadata does not match its items."
+    );
+  }
+  return Object.freeze({
+    items: normalized.items,
+    firstSequence: first,
+    lastSequence: last,
+    hasMoreBefore: page.hasMoreBefore,
+    hasMoreAfter: page.hasMoreAfter
+  });
+}
+function stableValueFingerprint(value, ancestors = /* @__PURE__ */ new WeakSet()) {
+  if (!value || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (ancestors.has(value)) return '"[circular]"';
+  ancestors.add(value);
+  const result = Array.isArray(value) ? `[${value.map((entry) => stableValueFingerprint(entry, ancestors)).join(",")}]` : `{${Object.keys(value).sort().map(
+    (key) => `${JSON.stringify(key)}:${stableValueFingerprint(
+      value[key],
+      ancestors
+    )}`
+  ).join(",")}}`;
+  ancestors.delete(value);
+  return result;
+}
+function sameDurableItem(left, right) {
+  return stableValueFingerprint(left) === stableValueFingerprint(right);
+}
+function contiguousLocalTailWatermark(snapshot) {
+  let watermark = 0;
+  for (const item of snapshot.tail) {
+    if (item.sequence !== watermark + 1) break;
+    watermark = item.sequence;
+  }
+  return watermark;
+}
+var SessionFeedController = class {
+  snapshot;
+  canonical;
+  canonicalStructureValid;
+  deliveredThrough;
+  knownBySequence = /* @__PURE__ */ new Map();
+  sequenceById = /* @__PURE__ */ new Map();
+  subscribers = /* @__PURE__ */ new Set();
+  listTransport;
+  repairGeneration = 0;
+  repairPromise = null;
+  repairRetryHandle = null;
+  repairRetryToken = 0;
+  repairFailureAttempt = 0;
+  scheduleRepairRetryCallback;
+  cancelRepairRetryCallback;
+  initialRepairRetryDelayMs;
+  maxRepairRetryDelayMs;
+  disposed = false;
+  diagnosticListener;
+  diagnosticNow;
+  observedUnknownPositions = /* @__PURE__ */ new Set();
+  constructor(initialDocument, options = {}) {
+    this.diagnosticListener = options.onDiagnostic || null;
+    this.diagnosticNow = options.now || Date.now;
+    this.scheduleRepairRetryCallback = options.scheduleRepairRetry || ((callback, delayMs) => setTimeout(callback, delayMs));
+    this.cancelRepairRetryCallback = options.cancelRepairRetry || ((handle) => clearTimeout(handle));
+    this.initialRepairRetryDelayMs = Math.max(
+      1,
+      options.initialRepairRetryDelayMs ?? 500
+    );
+    this.maxRepairRetryDelayMs = Math.max(
+      this.initialRepairRetryDelayMs,
+      options.maxRepairRetryDelayMs ?? 1e4
+    );
+    this.canonical = hasCanonicalSessionFeedActivation(initialDocument);
+    this.canonicalStructureValid = this.canonical && canonicalSessionFeedStructureError(initialDocument) === null;
+    this.snapshot = readSessionFeedSnapshot(initialDocument, {
+      isHydrated: options.isHydrated ?? this.canonical
+    });
+    this.listTransport = options.listTransport || null;
+    this.deliveredThrough = contiguousLocalTailWatermark(this.snapshot);
+    const identityError = this.remember(this.snapshot.tail);
+    const needsRepair = this.canonicalStructureValid && this.deliveredThrough < this.snapshot.lastSequence;
+    if (identityError || needsRepair) {
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: needsRepair && Boolean(this.listTransport),
+        error: identityError || this.snapshot.error
+      });
     }
-    try {
-      const payloadSegment = parts[1];
-      if (!payloadSegment) {
-        return null;
-      }
-      const payloadRaw = this.decodeBase64Url(payloadSegment);
-      const payload = JSON.parse(payloadRaw);
-      if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
-        return null;
-      }
-      return payload.exp * 1e3;
-    } catch {
-      return null;
+    if (needsRepair) {
+      this.startRepair(this.snapshot.lastSequence);
     }
   }
-  scheduleTokenRefresh() {
-    this.clearTokenRefreshTimer();
-    if (!this.options.tokenProvider || this.isExplicitlyDisconnected) {
-      return;
+  setListTransport(transport) {
+    if (this.disposed) return;
+    if (transport !== this.listTransport) {
+      this.cancelScheduledRepairRetry();
+      this.repairFailureAttempt = 0;
+      this.repairGeneration += 1;
+      this.repairPromise = null;
     }
-    const expiresAt = this.getTokenExpiryMs(this.token);
-    if (!expiresAt) {
-      return;
+    this.listTransport = transport;
+    if (transport && this.canonical && this.canonicalStructureValid && this.deliveredThrough < this.snapshot.lastSequence) {
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: true,
+        error: null
+      });
+      this.startRepair(this.snapshot.lastSequence);
     }
-    const refreshInMs = Math.max(
-      1e3,
-      expiresAt - Date.now() - TOKEN_REFRESH_LEEWAY_MS
-    );
-    const delay = Math.min(refreshInMs, MAX_TIMER_DELAY_MS);
-    this.tokenRefreshTimer = setTimeout(() => {
-      void this.refreshTokenInBackground();
-    }, delay);
   }
-  async refreshTokenInBackground() {
-    if (!this.options.tokenProvider || this.isExplicitlyDisconnected) {
-      return;
+  getSnapshot() {
+    return this.snapshot;
+  }
+  /**
+   * Stop background archive work when its owning Session is replaced or
+   * explicitly disconnected. Late transport completions are quarantined by
+   * the generation check and cannot update subscribers.
+   */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.cancelScheduledRepairRetry();
+    this.repairGeneration += 1;
+    this.repairPromise = null;
+    this.listTransport = null;
+    this.subscribers.clear();
+  }
+  async list(options = {}) {
+    const validated = validateFeedListOptions(options);
+    if (!this.listTransport) {
+      throw new Error(
+        "Historical feed transport is unavailable for this Session."
+      );
     }
-    try {
-      const refreshedToken = await this.options.tokenProvider();
-      if (typeof refreshedToken !== "string" || refreshedToken.length === 0) {
-        throw new Error("Token provider returned no token");
-      }
-      this.token = refreshedToken;
-      this.scheduleTokenRefresh();
-    } catch (error2) {
-      if (this.isExplicitlyDisconnected) {
-        return;
+    const page = normalizeFeedPage(await this.listTransport(validated));
+    this.observeUnknownKinds(page.items);
+    return page;
+  }
+  subscribe(listener, options = {}) {
+    const afterSequence = options.afterSequence;
+    if (afterSequence !== void 0 && !isSafeInteger(afterSequence)) {
+      throw new RangeError(
+        "Feed afterSequence must be a non-negative safe integer."
+      );
+    }
+    this.subscribers.add(listener);
+    if (afterSequence !== void 0 && afterSequence < this.snapshot.lastSequence) {
+      const items = this.snapshot.tail.filter(
+        (item) => item.sequence > afterSequence
+      );
+      if (items.length > 0 && items[0].sequence === afterSequence + 1 && items[items.length - 1].sequence === this.snapshot.lastSequence) {
+        listener({ type: "append", items });
+        if (this.snapshot.transients.length > 0) {
+          listener({
+            type: "transients",
+            items: this.snapshot.transients,
+            revision: this.snapshot.revision
+          });
+        }
+      } else {
+        listener({ type: "reset", snapshot: this.snapshot });
       }
-      console.warn("[Granular] Token refresh failed, retrying soon:", error2);
-      this.clearTokenRefreshTimer();
-      this.tokenRefreshTimer = setTimeout(() => {
-        void this.refreshTokenInBackground();
-      }, TOKEN_REFRESH_RETRY_MS);
+    } else {
+      listener({ type: "reset", snapshot: this.snapshot });
+    }
+    return () => {
+      this.subscribers.delete(listener);
+    };
+  }
+  /**
+   * Accept the latest synced document. Calls may arrive out of order after a
+   * reconnect; freshness watermarks prevent an older snapshot from regressing
+   * durable positions or transient state.
+   */
+  updateDocument(document, options = {}) {
+    if (this.disposed) return;
+    const nextCanonical = hasCanonicalSessionFeedActivation(document);
+    const next = readSessionFeedSnapshot(document, { isHydrated: true });
+    if (!nextCanonical) {
+      if (!this.canonical) {
+        this.snapshot = next;
+        this.emit({ type: "reset", snapshot: this.snapshot });
+        return;
+      }
+      this.rejectSnapshotRegression("canonical_deactivation", next);
+      return;
+    }
+    const nextStructureError = canonicalSessionFeedStructureError(document);
+    if (nextStructureError) {
+      if (!this.canonical) {
+        this.canonical = true;
+        this.canonicalStructureValid = false;
+        this.cancelScheduledRepairRetry();
+        this.repairFailureAttempt = 0;
+        this.repairGeneration += 1;
+        this.repairPromise = null;
+        this.deliveredThrough = 0;
+        this.knownBySequence.clear();
+        this.sequenceById.clear();
+        this.observedUnknownPositions.clear();
+        this.snapshot = next;
+        this.emit({ type: "reset", snapshot: this.snapshot });
+        return;
+      }
+      this.rejectSnapshotRegression("invalid_canonical_document", next);
+      if (!this.canonicalStructureValid) {
+        const current2 = this.snapshot;
+        const incomingIsNewer = next.documentEpoch > current2.documentEpoch || next.documentEpoch === current2.documentEpoch && next.documentRevision >= current2.documentRevision;
+        if (incomingIsNewer && next.lastSequence >= current2.lastSequence) {
+          this.snapshot = next;
+        }
+      } else {
+        this.snapshot = snapshotWith(this.snapshot, {
+          error: nextStructureError
+        });
+      }
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      return;
+    }
+    if (!this.canonical || options.forceReset) {
+      this.acceptReset(next);
+      return;
+    }
+    if (!this.canonicalStructureValid) {
+      const current2 = this.snapshot;
+      if (next.documentEpoch < current2.documentEpoch) {
+        this.rejectSnapshotRegression("older_document_epoch", next);
+        return;
+      }
+      if (next.lastSequence < current2.lastSequence) {
+        this.rejectSnapshotRegression("last_sequence_regression", next);
+        return;
+      }
+      if (next.documentEpoch === current2.documentEpoch && next.documentRevision < current2.documentRevision) {
+        this.rejectSnapshotRegression("document_revision_regression", next);
+        return;
+      }
+      if (next.documentEpoch === current2.documentEpoch && next.revision < current2.revision) {
+        this.rejectSnapshotRegression("feed_revision_regression", next);
+        return;
+      }
+      this.acceptReset(next);
+      return;
+    }
+    const current = this.snapshot;
+    if (next.documentEpoch < current.documentEpoch) {
+      this.rejectSnapshotRegression("older_document_epoch", next);
+      return;
+    }
+    if (next.documentEpoch > current.documentEpoch) {
+      if (next.lastSequence < current.lastSequence) {
+        this.rejectSnapshotRegression("last_sequence_regression", next);
+        return;
+      }
+      const identityError2 = this.findIdentityConflict(next.tail);
+      if (identityError2) {
+        this.rejectSnapshotRegression("identity_conflict", next);
+        this.snapshot = snapshotWith(current, { error: identityError2 });
+        this.emit({ type: "reset", snapshot: this.snapshot });
+        return;
+      }
+      this.acceptReset(next);
+      return;
+    }
+    if (next.lastSequence < current.lastSequence) {
+      this.rejectSnapshotRegression("last_sequence_regression", next);
+      if (next.documentRevision > current.documentRevision) {
+        this.emit({
+          type: "resource_refresh",
+          documentRevision: next.documentRevision
+        });
+        this.snapshot = snapshotWith(current, {
+          documentRevision: next.documentRevision
+        });
+      }
+      return;
+    }
+    const previousDocumentRevision = current.documentRevision;
+    const previousRevision = current.revision;
+    if (next.lastSequence > current.lastSequence && next.revision <= previousRevision) {
+      this.rejectSnapshotRegression("last_sequence_without_revision", next);
+      const documentRevision = Math.max(
+        previousDocumentRevision,
+        next.documentRevision
+      );
+      this.snapshot = snapshotWith(current, {
+        documentRevision,
+        error: new Error(
+          "Feed lastSequence advanced without a newer feed revision."
+        )
+      });
+      if (next.documentRevision > previousDocumentRevision) {
+        this.emit({
+          type: "resource_refresh",
+          documentRevision: next.documentRevision
+        });
+      }
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      return;
+    }
+    const previousTransients = current.transients;
+    const transientIdentityError = next.revision === previousRevision && !sameTransientSet(previousTransients, next.transients) ? new Error("Transient feed changed without a newer feed revision.") : null;
+    const transientSelection = this.selectNewerTransients(current, next);
+    const mergedTransients = transientSelection.items;
+    const identityError = transientIdentityError || transientSelection.error || this.remember(next.tail);
+    if (identityError) {
+      this.rejectSnapshotRegression("identity_conflict", next);
+      this.snapshot = snapshotWith(current, {
+        documentRevision: Math.max(
+          previousDocumentRevision,
+          next.documentRevision
+        ),
+        error: identityError
+      });
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      return;
+    }
+    const keepCurrentFeedState = next.lastSequence === current.lastSequence && next.revision < current.revision;
+    if (keepCurrentFeedState) {
+      this.rejectSnapshotRegression("feed_revision_regression", next);
+    }
+    let nextSnapshot = snapshotWith(keepCurrentFeedState ? current : next, {
+      transients: mergedTransients,
+      revision: Math.max(previousRevision, next.revision),
+      documentRevision: Math.max(
+        previousDocumentRevision,
+        next.documentRevision
+      )
+    });
+    const appended = next.lastSequence > this.deliveredThrough ? this.drainContiguous(next.lastSequence) : [];
+    const needsRepair = this.deliveredThrough < next.lastSequence;
+    const incomingAdvanced = next.documentEpoch > current.documentEpoch || next.documentRevision > current.documentRevision || next.revision > current.revision || next.lastSequence > current.lastSequence;
+    if (incomingAdvanced || !needsRepair) {
+      this.cancelScheduledRepairRetry();
+      this.repairFailureAttempt = 0;
+    }
+    nextSnapshot = snapshotWith(nextSnapshot, {
+      isRepairing: needsRepair,
+      error: nextSnapshot.error
+    });
+    this.snapshot = nextSnapshot;
+    if (appended.length > 0) {
+      this.emit({ type: "append", items: appended });
+    }
+    if (!sameTransientSet(previousTransients, mergedTransients) && next.revision > previousRevision) {
+      this.emit({
+        type: "transients",
+        items: mergedTransients,
+        revision: this.snapshot.revision
+      });
+    }
+    if (next.documentRevision > previousDocumentRevision) {
+      this.emit({
+        type: "resource_refresh",
+        documentRevision: next.documentRevision
+      });
+    }
+    if (needsRepair) {
+      this.startRepair(next.lastSequence);
+    }
+  }
+  /**
+   * Quarantine a canonical replacement rejected by the document transport.
+   * The notice deliberately contains no replacement document, so accepted
+   * feed history remains the only data visible to subscribers during repair.
+   *
+   * @internal
+   */
+  quarantineCanonicalReplacement(quarantine) {
+    if (this.disposed) return;
+    const incoming = snapshotWith(emptyFeedSnapshot(true), {
+      documentEpoch: quarantine.documentEpoch,
+      documentRevision: quarantine.documentRevision,
+      isRepairing: true,
+      error: quarantine.error
+    });
+    if (!this.canonical) {
+      this.canonical = true;
+      this.canonicalStructureValid = false;
+      this.repairGeneration += 1;
+      this.repairPromise = null;
+      this.cancelScheduledRepairRetry();
+      this.repairFailureAttempt = 0;
+      this.deliveredThrough = 0;
+      this.knownBySequence.clear();
+      this.sequenceById.clear();
+      this.observedUnknownPositions.clear();
+      this.snapshot = incoming;
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      return;
+    }
+    this.rejectSnapshotRegression("invalid_canonical_document", incoming);
+    this.repairGeneration += 1;
+    this.repairPromise = null;
+    this.cancelScheduledRepairRetry();
+    this.repairFailureAttempt = 0;
+    if (!this.canonicalStructureValid) {
+      const current = this.snapshot;
+      const incomingIsNewer = incoming.documentEpoch > current.documentEpoch || incoming.documentEpoch === current.documentEpoch && incoming.documentRevision >= current.documentRevision;
+      if (incomingIsNewer) {
+        this.snapshot = incoming;
+      } else {
+        this.snapshot = snapshotWith(current, {
+          isRepairing: true,
+          error: quarantine.error
+        });
+      }
+    } else {
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: true,
+        error: quarantine.error
+      });
+    }
+    this.emit({ type: "reset", snapshot: this.snapshot });
+  }
+  acceptReset(snapshot) {
+    this.cancelScheduledRepairRetry();
+    this.repairFailureAttempt = 0;
+    this.repairGeneration += 1;
+    this.repairPromise = null;
+    this.canonical = true;
+    this.canonicalStructureValid = true;
+    this.knownBySequence.clear();
+    this.sequenceById.clear();
+    this.observedUnknownPositions.clear();
+    this.deliveredThrough = contiguousLocalTailWatermark(snapshot);
+    const identityError = this.remember(snapshot.tail);
+    const needsRepair = this.deliveredThrough < snapshot.lastSequence;
+    this.snapshot = snapshotWith(snapshot, {
+      isRepairing: needsRepair && Boolean(this.listTransport),
+      error: identityError || snapshot.error
+    });
+    this.emit({ type: "reset", snapshot: this.snapshot });
+    if (needsRepair) {
+      this.startRepair(snapshot.lastSequence);
+    }
+  }
+  emitDiagnostic(diagnostic) {
+    emitFeedDiagnostic(diagnostic, this.diagnosticListener);
+  }
+  rejectSnapshotRegression(reason, incoming) {
+    const current = this.snapshot;
+    this.emitDiagnostic({
+      type: "snapshot_regression_rejected",
+      reason,
+      currentDocumentEpoch: current.documentEpoch,
+      incomingDocumentEpoch: incoming.documentEpoch,
+      currentDocumentRevision: current.documentRevision,
+      incomingDocumentRevision: incoming.documentRevision,
+      currentFeedRevision: current.revision,
+      incomingFeedRevision: incoming.revision,
+      currentLastSequence: current.lastSequence,
+      incomingLastSequence: incoming.lastSequence
+    });
+  }
+  observeUnknownKinds(items) {
+    for (const item of items) {
+      const runtimeKind = String(item.kind);
+      if (isKnownDurableFeedKind(runtimeKind)) continue;
+      const diagnosticKind = normalizeFeedDiagnosticKind(runtimeKind);
+      const position = `${item.sequence}:${diagnosticKind}`;
+      if (this.observedUnknownPositions.has(position)) continue;
+      this.observedUnknownPositions.add(position);
+      this.emitDiagnostic({
+        type: "unknown_kind",
+        kind: diagnosticKind,
+        sequence: item.sequence,
+        consumer: "sdk"
+      });
+    }
+  }
+  selectNewerTransients(current, next) {
+    if (next.revision <= current.revision) {
+      return { items: current.transients, error: null };
+    }
+    let newestById;
+    try {
+      newestById = new Map(
+        orderTransientFeedItems([
+          ...current.transients,
+          ...next.transients
+        ]).map((item) => [item.id, item])
+      );
+    } catch {
+      return {
+        items: current.transients,
+        error: new Error(
+          "Transient feed changed immutable identity or revision."
+        )
+      };
+    }
+    const currentById = new Map(
+      current.transients.map((item) => [item.id, item])
+    );
+    const selected = [];
+    for (const incoming of next.transients) {
+      const previous = currentById.get(incoming.id);
+      if (previous && previous.kind !== incoming.kind) {
+        return {
+          items: current.transients,
+          error: new Error(
+            `Transient feed item ${incoming.id} changed its immutable kind.`
+          )
+        };
+      }
+      if (previous?.kind === "message" && incoming.kind === "message" && incoming.revision > previous.revision && incoming.producerRevision < previous.producerRevision) {
+        selected.push(previous);
+        continue;
+      }
+      selected.push(newestById.get(incoming.id) || incoming);
+    }
+    return {
+      items: orderTransientFeedItems(selected),
+      error: null
+    };
+  }
+  remember(items) {
+    const stagedBySequence = /* @__PURE__ */ new Map();
+    const stagedSequenceById = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      const knownSequence = stagedSequenceById.get(item.id) ?? this.sequenceById.get(item.id);
+      const knownItem = stagedBySequence.get(item.sequence) || this.knownBySequence.get(item.sequence);
+      if (knownSequence !== void 0 && knownSequence !== item.sequence || knownItem && knownItem.id !== item.id) {
+        return new Error(
+          `Feed identity changed at sequence ${item.sequence}; a reset is required.`
+        );
+      }
+      if (knownItem && !sameDurableItem(knownItem, item)) {
+        return new Error(
+          `Immutable feed item ${item.id} changed at sequence ${item.sequence}.`
+        );
+      }
+      stagedSequenceById.set(item.id, item.sequence);
+      stagedBySequence.set(item.sequence, item);
+    }
+    for (const item of stagedBySequence.values()) {
+      this.sequenceById.set(item.id, item.sequence);
+      this.knownBySequence.set(item.sequence, item);
+    }
+    this.observeUnknownKinds([...stagedBySequence.values()]);
+    return null;
+  }
+  findIdentityConflict(items) {
+    for (const item of items) {
+      const knownSequence = this.sequenceById.get(item.id);
+      const knownItem = this.knownBySequence.get(item.sequence);
+      if (knownSequence !== void 0 && knownSequence !== item.sequence || knownItem && knownItem.id !== item.id) {
+        return new Error(
+          `Feed identity changed at sequence ${item.sequence}; the checkpoint was rejected.`
+        );
+      }
+      if (knownItem && !sameDurableItem(knownItem, item)) {
+        return new Error(
+          `Immutable feed item ${item.id} changed at sequence ${item.sequence}.`
+        );
+      }
+    }
+    return null;
+  }
+  drainContiguous(targetSequence) {
+    const appended = [];
+    let sequence = this.deliveredThrough + 1;
+    while (sequence <= targetSequence) {
+      const item = this.knownBySequence.get(sequence);
+      if (!item) break;
+      appended.push(item);
+      this.deliveredThrough = sequence;
+      sequence += 1;
+    }
+    return Object.freeze(appended);
+  }
+  startRepair(targetSequence) {
+    if (this.disposed || this.repairPromise || this.repairRetryHandle !== null) {
+      return;
+    }
+    if (!this.listTransport) {
+      this.emitDiagnostic({
+        type: "gap_detected",
+        expectedSequence: this.deliveredThrough + 1,
+        targetSequence,
+        repairAvailable: false
+      });
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: false,
+        error: this.snapshot.error || new Error(
+          "Feed sequence gap cannot be repaired without history transport."
+        )
+      });
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      return;
+    }
+    this.emitDiagnostic({
+      type: "gap_detected",
+      expectedSequence: this.deliveredThrough + 1,
+      targetSequence,
+      repairAvailable: true
+    });
+    const generation = ++this.repairGeneration;
+    this.repairPromise = this.repair(targetSequence, generation).finally(() => {
+      if (generation === this.repairGeneration) {
+        this.repairPromise = null;
+        if (this.deliveredThrough < this.snapshot.lastSequence) {
+          if (this.snapshot.error) {
+            this.scheduleQuietRepairRetry();
+          } else {
+            this.snapshot = snapshotWith(this.snapshot, { isRepairing: true });
+            this.startRepair(this.snapshot.lastSequence);
+          }
+        } else {
+          this.repairFailureAttempt = 0;
+        }
+      }
+    });
+  }
+  cancelScheduledRepairRetry() {
+    if (this.repairRetryHandle === null) return;
+    const handle = this.repairRetryHandle;
+    this.repairRetryHandle = null;
+    this.repairRetryToken += 1;
+    this.cancelRepairRetryCallback(handle);
+  }
+  scheduleQuietRepairRetry() {
+    if (this.disposed || this.repairRetryHandle !== null || this.repairPromise || !this.listTransport || this.deliveredThrough >= this.snapshot.lastSequence) {
+      return;
+    }
+    this.repairFailureAttempt += 1;
+    const delayMs = Math.min(
+      this.maxRepairRetryDelayMs,
+      this.initialRepairRetryDelayMs * 2 ** Math.min(30, Math.max(0, this.repairFailureAttempt - 1))
+    );
+    const retryToken = ++this.repairRetryToken;
+    let handle;
+    handle = this.scheduleRepairRetryCallback(() => {
+      if (retryToken !== this.repairRetryToken || this.repairRetryHandle !== handle) {
+        return;
+      }
+      this.repairRetryHandle = null;
+      if (this.disposed) return;
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: true,
+        error: null
+      });
+      this.emit({ type: "reset", snapshot: this.snapshot });
+      this.startRepair(this.snapshot.lastSequence);
+    }, delayMs);
+    this.repairRetryHandle = handle;
+  }
+  async repair(targetSequence, generation) {
+    const startedAt = this.diagnosticNow();
+    let pageCount = 0;
+    let outcome = "success";
+    try {
+      let attempts = 0;
+      while (generation === this.repairGeneration && this.deliveredThrough < targetSequence) {
+        if (++attempts > 100) {
+          throw new Error("Feed gap repair exceeded its page limit.");
+        }
+        const page = await this.list({
+          afterSequence: this.deliveredThrough,
+          limit: 500
+        });
+        pageCount += 1;
+        if (generation !== this.repairGeneration) {
+          outcome = "cancelled";
+          return;
+        }
+        if (page.items.length === 0) {
+          throw new Error(
+            `Feed gap repair returned no item after sequence ${this.deliveredThrough}.`
+          );
+        }
+        const deliveredBeforePage = this.deliveredThrough;
+        const identityError = this.remember(page.items);
+        if (identityError) throw identityError;
+        const appended = this.drainContiguous(targetSequence);
+        const reachedTarget = this.deliveredThrough >= targetSequence;
+        if (reachedTarget) {
+          this.snapshot = snapshotWith(this.snapshot, {
+            isRepairing: this.deliveredThrough < this.snapshot.lastSequence,
+            error: null
+          });
+        }
+        if (appended.length > 0) {
+          this.emit({ type: "append", items: appended });
+        }
+        if (this.deliveredThrough === deliveredBeforePage) {
+          throw new Error(
+            `Feed gap repair did not return expected sequence ${deliveredBeforePage + 1}.`
+          );
+        }
+        if (this.deliveredThrough < targetSequence && !page.hasMoreAfter && (page.lastSequence || 0) < targetSequence) {
+          throw new Error(
+            `Feed gap remains after sequence ${this.deliveredThrough}.`
+          );
+        }
+      }
+      if (generation !== this.repairGeneration) {
+        outcome = "cancelled";
+        return;
+      }
+    } catch (error2) {
+      if (generation !== this.repairGeneration) {
+        outcome = "cancelled";
+        return;
+      }
+      outcome = "failure";
+      this.snapshot = snapshotWith(this.snapshot, {
+        isRepairing: false,
+        error: error2 instanceof Error ? error2 : new Error(String(error2))
+      });
+      this.emit({ type: "reset", snapshot: this.snapshot });
+    } finally {
+      this.emitDiagnostic({
+        type: "gap_repair",
+        outcome,
+        durationMs: Math.max(0, this.diagnosticNow() - startedAt),
+        pageCount,
+        repairedThroughSequence: this.deliveredThrough,
+        targetSequence
+      });
+    }
+  }
+  emit(change) {
+    for (const subscriber of this.subscribers) {
+      try {
+        subscriber(change);
+      } catch (error2) {
+        console.error("[Granular] Session feed subscriber failed", error2);
+      }
+    }
+  }
+};
+function sameTransientSet(left, right) {
+  return stableValueFingerprint(left) === stableValueFingerprint(right);
+}
+function operationId(prefix) {
+  const randomUuid = globalThis.crypto?.randomUUID?.();
+  return randomUuid ? `${prefix}_${randomUuid}` : `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+function unwrapPublishedItem(value) {
+  const record = asRecord(value);
+  const directItems = Array.isArray(record?.items) ? record.items : [];
+  const durable = asRecord(record?.durable);
+  const durableItems = Array.isArray(durable?.items) ? durable.items : [];
+  return record?.item || directItems[0] || durableItems[0] || value;
+}
+function requireFeedbackItem(value) {
+  const item = normalizeFeedItem(unwrapPublishedItem(value));
+  if (!item || item.kind !== "feedback") {
+    throw new Error("Feed publisher returned an invalid feedback item.");
+  }
+  return item;
+}
+function requireTransientFeedbackItem(value) {
+  const item = normalizeTransientFeedItem(unwrapPublishedItem(value));
+  if (!item || item.kind !== "feedback") {
+    throw new Error(
+      "Feed publisher returned an invalid transient feedback item."
+    );
+  }
+  return item;
+}
+function createFeedPublisher(publish) {
+  const makeHandle = (initial) => {
+    let current = initial;
+    let mutationQueue = Promise.resolve();
+    const enqueueMutation = (mutation) => {
+      const result = mutationQueue.then(mutation);
+      mutationQueue = result.then(
+        () => void 0,
+        () => void 0
+      );
+      return result;
+    };
+    const handle = {
+      get id() {
+        return current.id;
+      },
+      get ordinal() {
+        return current.ordinal;
+      },
+      get revision() {
+        return current.revision;
+      },
+      update(text, options = {}) {
+        const reservedOperationId = options.operationId || operationId("feed_transient_update");
+        const reservedOptions = { ...options };
+        return enqueueMutation(async () => {
+          const response = await publish("feed.transient.update", {
+            transientId: current.id,
+            expectedRevision: current.revision,
+            text,
+            ...reservedOptions,
+            operationId: reservedOperationId
+          });
+          current = requireTransientFeedbackItem(response);
+          return handle;
+        });
+      },
+      settle(text, options = {}) {
+        const reservedOperationId = options.operationId || operationId("feed_transient_settle");
+        const reservedOptions = { ...options };
+        return enqueueMutation(async () => {
+          const response = await publish("feed.transient.settle", {
+            transientId: current.id,
+            expectedRevision: current.revision,
+            ...text === void 0 ? {} : { text },
+            ...reservedOptions,
+            operationId: reservedOperationId
+          });
+          const responseRecord = asRecord(response);
+          const durable = asRecord(responseRecord?.durable);
+          const durableItems = Array.isArray(durable?.items) ? durable.items : [];
+          const rawItem = responseRecord?.item ?? responseRecord?.durableItem ?? durableItems[0];
+          if (rawItem === null || rawItem === void 0) {
+            return null;
+          }
+          return requireFeedbackItem(rawItem);
+        });
+      }
+    };
+    return handle;
+  };
+  return {
+    async feedback(text, options = {}) {
+      return requireFeedbackItem(
+        await publish("feed.feedback", {
+          text,
+          ...options,
+          operationId: options.operationId || operationId("feed_feedback")
+        })
+      );
+    },
+    async transientFeedback(text, options = {}) {
+      const item = requireTransientFeedbackItem(
+        await publish("feed.transient.create", {
+          text,
+          ...options,
+          operationId: options.operationId || operationId("feed_transient_create")
+        })
+      );
+      return makeHandle(item);
+    }
+  };
+}
+
+// src/ws-client.ts
+var GlobalWebSocket = void 0;
+if (typeof globalThis !== "undefined" && globalThis.WebSocket) {
+  GlobalWebSocket = globalThis.WebSocket;
+}
+var READY_STATE_OPEN = 1;
+var TOKEN_REFRESH_LEEWAY_MS = 2 * 60 * 1e3;
+var TOKEN_REFRESH_RETRY_MS = 30 * 1e3;
+var MAX_TIMER_DELAY_MS = 2147483647;
+var DEBUG_WS = process.env.GRANULAR_DEBUG_WS === "1";
+var DEFAULT_RPC_TIMEOUT_MS = 3e4;
+var DOMAIN_PACKAGE_RPC_TIMEOUT_MS = 12e4;
+var EFFECT_CONTROL_RPC_TIMEOUT_MS = 12e4;
+var HARNESS_RUN_RPC_TIMEOUT_MS = 6e5;
+var HEARTBEAT_RPC_TIMEOUT_MS = 15e3;
+var DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
+var DEFAULT_RECONNECT_DELAY_MS = 3e3;
+var DEFAULT_MAX_RECONNECT_ATTEMPTS = 5;
+var DOCUMENT_RESYNC_CLOSE_CODE = 4e3;
+var DOCUMENT_RESYNC_CLOSE_REASON = "Document resync required";
+function documentVersion(document) {
+  const record = document;
+  const epochValue = record.documentEpoch;
+  const revisionValue = record.documentRevision;
+  const epoch = epochValue === void 0 ? 0 : epochValue;
+  const revision = revisionValue === void 0 ? 0 : revisionValue;
+  if (!Number.isSafeInteger(epoch) || Number(epoch) < 0 || !Number.isSafeInteger(revision) || Number(revision) < 0) {
+    throw new Error("Session document version metadata is invalid");
+  }
+  return {
+    epoch: Number(epoch),
+    revision: Number(revision)
+  };
+}
+function stableDocumentFingerprint(value) {
+  if (value === null) return "null";
+  if (value === void 0) return '"[undefined]"';
+  if (typeof value !== "object") return JSON.stringify(value) ?? String(value);
+  if (value instanceof Date) return `date:${value.toISOString()}`;
+  if (value instanceof Uint8Array) {
+    return `bytes:${Array.from(value).join(",")}`;
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableDocumentFingerprint).join(",")}]`;
+  }
+  const record = value;
+  return `{${Object.keys(record).sort().map(
+    (key) => `${JSON.stringify(key)}:${stableDocumentFingerprint(record[key])}`
+  ).join(",")}}`;
+}
+function debugWs(...args) {
+  if (DEBUG_WS) {
+    console.log(...args);
+  }
+}
+function rpcTimeoutMsForMethod(method) {
+  switch (method) {
+    case "domain.fetchPackagePart":
+    case "domain.getSummary":
+      return DOMAIN_PACKAGE_RPC_TIMEOUT_MS;
+    case "client.heartbeat":
+      return HEARTBEAT_RPC_TIMEOUT_MS;
+    case "effects.publishCatalog":
+    case "effects.resetCatalog":
+    case "effects.addCatalog":
+    case "effects.removeCatalog":
+    case "effects.refresh":
+    case "harness.prepare":
+      return EFFECT_CONTROL_RPC_TIMEOUT_MS;
+    case "harness.run":
+      return HARNESS_RUN_RPC_TIMEOUT_MS;
+    default:
+      return DEFAULT_RPC_TIMEOUT_MS;
+  }
+}
+var WSClient = class {
+  ws = null;
+  url;
+  sessionId;
+  token;
+  messageQueue = [];
+  rpcHandlers = /* @__PURE__ */ new Map();
+  eventHandlers = /* @__PURE__ */ new Map();
+  canonicalDocumentQuarantineHandlers = /* @__PURE__ */ new Set();
+  nextRpcId = 1;
+  doc = Automerge__namespace.init();
+  reconnectTimer = null;
+  tokenRefreshTimer = null;
+  isExplicitlyDisconnected = false;
+  reconnectAttempts = 0;
+  connectPromise = null;
+  connectionEpoch = 0;
+  cancelConnectAttempt = null;
+  documentRepairRequired = false;
+  canonicalDocumentActivated = false;
+  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 {
+      const replacement = document instanceof Uint8Array ? Automerge__namespace.load(document) : Automerge__namespace.from(document);
+      if (!this.canAcceptDocumentReplacement(replacement, false)) {
+        return;
+      }
+      this.doc = replacement;
+      this.rememberCanonicalActivation(replacement);
+      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);
+      this.tokenRefreshTimer = null;
+    }
+  }
+  decodeBase64Url(payload) {
+    const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4 || 4)) % 4);
+    if (typeof atob === "function") {
+      return atob(padded);
+    }
+    const maybeBuffer = globalThis.Buffer;
+    if (maybeBuffer) {
+      return maybeBuffer.from(padded, "base64").toString("utf8");
+    }
+    throw new Error("No base64 decoder available");
+  }
+  getTokenExpiryMs(token) {
+    const parts = token.split(".");
+    if (parts.length < 2) {
+      return null;
+    }
+    try {
+      const payloadSegment = parts[1];
+      if (!payloadSegment) {
+        return null;
+      }
+      const payloadRaw = this.decodeBase64Url(payloadSegment);
+      const payload = JSON.parse(payloadRaw);
+      if (typeof payload.exp !== "number" || !Number.isFinite(payload.exp)) {
+        return null;
+      }
+      return payload.exp * 1e3;
+    } catch {
+      return null;
+    }
+  }
+  scheduleTokenRefresh() {
+    this.clearTokenRefreshTimer();
+    if (!this.options.tokenProvider || this.isExplicitlyDisconnected) {
+      return;
+    }
+    const expiresAt = this.getTokenExpiryMs(this.token);
+    if (!expiresAt) {
+      return;
+    }
+    const refreshInMs = Math.max(
+      1e3,
+      expiresAt - Date.now() - TOKEN_REFRESH_LEEWAY_MS
+    );
+    const delay = Math.min(refreshInMs, MAX_TIMER_DELAY_MS);
+    this.tokenRefreshTimer = setTimeout(() => {
+      void this.refreshTokenInBackground();
+    }, delay);
+  }
+  async refreshTokenInBackground() {
+    if (!this.options.tokenProvider || this.isExplicitlyDisconnected) {
+      return;
+    }
+    try {
+      const refreshedToken = await this.options.tokenProvider();
+      if (typeof refreshedToken !== "string" || refreshedToken.length === 0) {
+        throw new Error("Token provider returned no token");
+      }
+      this.token = refreshedToken;
+      this.scheduleTokenRefresh();
+    } catch (error2) {
+      if (this.isExplicitlyDisconnected) {
+        return;
+      }
+      console.warn("[Granular] Token refresh failed, retrying soon:", error2);
+      this.clearTokenRefreshTimer();
+      this.tokenRefreshTimer = setTimeout(() => {
+        void this.refreshTokenInBackground();
+      }, TOKEN_REFRESH_RETRY_MS);
     }
   }
   async resolveTokenForConnect() {
@@ -19733,6 +21030,26 @@ var WSClient = class {
       }
     }
   }
+  /**
+   * Mark the current transport as unusable and schedule the normal reconnect
+   * path. Browser WebSockets can remain in OPEN state after a proxy/worker
+   * restart, so a timed-out heartbeat must revoke the stale socket explicitly.
+   */
+  reportTransportFailure(reason = "WebSocket transport failed") {
+    if (this.isExplicitlyDisconnected) return;
+    const socket = this.ws;
+    this.connectionEpoch += 1;
+    this.ws = null;
+    try {
+      socket?.close(4001, "Transport failure");
+    } catch {
+    }
+    this.handleDisconnect({
+      code: 4001,
+      reason: reason instanceof Error ? reason.message : String(reason),
+      wasClean: false
+    });
+  }
   async connectAttempt(signal) {
     if (signal?.aborted) throw new Error("WebSocket connect aborted");
     const token = await this.resolveTokenForConnect();
@@ -19764,10 +21081,17 @@ var WSClient = class {
     this.ws = socket;
     return new Promise((resolve2, reject) => {
       let settled = false;
+      const configuredConnectTimeoutMs = this.options.connectTimeoutMs;
+      const connectTimeoutMs = typeof configuredConnectTimeoutMs === "number" && Number.isFinite(configuredConnectTimeoutMs) && configuredConnectTimeoutMs > 0 ? configuredConnectTimeoutMs : DEFAULT_CONNECT_TIMEOUT_MS;
+      let connectTimeout = null;
       const isCurrent = () => this.connectionEpoch === epoch && this.ws === socket;
       const finish = (error2) => {
         if (settled) return;
         settled = true;
+        if (connectTimeout) {
+          clearTimeout(connectTimeout);
+          connectTimeout = null;
+        }
         if (this.cancelConnectAttempt === handleAbort) {
           this.cancelConnectAttempt = null;
         }
@@ -19832,6 +21156,17 @@ var WSClient = class {
           wasClean: close.wasClean
         });
       };
+      connectTimeout = setTimeout(() => {
+        if (!isCurrent()) return;
+        this.connectionEpoch += 1;
+        this.ws = null;
+        closeStaleSocket();
+        finish(
+          new Error(
+            `WebSocket connect timed out after ${connectTimeoutMs}ms`
+          )
+        );
+      }, connectTimeoutMs);
       signal?.addEventListener("abort", handleAbort, { once: true });
       const nodeSocket = socket;
       if (typeof nodeSocket.on === "function") {
@@ -19870,11 +21205,12 @@ var WSClient = class {
     });
     this.messageQueue = [];
   }
-  emitReconnectErrorMessage(error2) {
+  emitReconnectErrorMessage(error2, terminal2 = false) {
     const reconnectInfo = {
       error: error2,
       sessionId: this.sessionId,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      terminal: terminal2
     };
     this.emit("reconnect_error", reconnectInfo);
     if (this.options.onReconnectError) {
@@ -19894,7 +21230,8 @@ var WSClient = class {
     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).`
+        `WebSocket reconnect attempts exhausted after ${maxReconnectAttempts} attempt(s).`,
+        true
       );
       return null;
     }
@@ -19924,6 +21261,190 @@ var WSClient = class {
     const suffix = details ? ` (${details})` : "";
     return new Error(`WebSocket disconnected${suffix}`);
   }
+  decodeDocumentBytes(payload, envelopeType) {
+    if (typeof payload === "string") {
+      const binaryString = atob(payload);
+      const bytes = new Uint8Array(binaryString.length);
+      for (let index = 0; index < binaryString.length; index += 1) {
+        bytes[index] = binaryString.charCodeAt(index);
+      }
+      return bytes;
+    }
+    if (payload instanceof Uint8Array) {
+      return payload;
+    }
+    if (Array.isArray(payload) && payload.every(
+      (value) => typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 255
+    )) {
+      return new Uint8Array(payload);
+    }
+    throw new Error(`${envelopeType} payload is not valid byte data`);
+  }
+  rememberCanonicalActivation(document) {
+    if (isCanonicalSessionFeedDocument(document)) {
+      this.canonicalDocumentActivated = true;
+    }
+  }
+  canAcceptDocumentReplacement(replacement, strictlyNewer) {
+    const replacementCanonical = isCanonicalSessionFeedDocument(replacement);
+    const currentCanonical = isCanonicalSessionFeedDocument(this.doc);
+    if (replacementCanonical) {
+      this.canonicalDocumentActivated = true;
+    }
+    if (this.canonicalDocumentActivated && !replacementCanonical) {
+      debugWs(
+        "[Granular DEBUG] Rejected session document replacement that would deactivate the canonical feed."
+      );
+      return false;
+    }
+    const current = documentVersion(this.doc);
+    const incoming = documentVersion(replacement);
+    if (incoming.epoch < current.epoch) {
+      debugWs(
+        `[Granular DEBUG] Rejected stale session document epoch ${incoming.epoch}; current epoch is ${current.epoch}.`
+      );
+      return false;
+    }
+    if (incoming.epoch === current.epoch) {
+      const minimumRevision = strictlyNewer ? current.revision + 1 : current.revision;
+      if (incoming.revision < minimumRevision) {
+        debugWs(
+          `[Granular DEBUG] Rejected stale session document revision ${incoming.revision}; current revision is ${current.revision}.`
+        );
+        return false;
+      }
+    }
+    if (replacementCanonical) {
+      const incomingSnapshot = readSessionFeedSnapshot(replacement);
+      if (incomingSnapshot.error) {
+        this.documentRepairRequired = true;
+        this.exposeCanonicalQuarantine(
+          replacement,
+          currentCanonical,
+          incomingSnapshot.error
+        );
+        debugWs(
+          `[Granular DEBUG] Rejected malformed canonical snapshot: ${incomingSnapshot.error.message}`
+        );
+        return false;
+      }
+    }
+    const canonicalError = this.canonicalReplacementError(replacement);
+    if (canonicalError) {
+      debugWs(`[Granular DEBUG] Rejected session snapshot: ${canonicalError}`);
+      return false;
+    }
+    if (this.canonicalDocumentActivated && incoming.epoch === current.epoch && incoming.revision === current.revision && !readSessionFeedSnapshot(this.doc).error && stableDocumentFingerprint(Automerge__namespace.toJS(replacement)) !== stableDocumentFingerprint(Automerge__namespace.toJS(this.doc))) {
+      debugWs(
+        "[Granular DEBUG] Rejected divergent canonical snapshot at the accepted document version."
+      );
+      return false;
+    }
+    return true;
+  }
+  exposeCanonicalQuarantine(replacement, currentCanonical, error2) {
+    const version2 = documentVersion(replacement);
+    if (currentCanonical) {
+      const quarantine2 = Object.freeze({
+        documentEpoch: version2.epoch,
+        documentRevision: version2.revision,
+        error: new Error(error2.message)
+      });
+      for (const handler of this.canonicalDocumentQuarantineHandlers) {
+        handler(quarantine2);
+      }
+      return;
+    }
+    const accepted = Automerge__namespace.toJS(this.doc);
+    const quarantine = Automerge__namespace.from({
+      ...accepted,
+      documentEpoch: version2.epoch,
+      documentRevision: version2.revision,
+      feed: {
+        activation: { mode: "canonical" }
+      }
+    });
+    this.doc = quarantine;
+    this.emit("sync", this.doc);
+    debugWs(
+      `[Granular DEBUG] Canonical activation quarantined pending repair: ${error2.message}`
+    );
+  }
+  canonicalReplacementError(replacement) {
+    if (!isCanonicalSessionFeedDocument(replacement)) return null;
+    const incoming = readSessionFeedSnapshot(replacement);
+    if (incoming.error) {
+      return `canonical feed is invalid: ${incoming.error.message}`;
+    }
+    if (!this.canonicalDocumentActivated) return null;
+    const current = readSessionFeedSnapshot(this.doc);
+    if (current.error) {
+      return null;
+    }
+    if (incoming.lastSequence < current.lastSequence) {
+      return `canonical lastSequence ${incoming.lastSequence} regresses accepted ${current.lastSequence}`;
+    }
+    const currentBySequence = new Map(
+      current.tail.map((item) => [item.sequence, item])
+    );
+    for (const item of incoming.tail) {
+      const accepted = currentBySequence.get(item.sequence);
+      if (accepted && stableDocumentFingerprint(item) !== stableDocumentFingerprint(accepted)) {
+        return `canonical occurrence ${item.sequence} conflicts with accepted history`;
+      }
+    }
+    return null;
+  }
+  assertIncrementalDocumentIsSafe(replacement) {
+    const missingDependencies = Automerge__namespace.getMissingDeps(replacement, []);
+    if (missingDependencies.length > 0) {
+      throw new Error(
+        `Incremental session update is missing ${missingDependencies.length} causal dependency/dependencies`
+      );
+    }
+    if (this.canonicalDocumentActivated && !isCanonicalSessionFeedDocument(replacement)) {
+      throw new Error(
+        "Incremental session update would deactivate the canonical feed"
+      );
+    }
+    const current = documentVersion(this.doc);
+    const incoming = documentVersion(replacement);
+    if (incoming.epoch < current.epoch || incoming.epoch === current.epoch && incoming.revision < current.revision) {
+      throw new Error("Incremental session update regressed document version");
+    }
+    const canonicalError = this.canonicalReplacementError(replacement);
+    if (canonicalError) {
+      throw new Error(canonicalError);
+    }
+    if (this.canonicalDocumentActivated && incoming.epoch === current.epoch && incoming.revision === current.revision && stableDocumentFingerprint(Automerge__namespace.toJS(replacement)) !== stableDocumentFingerprint(Automerge__namespace.toJS(this.doc))) {
+      throw new Error(
+        "Incremental session update diverged without advancing document revision"
+      );
+    }
+  }
+  requireDocumentResync(envelopeType, error2) {
+    this.documentRepairRequired = true;
+    console.warn(
+      `[Granular] ${envelopeType} could not be applied; reconnecting for a fresh session snapshot.`,
+      error2
+    );
+    const socket = this.ws;
+    if (!socket) {
+      this.scheduleReconnectAttempt();
+      return;
+    }
+    this.connectionEpoch += 1;
+    this.ws = null;
+    try {
+      socket.close(DOCUMENT_RESYNC_CLOSE_CODE, DOCUMENT_RESYNC_CLOSE_REASON);
+    } catch {
+    }
+    this.handleDisconnect({
+      code: DOCUMENT_RESYNC_CLOSE_CODE,
+      reason: DOCUMENT_RESYNC_CLOSE_REASON,
+      wasClean: false
+    });
+  }
   handleDisconnect(close = {}) {
     const unexpected = !this.isExplicitlyDisconnected;
     const info2 = {
@@ -19942,11 +21463,11 @@ var WSClient = class {
     }
     if (unexpected) {
       const disconnectError = this.buildDisconnectError(info2);
-      this.rejectPending(disconnectError);
-      this.emit("disconnect", info2);
       const reconnectDelayMs = this.scheduleReconnectAttempt();
       info2.reconnectScheduled = reconnectDelayMs !== null;
       if (reconnectDelayMs !== null) info2.reconnectDelayMs = reconnectDelayMs;
+      this.rejectPending(disconnectError);
+      this.emit("disconnect", info2);
       if (this.options.onUnexpectedClose) {
         try {
           this.options.onUnexpectedClose(info2);
@@ -19966,100 +21487,109 @@ var WSClient = class {
       JSON.stringify(message).slice(0, 500)
     );
     if ("type" in message && message.type === "sync") {
-      const syncMessage = message;
-      let bytes;
+      this.requireDocumentResync(
+        "Unsupported Automerge sync envelope",
+        new Error("Use snapshot, snapshot_reset, or change.")
+      );
+      return;
+    }
+    if ("type" in message && message.type === "snapshot_reset") {
+      const resetMessage = message;
       try {
-        const payload = syncMessage.message || syncMessage.data;
-        if (typeof payload === "string") {
-          const binaryString = atob(payload);
-          const len = binaryString.length;
-          bytes = new Uint8Array(len);
-          for (let i = 0; i < len; i++) {
-            bytes[i] = binaryString.charCodeAt(i);
-          }
-        } else if (Array.isArray(payload)) {
-          bytes = new Uint8Array(payload);
-        } else if (payload instanceof Uint8Array) {
-          bytes = payload;
-        } else {
-          return;
+        if (!Number.isSafeInteger(resetMessage.documentEpoch) || resetMessage.documentEpoch <= 0 || !Number.isSafeInteger(resetMessage.documentRevision) || resetMessage.documentRevision < 0 || !Array.isArray(resetMessage.data)) {
+          throw new Error("snapshot_reset metadata is invalid");
         }
-        debugWs("[Granular DEBUG] Applying sync bytes:", bytes.length);
-        const [newDoc, newSyncState] = Automerge__namespace.receiveSyncMessage(
-          this.doc,
-          this.syncState,
-          bytes
+        const replacement = Automerge__namespace.load(
+          this.decodeDocumentBytes(
+            resetMessage.data,
+            "Automerge snapshot_reset"
+          )
         );
-        this.doc = newDoc;
-        this.syncState = newSyncState;
-        const docAny = this.doc;
-        if (docAny.catalog) {
-          debugWs(
-            "[Granular DEBUG] Doc catalog sync applied. Keys in catalog:",
-            Object.keys(docAny.catalog || {})
-          );
-          debugWs(
-            "[Granular DEBUG] RawToolCatalogs:",
-            Object.keys(docAny.catalog.rawToolCatalogs || {})
-          );
-        } else {
-          debugWs(
-            "[Granular DEBUG] Doc synced but no catalog yet. Keys in doc:",
-            Object.keys(docAny)
+        const replacementVersion = documentVersion(replacement);
+        const replacementEpoch = replacementVersion.epoch;
+        const replacementRevision = replacementVersion.revision;
+        if (replacementEpoch !== resetMessage.documentEpoch || replacementRevision !== resetMessage.documentRevision) {
+          throw new Error(
+            "snapshot_reset metadata does not match the saved document"
           );
         }
-        this.emit("sync", this.doc);
-      } catch (e) {
-        try {
-          debugWs(
-            "[Granular DEBUG] receiveSyncMessage failed, trying applyChanges..."
-          );
-          const [newDoc] = Automerge__namespace.applyChanges(this.doc, [bytes]);
-          this.doc = newDoc;
-          this.emit("sync", this.doc);
-          debugWs(
-            "[Granular DEBUG] applyChanges succeeded. Doc:",
-            JSON.stringify(Automerge__namespace.toJS(this.doc))
-          );
-        } catch (applyError) {
-          console.warn(
-            "[Granular] Failed to apply sync message (both sync & applyChanges)",
-            e,
-            applyError
-          );
+        if (!this.canAcceptDocumentReplacement(replacement, true)) {
+          if (this.documentRepairRequired) {
+            this.requireDocumentResync(
+              "Stale Automerge snapshot_reset during document repair",
+              new Error("Replacement reset did not advance accepted state")
+            );
+          }
+          return;
         }
+        this.doc = replacement;
+        this.documentRepairRequired = false;
+        this.rememberCanonicalActivation(replacement);
+        this.emit("snapshot_reset", {
+          documentEpoch: replacementEpoch,
+          documentRevision: replacementRevision
+        });
+        this.emit("sync", this.doc);
+      } catch (error2) {
+        this.requireDocumentResync("Automerge snapshot_reset", error2);
       }
       return;
     }
     if ("type" in message && message.type === "snapshot") {
       const snapshotMessage = message;
       try {
-        const bytes = new Uint8Array(snapshotMessage.data);
+        const bytes = this.decodeDocumentBytes(
+          snapshotMessage.data,
+          "Automerge snapshot"
+        );
         debugWs(
           "[Granular DEBUG] Loading Automerge session snapshot bytes:",
           bytes.length
         );
-        this.doc = Automerge__namespace.load(bytes);
+        const replacement = Automerge__namespace.load(bytes);
+        if (!this.canAcceptDocumentReplacement(replacement, false)) {
+          if (this.documentRepairRequired) {
+            this.requireDocumentResync(
+              "Stale Automerge snapshot during document repair",
+              new Error("Replacement snapshot regressed accepted state")
+            );
+          }
+          return;
+        }
+        this.doc = replacement;
+        this.documentRepairRequired = false;
+        this.rememberCanonicalActivation(replacement);
         this.emit("sync", this.doc);
         debugWs(
           "[Granular DEBUG] Automerge session snapshot loaded. Doc:",
           JSON.stringify(Automerge__namespace.toJS(this.doc))
         );
-      } catch (e) {
-        console.warn("[Granular] Failed to load snapshot message", e);
+      } catch (error2) {
+        this.requireDocumentResync("Automerge snapshot", error2);
       }
       return;
     }
     if ("type" in message && message.type === "change") {
+      if (this.documentRepairRequired) {
+        debugWs(
+          "[Granular DEBUG] Ignoring raw change while a replacement snapshot is required."
+        );
+        return;
+      }
       const changeMessage = message;
       try {
-        const bytes = new Uint8Array(changeMessage.data);
+        const bytes = this.decodeDocumentBytes(
+          changeMessage.data,
+          "Automerge change"
+        );
         const [newDoc] = Automerge__namespace.applyChanges(this.doc, [bytes]);
+        this.assertIncrementalDocumentIsSafe(newDoc);
         this.doc = newDoc;
+        this.rememberCanonicalActivation(newDoc);
         this.emit("change", changeMessage);
         this.emit("sync", this.doc);
-      } catch (e) {
-        console.warn("[Granular] Failed to apply change message", e);
+      } catch (error2) {
+        this.requireDocumentResync("Automerge change message", error2);
       }
       return;
     }
@@ -20178,6 +21708,18 @@ var WSClient = class {
     }
     this.eventHandlers.get(event).push(handler);
   }
+  /**
+   * Subscribe to rejected canonical replacement metadata without exposing the
+   * malformed document through the public sync stream.
+   *
+   * @internal Session uses this to quarantine only its feed projection.
+   */
+  onCanonicalDocumentQuarantine(handler) {
+    this.canonicalDocumentQuarantineHandlers.add(handler);
+    return () => {
+      this.canonicalDocumentQuarantineHandlers.delete(handler);
+    };
+  }
   /**
    * Register an RPC handler for incoming server requests
    * @param {string} method - RPC method name
@@ -20235,7 +21777,7 @@ var WSClient = class {
 };
 
 // src/prompt-utils.ts
-function asRecord(value) {
+function asRecord2(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return value;
 }
@@ -20250,7 +21792,7 @@ function parseJsonPromptChoiceOption(option) {
   if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) return null;
   try {
     const parsed = JSON.parse(trimmed);
-    return asRecord(parsed);
+    return asRecord2(parsed);
   } catch {
     return null;
   }
@@ -20312,33 +21854,37 @@ function normalizePromptType(raw) {
   if (kind === "confirm" || kind === "choice" || kind === "input") return kind;
   if (promptType === "confirm" || promptType === "choice" || promptType === "input")
     return promptType;
-  return "input";
+  return null;
 }
 function normalizePrompt(rawValue) {
-  const raw = asRecord(rawValue);
+  const raw = asRecord2(rawValue);
   if (!raw) return null;
-  const promptRecord = asRecord(raw.prompt);
+  const promptRecord = asRecord2(raw.prompt);
   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;
+  const type = normalizePromptType(
+    source === raw ? raw : { ...raw, ...source }
+  );
+  if (!type) return null;
   return {
     id,
     ...jobId ? { jobId } : {},
     ...turnId ? { turnId } : {},
-    type: normalizePromptType(source === raw ? raw : { ...raw, ...source }),
+    type,
     title: typeof source.title === "string" ? source.title : "Input required",
     message: typeof source.message === "string" ? source.message : "",
     options: Array.isArray(source.options) ? source.options.map(
-      (option) => typeof option === "string" || asRecord(option) ? normalizePromptChoiceOption(
+      (option) => typeof option === "string" || asRecord2(option) ? normalizePromptChoiceOption(
         option
       ) : option
     ) : void 0,
     defaultValue: source.defaultValue,
     placeholder: typeof source.placeholder === "string" ? source.placeholder : void 0,
     allowEmpty: typeof source.allowEmpty === "boolean" ? source.allowEmpty : void 0,
-    metadata: asRecord(source.metadata) || void 0
+    metadata: asRecord2(source.metadata) || void 0
   };
 }
 function resolvePromptAnswer(prompt3, answer) {
@@ -20366,23 +21912,36 @@ function resolvePromptAnswer(prompt3, answer) {
 }
 
 // src/session.ts
-var PROMPT_TRANSCRIPT_APPEND_TIMEOUT_MS = 5e3;
 function toPascalCase3(value) {
   return value.split(/[_:\-\s]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 }
-function withPromptTranscriptTimeout(promise) {
-  let timeout = null;
-  return Promise.race([
-    promise,
-    new Promise((_, reject) => {
-      timeout = setTimeout(() => {
-        reject(new Error("Timed out appending prompt answer transcript."));
-      }, PROMPT_TRANSCRIPT_APPEND_TIMEOUT_MS);
-    })
-  ]).finally(() => {
-    if (timeout) {
-      clearTimeout(timeout);
-    }
+function reserveUserMessageId() {
+  const randomUuid = globalThis.crypto?.randomUUID?.();
+  return randomUuid ? `message_${randomUuid}` : `message_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+}
+function normalizeUserMessageIdentity(value, field) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`User message ${field} must be a non-empty string.`);
+  }
+  return value.trim();
+}
+function recordFromUnknown(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function promptSnapshotFingerprint(prompt3) {
+  return JSON.stringify({
+    id: prompt3.id,
+    jobId: prompt3.jobId || null,
+    turnId: prompt3.turnId || null,
+    type: prompt3.type,
+    title: prompt3.title,
+    message: prompt3.message,
+    options: prompt3.options || null,
+    defaultValue: prompt3.defaultValue,
+    placeholder: prompt3.placeholder || null,
+    allowEmpty: prompt3.allowEmpty,
+    metadata: prompt3.metadata || null
   });
 }
 var Session = class {
@@ -20390,7 +21949,6 @@ var Session = class {
   clientId;
   initialQuota;
   jobsMap = /* @__PURE__ */ new Map();
-  pendingAgentMessagesByJobId = /* @__PURE__ */ new Map();
   eventListeners = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
   /** Tracks which tools are instance methods (className set, not static) */
@@ -20407,10 +21965,23 @@ var Session = class {
   domainPackagePartCache = /* @__PURE__ */ new Map();
   domainPackagePartPromises = /* @__PURE__ */ new Map();
   domainPackageFetchQueue = Promise.resolve();
+  feedController;
+  feed;
   constructor(client, clientId, options = {}) {
     this.client = client;
     this.clientId = clientId || `client_${Date.now()}`;
     this.initialQuota = options.initialQuota || null;
+    this.feedController = new SessionFeedController(this.client.doc, {
+      listTransport: (feedOptions) => this.client.call(
+        "feed.list",
+        feedOptions
+      )
+    });
+    this.feed = Object.freeze({
+      getSnapshot: () => this.feedController.getSnapshot(),
+      list: (feedOptions = {}) => this.feedController.list(feedOptions),
+      subscribe: (listener, subscribeOptions = {}) => this.feedController.subscribe(listener, subscribeOptions)
+    });
     this.setupEventHandlers();
     this.setupToolInvokeHandler();
     this.currentDomainRevision = this.extractDomainRevisionFromDoc(
@@ -20429,34 +22000,160 @@ var Session = class {
     }
     return null;
   }
-  buildLegacyEffectContext() {
+  /**
+   * Prompt delivery is deliberately event-driven while a socket is live, but
+   * an existing session can be attached from a fresh tab/client after the
+   * event was originally sent. Rebuild that client's prompt cache from the
+   * canonical document on every sync so an open durable prompt remains
+   * actionable after reconnect without manufacturing a second prompt.
+   */
+  reconcilePromptCacheFromCanonicalDocument(doc) {
+    const jobsById = recordFromUnknown(recordFromUnknown(doc)?.jobs)?.byId;
+    const jobs = recordFromUnknown(jobsById) || {};
+    const openPromptIds = /* @__PURE__ */ new Set();
+    for (const [jobId, jobValue] of Object.entries(jobs)) {
+      const prompts = recordFromUnknown(recordFromUnknown(jobValue)?.prompts);
+      if (!prompts) continue;
+      for (const [promptId, promptValue] of Object.entries(prompts)) {
+        const persisted = recordFromUnknown(promptValue);
+        if (!persisted || persisted.status !== "open") continue;
+        const prompt3 = normalizePrompt({
+          promptId,
+          jobId,
+          kind: persisted.kind,
+          type: persisted.type,
+          title: persisted.title,
+          message: persisted.message,
+          options: persisted.options,
+          defaultValue: persisted.defaultValue,
+          placeholder: persisted.placeholder,
+          allowEmpty: persisted.allowEmpty,
+          metadata: persisted.metadata
+        });
+        if (!prompt3) continue;
+        openPromptIds.add(prompt3.id);
+        if (this.hiddenPromptIds.has(prompt3.id)) continue;
+        const previous = this.promptCache.get(prompt3.id);
+        this.promptCache.set(prompt3.id, prompt3);
+        if (!previous || promptSnapshotFingerprint(previous) !== promptSnapshotFingerprint(prompt3)) {
+          this.emit("prompt", prompt3);
+        }
+      }
+    }
+    for (const promptId of this.promptCache.keys()) {
+      if (!openPromptIds.has(promptId)) {
+        this.promptCache.delete(promptId);
+      }
+    }
+  }
+  buildDirectedInvocationEffectContext(params, feedbackContext) {
     return {
       effectClientId: this.clientId,
-      sandboxId: "",
-      environmentId: "",
-      sessionId: "",
+      sandboxId: params.sandboxId || "",
+      environmentId: params.environmentId || "",
+      invocationId: params.callId,
+      jobId: params.jobId,
+      sessionId: params.sessionId || this.client.currentSessionId,
       user: {
         granularId: "",
         userId: "",
         subjectId: ""
-      }
+      },
+      ...feedbackContext ? {
+        feedback: feedbackContext.feedback,
+        transientFeedback: feedbackContext.transientFeedback
+      } : {}
     };
   }
-  stringifyConversationValue(value) {
-    if (typeof value === "string") {
-      return value;
-    }
-    if (typeof value === "boolean") {
-      return value ? "Confirmed" : "Canceled";
-    }
-    if (value === void 0) {
-      return "";
-    }
-    try {
-      return JSON.stringify(value, null, 2);
-    } catch {
-      return String(value);
-    }
+  createDirectedInvocationFeedbackContext(params) {
+    if (!params.feedbackCapability) return null;
+    const publications = [];
+    let nextOperationOrdinal = 0;
+    const nextOperationId = (kind) => `${kind}:${nextOperationOrdinal++}`;
+    const track = (publication) => {
+      const tracked = Promise.resolve(publication);
+      publications.push(tracked);
+      void tracked.catch(() => void 0);
+      return tracked;
+    };
+    const methodMap = {
+      "feed.feedback": "tool.feedback",
+      "feed.transient.create": "tool.transient.create",
+      "feed.transient.update": "tool.transient.update",
+      "feed.transient.settle": "tool.transient.settle"
+    };
+    const publisher = createFeedPublisher((method, publishParams) => {
+      const directedFeedbackMethod = methodMap[method];
+      if (!directedFeedbackMethod) {
+        throw new Error(`Unsupported directed feedback method: ${method}`);
+      }
+      return this.client.call(directedFeedbackMethod, {
+        ...publishParams,
+        callId: params.callId,
+        feedbackCapability: params.feedbackCapability
+      });
+    });
+    const wrapTransientHandle = (initial) => {
+      let current = initial;
+      const wrapped = {
+        get id() {
+          return current.id;
+        },
+        get ordinal() {
+          return current.ordinal;
+        },
+        get revision() {
+          return current.revision;
+        },
+        async update(text, options = {}) {
+          current = await track(
+            current.update(text, {
+              ...options,
+              operationId: options.operationId || nextOperationId("transient-update")
+            })
+          );
+          return wrapped;
+        },
+        settle(text, options = {}) {
+          return track(
+            current.settle(text, {
+              ...options,
+              operationId: options.operationId || nextOperationId("transient-settle")
+            })
+          );
+        }
+      };
+      return wrapped;
+    };
+    return {
+      feedback: (text, options = {}) => track(
+        publisher.feedback(text, {
+          ...options,
+          operationId: options.operationId || nextOperationId("feedback")
+        })
+      ),
+      transientFeedback: (text, options = {}) => track(
+        publisher.transientFeedback(text, {
+          ...options,
+          operationId: options.operationId || nextOperationId("transient-create")
+        }).then(wrapTransientHandle)
+      ),
+      async flush() {
+        let cursor = 0;
+        let firstError;
+        while (cursor < publications.length) {
+          const batch = publications.slice(cursor);
+          cursor = publications.length;
+          const results = await Promise.allSettled(batch);
+          for (const result of results) {
+            if (result.status === "rejected" && firstError === void 0) {
+              firstError = result.reason;
+            }
+          }
+        }
+        if (firstError !== void 0) throw firstError;
+      }
+    };
   }
   // --- Public API ---
   get document() {
@@ -20588,15 +22285,6 @@ var Session = class {
       createdAt: Date.now()
     });
     this.jobsMap.set(result.jobId, job2);
-    const pendingAgentMessages = this.pendingAgentMessagesByJobId.get(
-      result.jobId
-    );
-    if (pendingAgentMessages && pendingAgentMessages.length > 0) {
-      this.pendingAgentMessagesByJobId.delete(result.jobId);
-      for (const message of pendingAgentMessages) {
-        job2.replayAgentMessage(message);
-      }
-    }
     return job2;
   }
   /**
@@ -20617,50 +22305,44 @@ var Session = class {
   async answerPrompt(promptId, answer) {
     const prompt3 = this.promptCache.get(promptId);
     const resolvedAnswer = resolvePromptAnswer(prompt3, answer);
+    const response = await this.client.call("prompt.answer", {
+      promptId,
+      answer: resolvedAnswer,
+      value: resolvedAnswer
+    });
+    if (response && typeof response === "object" && "ok" in response && response.ok === false) {
+      const rejected = response;
+      const errorMessage = typeof rejected.error === "string" ? rejected.error : "Prompt answer was rejected.";
+      throw new Error(errorMessage);
+    }
     this.promptCache.delete(promptId);
     this.hiddenPromptIds.add(promptId);
     this.emit("prompt:answered", {
       ...prompt3 || { id: promptId },
       id: promptId,
+      answer: resolvedAnswer,
       status: "answered"
     });
-    try {
-      const response = await this.client.call("prompt.answer", {
-        promptId,
-        answer: resolvedAnswer,
-        value: resolvedAnswer
-      });
-      if (response && typeof response === "object" && "ok" in response && response.ok === false) {
-        const rejected = response;
-        const errorMessage = typeof rejected.error === "string" ? rejected.error : "Prompt answer was rejected.";
-        throw new Error(errorMessage);
-      }
-    } catch (error2) {
-      this.hiddenPromptIds.delete(promptId);
-      if (prompt3) {
-        this.promptCache.set(promptId, prompt3);
-      }
-      throw error2;
-    }
-    try {
-      const content = this.stringifyConversationValue(resolvedAnswer);
-      if (content.trim()) {
-        await withPromptTranscriptTimeout(
-          this.appendConversationMessage({
-            role: "user",
-            content,
-            promptId
-          })
-        );
-      }
-    } catch {
-    }
   }
-  async appendConversationMessage(input) {
-    return this.client.call(
-      "conversation.append",
-      input
+  async appendUserMessage(input) {
+    const requestedId = normalizeUserMessageIdentity(input.id, "id");
+    const requestedOperationId = normalizeUserMessageIdentity(
+      input.operationId,
+      "operationId"
     );
+    const id = requestedId || (requestedOperationId ? void 0 : reserveUserMessageId());
+    const operationId2 = requestedOperationId || `conversation.append:${id}`;
+    const {
+      id: _ignoredInputId,
+      operationId: _ignoredInputOperationId,
+      ...message
+    } = input;
+    return this.client.call("conversation.append", {
+      ...message,
+      role: "user",
+      ...id ? { id } : {},
+      operationId: operationId2
+    });
   }
   /**
    * Get the current list of available effects.
@@ -21043,6 +22725,7 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
    * Close the session and disconnect from the sandbox
    */
   async disconnect() {
+    this.disposeSessionFeed();
     try {
       await this.client.call("client.goodbye", {
         clientId: this.clientId,
@@ -21052,6 +22735,10 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
     }
     this.client.disconnect();
   }
+  /** Stop feed repair work without detaching a reconnectable transport. */
+  disposeSessionFeed() {
+    this.feedController.dispose();
+  }
   // --- Event Handling ---
   /**
    * Subscribe to session events
@@ -21076,9 +22763,14 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
     }
   }
   // --- Internal ---
+  setFeedListTransport(transport) {
+    this.feedController.setListTransport(transport);
+  }
   setupToolInvokeHandler() {
     this.client.registerRpcHandler("tool.invoke", async (params) => {
-      const { callId, toolName, input } = params;
+      const invocation = params;
+      const { callId, toolName, input, feedbackCapability } = invocation;
+      const capabilityResultParams = feedbackCapability ? { feedbackCapability } : {};
       this.emit("effect:invoke", {
         callId,
         effectKey: toolName,
@@ -21090,6 +22782,7 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
       if (!handler) {
         await this.client.call("tool.result", {
           callId,
+          ...capabilityResultParams,
           error: {
             code: "TOOL_NOT_FOUND",
             message: `Tool handler not found: ${toolName}`
@@ -21099,21 +22792,45 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
       }
       try {
         let result;
-        const invocationContext = this.buildLegacyEffectContext();
-        if (this.instanceTools.has(toolName) && input && typeof input === "object" && "_objectId" in input) {
-          const { _objectId, ...restParams } = input;
-          result = await handler(
-            _objectId,
-            restParams,
-            invocationContext
-          );
-        } else {
-          result = await handler(input, invocationContext);
+        const feedbackContext = this.createDirectedInvocationFeedbackContext(invocation);
+        const invocationContext = this.buildDirectedInvocationEffectContext(
+          invocation,
+          feedbackContext
+        );
+        let handlerError;
+        let handlerFailed = false;
+        try {
+          if (this.instanceTools.has(toolName) && input && typeof input === "object" && "_objectId" in input) {
+            const { _objectId, ...restParams } = input;
+            result = await handler(
+              _objectId,
+              restParams,
+              invocationContext
+            );
+          } else {
+            result = await handler(input, invocationContext);
+          }
+        } catch (error2) {
+          handlerFailed = true;
+          handlerError = error2;
         }
+        let feedbackError;
+        let feedbackFailed = false;
+        if (feedbackContext) {
+          try {
+            await feedbackContext.flush();
+          } catch (error2) {
+            feedbackFailed = true;
+            feedbackError = error2;
+          }
+        }
+        if (handlerFailed) throw handlerError;
+        if (feedbackFailed) throw feedbackError;
         this.emit("effect:result", { callId, effectKey: toolName, result });
         this.emit("tool:result", { callId, result });
         await this.client.call("tool.result", {
           callId,
+          ...capabilityResultParams,
           result
         });
       } catch (error2) {
@@ -21126,6 +22843,7 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
         this.emit("tool:result", { callId, error: errorMessage });
         await this.client.call("tool.result", {
           callId,
+          ...capabilityResultParams,
           error: { code: "TOOL_EXECUTION_FAILED", message: errorMessage }
         });
       }
@@ -21138,9 +22856,14 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
     );
     this.client.on("sync", (doc) => {
       this.currentDomainRevision = this.extractDomainRevisionFromDoc(doc);
+      this.feedController.updateDocument(doc);
+      this.reconcilePromptCacheFromCanonicalDocument(doc);
       this.emit("sync", doc);
       this.checkForToolChanges();
     });
+    this.client.onCanonicalDocumentQuarantine?.((quarantine) => {
+      this.feedController.quarantineCanonicalReplacement(quarantine);
+    });
     const emitPrompt = (payload) => {
       const prompt3 = normalizePrompt(payload);
       if (!prompt3) return;
@@ -21173,23 +22896,6 @@ import { ${tools[0]?.name || "example"} } from "@granular/actions/backend";
     this.client.on("harness.text_response.delta", (data) => {
       this.emit("harness:text_response_delta", data);
     });
-    this.client.on("job.agent_message", (data) => {
-      const normalized = normalizeJobAgentMessageEnvelope(data);
-      if (!normalized) return;
-      this.emit("job:agent_message", normalized);
-      if (this.jobsMap.has(normalized.jobId)) return;
-      const pending = this.pendingAgentMessagesByJobId.get(normalized.jobId) || [];
-      if (normalized.message.messageId && pending.some(
-        (message) => message.messageId === normalized.message.messageId
-      )) {
-        return;
-      }
-      pending.push(normalized.message);
-      this.pendingAgentMessagesByJobId.set(
-        normalized.jobId,
-        pending.slice(-25)
-      );
-    });
     this.client.on("exec.completed", (data) => {
       this.emit("exec:completed", data);
     });
@@ -21314,24 +23020,6 @@ function sanitizeFeedbackValue(value, depth = 0, seen = /* @__PURE__ */ new Weak
   }
   return truncateFeedbackString(String(value));
 }
-function normalizeJobAgentMessageEnvelope(data) {
-  const d = data;
-  if (typeof d?.jobId !== "string" || !d.jobId) {
-    return null;
-  }
-  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",
-      reply: typeof d.reply === "string" ? d.reply : "",
-      show: d.show,
-      actions: Array.isArray(d.actions) ? d.actions : void 0,
-      timestamp: d.timestamp || Date.now()
-    }
-  };
-}
 var JobImplementation = class {
   id;
   client;
@@ -21340,8 +23028,6 @@ var JobImplementation = class {
   _resolveResult;
   _rejectResult;
   eventListeners = /* @__PURE__ */ new Map();
-  bufferedAgentMessages = [];
-  bufferedAgentMessageIds = /* @__PURE__ */ new Set();
   resultSettled = false;
   metadata;
   constructor(id, client, initialState) {
@@ -21501,12 +23187,6 @@ var JobImplementation = class {
         });
       }
     });
-    this.client.on("job.agent_message", (data) => {
-      const normalized = normalizeJobAgentMessageEnvelope(data);
-      if (normalized?.jobId === id) {
-        this.captureAgentMessage(normalized.message);
-      }
-    });
   }
   get result() {
     return this._resultPromise;
@@ -21531,11 +23211,6 @@ var JobImplementation = class {
       this.eventListeners.set(event, []);
     }
     this.eventListeners.get(event).push(handler);
-    if (event === "agentMessage" && this.bufferedAgentMessages.length > 0) {
-      for (const message of this.bufferedAgentMessages) {
-        handler(message);
-      }
-    }
     return () => {
       const handlers = this.eventListeners.get(event);
       if (!handlers) {
@@ -21547,9 +23222,6 @@ var JobImplementation = class {
       );
     };
   }
-  replayAgentMessage(message) {
-    this.captureAgentMessage(message);
-  }
   buildFeedbackMetadata() {
     const startedAt = this.metadata.startedAt;
     const completedAt = this.metadata.completedAt;
@@ -21622,317 +23294,11 @@ var JobImplementation = class {
       handlers.forEach((h) => h(data));
     }
   }
-  captureAgentMessage(message) {
-    if (message.messageId && this.bufferedAgentMessageIds.has(message.messageId)) {
-      return;
-    }
-    if (message.messageId) {
-      this.bufferedAgentMessageIds.add(message.messageId);
-    }
-    this.bufferedAgentMessages = [...this.bufferedAgentMessages, message].slice(
-      -25
-    );
-    this.emit("agentMessage", message);
-  }
 };
 
-// src/job-presentation.ts
-var RESPONSE_KEYS = [
-  "reply",
-  "response",
-  "text",
-  "message",
-  "summary",
-  "answer"
-];
-var ENTRY_KEY_CANDIDATES = ["entryPath", "path"];
-var ENTRY_ARRAY_KEY_CANDIDATES = ["entryPaths", "paths"];
-var LIST_KEY_CANDIDATES = ["listName"];
-var LIST_ARRAY_KEY_CANDIDATES = ["listNames"];
-var VARIABLE_KEY_CANDIDATES = ["variableName"];
-var VARIABLE_ARRAY_KEY_CANDIDATES = ["variableNames"];
-var UI_CONTAINER_KEYS = ["show", "display", "present", "ui"];
-function asRecord2(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  return value;
-}
-function normalizeText(value) {
-  if (typeof value !== "string") return null;
-  const trimmed = value.trim();
-  if (!trimmed) return null;
-  if (trimmed.startsWith("{") && trimmed.endsWith("}") || trimmed.startsWith("[") && trimmed.endsWith("]")) {
-    return null;
-  }
-  return trimmed;
-}
-function humanTextFromStdout(stdout) {
-  for (const line of [...stdout].reverse()) {
-    const normalized = normalizeText(line);
-    if (!normalized) continue;
-    if (/^[A-Z_]+:/.test(normalized)) continue;
-    return normalized;
-  }
-  return null;
-}
-function responseTextFromAgentMessages(agentMessages) {
-  for (const message of [...agentMessages].reverse()) {
-    const record = asRecord2(message);
-    if (!record) continue;
-    for (const key of RESPONSE_KEYS) {
-      const normalized = normalizeText(record[key]);
-      if (normalized) return normalized;
-    }
-  }
-  return null;
-}
-function pushString(target, value) {
-  if (typeof value === "string" && value.trim()) {
-    target.add(value.trim());
-  }
-}
-function pushStringArray(target, value) {
-  if (!Array.isArray(value)) return;
-  for (const item of value) {
-    pushString(target, item);
-  }
-}
-function collectReferencesFromRecord(record, refs) {
-  for (const key of ENTRY_KEY_CANDIDATES)
-    pushString(refs.entryPaths, record[key]);
-  for (const key of ENTRY_ARRAY_KEY_CANDIDATES)
-    pushStringArray(refs.entryPaths, record[key]);
-  for (const key of LIST_KEY_CANDIDATES)
-    pushString(refs.listNames, record[key]);
-  for (const key of LIST_ARRAY_KEY_CANDIDATES)
-    pushStringArray(refs.listNames, record[key]);
-  for (const key of VARIABLE_KEY_CANDIDATES)
-    pushString(refs.variableNames, record[key]);
-  for (const key of VARIABLE_ARRAY_KEY_CANDIDATES)
-    pushStringArray(refs.variableNames, record[key]);
-}
-function stringValue(record, keys) {
-  for (const key of keys) {
-    const value = record[key];
-    if (typeof value === "string" && value.trim()) {
-      return value.trim();
-    }
-  }
-  return null;
-}
-function findEntryPathForRecord(record, heap) {
-  const directPath = stringValue(record, ["entryPath", "path"]);
-  if (directPath && heap.entriesByPath?.[directPath]) {
-    return directPath;
-  }
-  const id = stringValue(record, ["id", "_id", "recordId", "objectId"]);
-  if (!id) {
-    return null;
-  }
-  const className = stringValue(record, [
-    "className",
-    "_className",
-    "__className",
-    "prototype",
-    "type"
-  ]);
-  const entries = Object.values(heap.entriesByPath || {});
-  const exact = entries.find(
-    (entry) => entry.id === id && (!className || entry.className === className || entry.prototypes?.includes(className))
-  );
-  if (exact?.path) {
-    return exact.path;
-  }
-  const idOnlyMatches = entries.filter((entry) => entry.id === id);
-  return idOnlyMatches.length === 1 ? idOnlyMatches[0].path : null;
-}
-function scanForHeapReferences(value, heap, refs, depth = 0, seen = /* @__PURE__ */ new Set()) {
-  if (value === null || value === void 0 || depth > 4 || seen.has(value))
-    return;
-  if (typeof value === "string") {
-    const trimmed = value.trim();
-    if (heap.entriesByPath?.[trimmed]) refs.entryPaths.add(trimmed);
-    if (heap.listsByName?.[trimmed]) refs.listNames.add(trimmed);
-    if (heap.variablesByName?.[trimmed]) refs.variableNames.add(trimmed);
-    return;
-  }
-  if (Array.isArray(value)) {
-    seen.add(value);
-    for (const item of value.slice(0, 24)) {
-      scanForHeapReferences(item, heap, refs, depth + 1, seen);
-    }
-    return;
-  }
-  const record = asRecord2(value);
-  if (!record) return;
-  seen.add(value);
-  const entryPath = findEntryPathForRecord(record, heap);
-  if (entryPath) refs.entryPaths.add(entryPath);
-  collectReferencesFromRecord(record, refs);
-  for (const key of UI_CONTAINER_KEYS) {
-    const nested = asRecord2(record[key]);
-    if (nested) collectReferencesFromRecord(nested, refs);
-  }
-  for (const nested of Object.values(record).slice(0, 24)) {
-    scanForHeapReferences(nested, heap, refs, depth + 1, seen);
-  }
-}
-function resolveVariablesToReferences(variableNames, heap, refs) {
-  for (const variableName of variableNames) {
-    const variable = heap.variablesByName?.[variableName];
-    if (!variable) continue;
-    if (variable.kind === "entry" && variable.entryPath) {
-      refs.entryPaths.add(variable.entryPath);
-    }
-    if (variable.kind === "list" && variable.listName) {
-      refs.listNames.add(variable.listName);
-    }
-  }
-}
-function sortEntries(entries) {
-  return [...entries].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-}
-function sortLists(lists) {
-  return [...lists].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-}
-function dedupeEntries(entries) {
-  const seen = /* @__PURE__ */ new Set();
-  const result = [];
-  for (const entry of entries) {
-    if (!entry?.path || seen.has(entry.path)) continue;
-    seen.add(entry.path);
-    result.push(entry);
-  }
-  return result;
-}
-function dedupeLists(lists) {
-  const seen = /* @__PURE__ */ new Set();
-  const result = [];
-  for (const list of lists) {
-    if (!list?.name || seen.has(list.name)) continue;
-    seen.add(list.name);
-    result.push(list);
-  }
-  return result;
-}
-function extractResponseText(result, stdout) {
-  const directText = normalizeText(result);
-  if (directText) return directText;
-  const record = asRecord2(result);
-  if (record) {
-    for (const key of RESPONSE_KEYS) {
-      const normalized = normalizeText(record[key]);
-      if (normalized) return normalized;
-    }
-    for (const containerKey of UI_CONTAINER_KEYS) {
-      const nested = asRecord2(record[containerKey]);
-      if (!nested) continue;
-      for (const key of RESPONSE_KEYS) {
-        const normalized = normalizeText(nested[key]);
-        if (normalized) return normalized;
-      }
-    }
-  }
-  return humanTextFromStdout(stdout);
-}
-function fallbackResponseText(entries, lists) {
-  if (entries.length > 0) {
-    return entries.length === 1 ? "I found one relevant record." : `I found ${entries.length} relevant records.`;
-  }
-  if (lists.length > 0) {
-    const emptyOnly = lists.every((list) => (list.paths || []).length === 0);
-    if (emptyOnly) {
-      return lists.length === 1 ? "I saved one empty result set." : `I saved ${lists.length} empty result sets.`;
-    }
-    return lists.length === 1 ? "I saved one result set." : `I saved ${lists.length} result sets.`;
-  }
-  return null;
-}
-function getJobRelatedEntries(heap, jobId) {
-  return sortEntries(
-    Object.values(heap.entriesByPath || {}).filter(
-      (entry) => entry.relatedJobIds?.includes(jobId)
-    )
-  );
-}
-function getJobRelatedLists(heap, jobId) {
-  return sortLists(
-    Object.values(heap.listsByName || {}).filter(
-      (list) => list.relatedJobIds?.includes(jobId)
-    )
-  );
-}
-function entriesFromLists(lists, heap) {
-  const entries = [];
-  for (const list of lists) {
-    for (const path7 of list.paths || []) {
-      const entry = heap.entriesByPath?.[path7];
-      if (entry) entries.push(entry);
-    }
-  }
-  return entries;
-}
-function resolveJobPresentation({
-  jobId,
-  result,
-  stdout = [],
-  agentMessages = [],
-  sessionHeap,
-  allowExplicitArtifacts = true
-}) {
-  const refs = {
-    entryPaths: /* @__PURE__ */ new Set(),
-    listNames: /* @__PURE__ */ new Set(),
-    variableNames: /* @__PURE__ */ new Set()
-  };
-  if (allowExplicitArtifacts) {
-    scanForHeapReferences(result, sessionHeap, refs);
-    resolveVariablesToReferences(refs.variableNames, sessionHeap, refs);
-  }
-  const referencedLists = sortLists(
-    [...refs.listNames].map((name) => sessionHeap.listsByName?.[name]).filter((list) => Boolean(list))
-  );
-  const referencedEntries = sortEntries(
-    [...refs.entryPaths].map((path7) => sessionHeap.entriesByPath?.[path7]).filter((entry) => Boolean(entry))
-  );
-  const jobLists = getJobRelatedLists(sessionHeap, jobId);
-  const jobEntries = getJobRelatedEntries(sessionHeap, jobId);
-  const changedEntries = dedupeEntries([
-    ...jobEntries,
-    ...entriesFromLists(jobLists, sessionHeap)
-  ]);
-  const explicitLists = dedupeLists(referencedLists);
-  const explicitEntries = dedupeEntries([
-    ...referencedEntries,
-    ...entriesFromLists(referencedLists, sessionHeap)
-  ]);
-  const hasExplicitArtifacts = allowExplicitArtifacts && (explicitEntries.length > 0 || explicitLists.length > 0);
-  const lists = hasExplicitArtifacts ? explicitLists : jobLists;
-  const entries = hasExplicitArtifacts ? explicitEntries : changedEntries;
-  const responseText = extractResponseText(result, stdout) || responseTextFromAgentMessages(agentMessages) || fallbackResponseText(entries, lists);
-  return {
-    responseText,
-    entries,
-    lists,
-    changedEntries,
-    changedLists: jobLists,
-    hasExplicitArtifacts
-  };
-}
-
 // src/session-transcript.ts
-var EMPTY_HEAP = {
-  entriesByPath: {},
-  listsByName: {},
-  variablesByName: {}};
 function asRecord3(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  return value;
-}
-function asArray(value) {
-  return Array.isArray(value) ? value : [];
-}
-function asNumber(value) {
-  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function asString(value) {
   return typeof value === "string" ? value : void 0;
@@ -21957,138 +23323,13 @@ function artifactRecordsById(liveDoc) {
     Object.entries(byId).map(([artifactId, value]) => {
       const record = asRecord3(value);
       return record ? [artifactId, record] : null;
-    }).filter(
-      (entry) => Boolean(entry)
-    )
-  );
-}
-function normalizeShowRefs(value) {
-  const record = asRecord3(value);
-  if (!record) return void 0;
-  const normalizeRefs = (input) => {
-    if (!Array.isArray(input)) return void 0;
-    const refs = Array.from(
-      new Set(
-        input.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean)
-      )
-    );
-    return refs.length > 0 ? refs : void 0;
-  };
-  const show = {
-    entryPaths: normalizeRefs(record.entryPaths),
-    listNames: normalizeRefs(record.listNames),
-    variableNames: normalizeRefs(record.variableNames),
-    fileIds: normalizeRefs(record.fileIds),
-    sessionArtifactIds: normalizeRefs(record.sessionArtifactIds),
-    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.tables ? show : void 0;
-}
-function normalizeActionSuggestions(value) {
-  if (!Array.isArray(value)) return void 0;
-  const suggestions = [];
-  for (const item of value) {
-    const record = asRecord3(item);
-    if (!record) continue;
-    const label = trimString(record.label);
-    if (!label) continue;
-    const suggestionId = trimString(record.suggestionId) || trimString(record.id) || label;
-    suggestions.push({
-      suggestionId,
-      label,
-      ...typeof record.description === "string" ? { description: record.description } : {},
-      ...asRecord3(record.artifact) ? { artifact: asRecord3(record.artifact) } : {},
-      ...asRecord3(record.target) ? { target: asRecord3(record.target) } : {},
-      ...asRecord3(record.metadata) ? { metadata: asRecord3(record.metadata) } : {}
-    });
-  }
-  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
-    ])
+    }).filter((entry) => Boolean(entry))
   );
-  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;
-  }
-  if (typeof value === "boolean") {
-    return value ? "Confirmed" : "Canceled";
-  }
-  if (value === void 0) {
-    return fallback2;
-  }
+  if (typeof value === "string") return value.trim() || fallback2;
+  if (typeof value === "boolean") return value ? "Confirmed" : "Canceled";
+  if (value === void 0) return fallback2;
   try {
     const json = JSON.stringify(value, null, 2);
     if (!json || json === "undefined") return fallback2;
@@ -22229,262 +23470,121 @@ ${stringifyTranscriptValue({ show }, "")}`;
     hasOtherRefs ? `Other shown refs: ${stringifyTranscriptValue(otherRefs, "")}` : null
   ].filter(Boolean).join("\n");
 }
-function normalizeConversationMessage(raw, artifactsById) {
-  const record = asRecord3(raw);
-  if (!record) return null;
-  const role = record.role === "user" ? "user" : record.role === "assistant" ? "assistant" : null;
-  if (!role) return null;
-  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 && !actions?.length) return null;
-  const artifactHistory = buildArtifactHistory(show, artifactsById);
-  const historyContent = role === "assistant" ? content && artifactHistory ? `[Assistant reply]
-${content}
-
-${artifactHistory}` : content ? `[Assistant reply]
-${content}` : artifactHistory : void 0;
-  return {
-    id,
-    role,
-    content,
-    timestamp,
-    jobId: asString(record.jobId),
-    promptId: asString(record.promptId),
-    show,
-    actions,
-    parts,
-    historyContent,
-    source: "conversation"
-  };
+function feedItemShow(item) {
+  switch (item.kind) {
+    case "objects": {
+      const entryPaths = [];
+      const listNames = [];
+      const variableNames = [];
+      for (const ref of item.payload.refs) {
+        if (ref.type === "entry") entryPaths.push(ref.path);
+        if (ref.type === "list") listNames.push(ref.name);
+        if (ref.type === "variable") variableNames.push(ref.name);
+      }
+      return {
+        ...entryPaths.length ? { entryPaths } : {},
+        ...listNames.length ? { listNames } : {},
+        ...variableNames.length ? { variableNames } : {}
+      };
+    }
+    case "table":
+      return {
+        tables: [
+          {
+            id: item.payload.tableId,
+            label: item.payload.label,
+            columns: item.payload.columns,
+            rows: item.payload.rows
+          }
+        ]
+      };
+    case "artifact":
+      return { sessionArtifactIds: [item.payload.artifactId] };
+    case "file":
+      return { fileIds: [item.payload.fileId] };
+    case "action_suggestion":
+      return {
+        actionSuggestions: [
+          {
+            suggestionId: item.payload.suggestionId,
+            label: item.payload.label,
+            description: item.payload.description,
+            target: item.payload.target ? { ...item.payload.target } : void 0,
+            artifact: item.payload.proposedArtifact ? { ...item.payload.proposedArtifact } : void 0
+          }
+        ]
+      };
+    default:
+      return void 0;
+  }
 }
-function normalizePromptEntries(jobId, rawPrompts, conversationPromptIds) {
-  const promptsById = asRecord3(rawPrompts) || {};
-  return Object.values(promptsById).map((value) => asRecord3(value)).filter((value) => Boolean(value)).sort(
-    (left, right) => (asNumber(left.openedAt) || asNumber(left.answeredAt) || 0) - (asNumber(right.openedAt) || asNumber(right.answeredAt) || 0)
-  ).flatMap((prompt3) => {
-    const promptId = asString(prompt3.promptId);
-    if (!promptId || conversationPromptIds.has(promptId)) return [];
-    const title = trimString(prompt3.title);
-    const message = trimString(prompt3.message);
-    const assistantContent = message || title || "Input required";
-    const openedAt = asNumber(prompt3.openedAt) || 0;
-    const answeredAt = asNumber(prompt3.answeredAt) || openedAt;
-    const entries = [
-      {
-        id: `prompt:${promptId}:assistant`,
-        role: "assistant",
-        content: assistantContent,
-        timestamp: openedAt,
-        jobId,
-        promptId,
-        historyContent: `[Assistant reply]
-${assistantContent}`,
-        source: "job_prompt"
-      }
-    ];
-    if (Object.prototype.hasOwnProperty.call(prompt3, "answer")) {
+function buildSessionTranscriptFromFeedItems(input) {
+  const artifactsById = artifactRecordsById(input.liveDoc);
+  const entries = [];
+  for (const item of [...input.items].sort(
+    (left, right) => left.sequence - right.sequence
+  )) {
+    if (item.kind === "feedback") continue;
+    if (item.kind === "message") {
+      if (item.payload.role === "system") continue;
+      const content = item.payload.text;
       entries.push({
-        id: `prompt:${promptId}:user`,
-        role: "user",
-        content: stringifyTranscriptValue(prompt3.answer, ""),
-        timestamp: answeredAt,
-        jobId,
-        promptId,
-        source: "job_prompt"
+        id: item.id,
+        role: item.payload.role,
+        content,
+        timestamp: item.occurredAt,
+        sequence: item.sequence,
+        jobId: item.source?.jobId,
+        promptId: item.payload.inReplyToPromptId,
+        historyContent: item.payload.role === "assistant" ? `[Assistant reply]
+${content}` : void 0,
+        source: "feed"
       });
+      continue;
     }
-    return entries;
-  });
-}
-function normalizeAgentMessageEntries(jobId, rawMessages, artifactsById) {
-  return asArray(rawMessages).map((value) => asRecord3(value)).filter((value) => Boolean(value)).sort(
-    (left, right) => (asNumber(left.timestamp) || asNumber(left.ts) || 0) - (asNumber(right.timestamp) || asNumber(right.ts) || 0)
-  ).flatMap((message) => {
-    const messageId = asString(message.messageId) || asString(message.id) || crypto.randomUUID();
-    const timestamp = asNumber(message.timestamp) || asNumber(message.ts) || 0;
-    const reply = trimString(
-      message.reply ?? message.message ?? message.text ?? message.content
-    );
-    const show = normalizeShowRefs(message.show);
-    const entries = [];
-    if (reply) {
+    if (item.kind === "prompt") {
+      const content = item.payload.message || item.payload.title;
       entries.push({
-        id: `agent:${messageId}:text`,
+        id: item.id,
         role: "assistant",
-        content: reply,
-        timestamp,
-        jobId,
+        content,
+        timestamp: item.occurredAt,
+        sequence: item.sequence,
+        jobId: item.source?.jobId,
+        promptId: item.payload.promptId,
         historyContent: `[Assistant reply]
-${reply}`,
-        source: "job_agent_message"
-      });
-    }
-    if (show) {
-      entries.push({
-        id: `agent:${messageId}:artifacts`,
-        role: "assistant",
-        content: "",
-        timestamp,
-        jobId,
-        show,
-        historyContent: buildArtifactHistory(show, artifactsById),
-        source: "job_agent_message"
+${content}`,
+        source: "feed"
       });
+      continue;
     }
-    return entries;
-  });
-}
-function buildJobFallbackEntries(jobId, job2, sessionHeap, artifactsById) {
-  const timestamp = asNumber(job2.finishedAt) || asNumber(job2.startedAt) || asNumber(job2.submittedAt) || 0;
-  const resultPreview = stringifyTranscriptValue(
-    job2.result,
-    "No job result recorded."
-  );
-  const presentation = resolveJobPresentation({
-    jobId,
-    result: job2.result,
-    stdout: [],
-    sessionHeap
-  });
-  const entries = [];
-  const responseText = presentation.responseText || "";
-  if (responseText) {
-    entries.push({
-      id: `job:${jobId}:result-text`,
-      role: "assistant",
-      content: responseText,
-      timestamp,
-      jobId,
-      historyContent: `[Assistant reply]
-${responseText}`,
-      source: "job_result"
-    });
-  }
-  const show = {
-    entryPaths: presentation.entries.map((entry) => entry.path),
-    listNames: presentation.lists.map((list) => list.name)
-  };
-  if (show.entryPaths && show.entryPaths.length > 0 || show.listNames && show.listNames.length > 0) {
+    const show = feedItemShow(item);
+    if (!show) continue;
     entries.push({
-      id: `job:${jobId}:result-artifacts`,
+      id: item.id,
       role: "assistant",
       content: "",
-      timestamp,
-      jobId,
+      timestamp: item.occurredAt,
+      sequence: item.sequence,
+      jobId: item.source?.jobId,
       show,
       historyContent: buildArtifactHistory(show, artifactsById),
-      source: "job_result"
-    });
-  }
-  if (entries.length === 0 && trimString(job2.error)) {
-    entries.push({
-      id: `job:${jobId}:result-error`,
-      role: "assistant",
-      content: trimString(job2.error),
-      timestamp,
-      jobId,
-      historyContent: `[Assistant reply]
-${trimString(job2.error)}`,
-      source: "job_result"
-    });
-  }
-  if (entries.length === 0 && resultPreview && resultPreview !== "No job result recorded.") {
-    entries.push({
-      id: `job:${jobId}:result-preview`,
-      role: "assistant",
-      content: resultPreview,
-      timestamp,
-      jobId,
-      historyContent: `[Assistant reply]
-${resultPreview}`,
-      source: "job_result"
+      source: "feed"
     });
   }
   return entries;
 }
-function buildJobCodeEntry(jobId, job2) {
-  const code = trimString(job2.source);
-  if (!code) return null;
-  const jobStatus = asString(job2.status);
-  const error2 = jobStatus === "failed" || jobStatus === "canceled" || jobStatus === "timeout" ? trimString(job2.error) || `Job ${jobStatus}` : void 0;
-  return {
-    id: `job:${jobId}:code`,
-    role: "assistant",
-    content: "",
-    timestamp: asNumber(job2.submittedAt) || asNumber(job2.startedAt) || asNumber(job2.finishedAt) || 0,
-    jobId,
-    code,
-    jobStatus,
-    jobResultPreview: stringifyTranscriptValue(
-      job2.result,
-      "No job result recorded."
-    ),
-    error: error2,
-    source: "job_code"
-  };
-}
+var CANONICAL_FEED_REQUIRED = "Canonical session feed-v1 is required; past message/job transcript reconstruction is not supported.";
 function buildSessionTranscript(input) {
   const liveDoc = input.liveDoc || null;
-  const sessionHeap = input.sessionHeap || EMPTY_HEAP;
-  const artifactsById = artifactRecordsById(liveDoc);
-  const transcript = [];
-  const conversationMessages = asArray(
-    asRecord3(liveDoc?.conversation)?.messages
-  ).map((message) => normalizeConversationMessage(message, artifactsById)).filter((message) => Boolean(message));
-  const conversationPromptIds = new Set(
-    conversationMessages.map((message) => message.promptId).filter((promptId) => Boolean(promptId))
-  );
-  const assistantConversationJobIds = new Set(
-    conversationMessages.filter(
-      (message) => message.role === "assistant" && Boolean(message.jobId)
-    ).map((message) => message.jobId)
-  );
-  transcript.push(...conversationMessages);
-  const jobsById = asRecord3(asRecord3(liveDoc?.jobs)?.byId) || {};
-  const jobs = Object.values(jobsById).map((value) => asRecord3(value)).filter((value) => Boolean(value)).sort(
-    (left, right) => (asNumber(left.submittedAt) || asNumber(left.startedAt) || asNumber(left.finishedAt) || 0) - (asNumber(right.submittedAt) || asNumber(right.startedAt) || asNumber(right.finishedAt) || 0)
-  );
-  for (const job2 of jobs) {
-    const jobId = asString(job2.jobId);
-    if (!jobId) continue;
-    const codeEntry = buildJobCodeEntry(jobId, job2);
-    if (codeEntry) {
-      transcript.push(codeEntry);
-    }
-    transcript.push(
-      ...normalizePromptEntries(jobId, job2.prompts, conversationPromptIds)
-    );
-    if (!assistantConversationJobIds.has(jobId)) {
-      const agentEntries = normalizeAgentMessageEntries(
-        jobId,
-        job2.agentMessages,
-        artifactsById
-      );
-      if (agentEntries.length > 0) {
-        transcript.push(...agentEntries);
-      } else {
-        transcript.push(
-          ...buildJobFallbackEntries(
-            jobId,
-            job2,
-            sessionHeap,
-            artifactsById
-          )
-        );
-      }
-    }
-  }
-  return transcript.sort((left, right) => {
-    if (left.timestamp !== right.timestamp) {
-      return left.timestamp - right.timestamp;
-    }
-    return left.id.localeCompare(right.id);
+  if (!isCanonicalSessionFeedDocument(liveDoc)) {
+    throw new Error(CANONICAL_FEED_REQUIRED);
+  }
+  const snapshot = readSessionFeedSnapshot(liveDoc);
+  if (snapshot.error) throw snapshot.error;
+  return buildSessionTranscriptFromFeedItems({
+    items: input.canonicalFeedItems || snapshot.tail,
+    liveDoc
   });
 }
 
@@ -22547,7 +23647,7 @@ function normalizeEffectBehaviors(value) {
 }
 function resolveInvocationMode(context) {
   const mode = context?.invocation?.mode;
-  if (mode === "dryRun" || mode === "reverse") {
+  if (mode === "dryRun" || mode === "reverse" || mode === "artifactOptions") {
     return mode;
   }
   return "execute";
@@ -22601,6 +23701,18 @@ function resolveHandlerForMode(effectMap, effect, request) {
     request.context?.behaviors || effect.metamodels || void 0
   );
   const mode = resolveInvocationMode(request.context);
+  if (mode === "artifactOptions") {
+    if (!effect.artifactOptionsHandler) {
+      throw new Error(
+        `Artifact relationship options are not supported for ${request.effectKey}`
+      );
+    }
+    return {
+      effect,
+      mode,
+      handler: effect.artifactOptionsHandler
+    };
+  }
   if (mode === "dryRun") {
     if (effect.dryRunHandler) {
       return { effect, mode, handler: effect.dryRunHandler };
@@ -22633,7 +23745,91 @@ function resolveHandlerForMode(effectMap, effect, request) {
   }
   return { effect, mode, handler: effect.handler };
 }
-async function invokeRegisteredEffect(effectMap, request) {
+function createInvocationFeedbackContext(bridge) {
+  const publications = [];
+  let nextOperationOrdinal = 0;
+  const nextOperationId = (kind) => `${kind}:${nextOperationOrdinal++}`;
+  const track = (publication) => {
+    const tracked = Promise.resolve(publication);
+    publications.push(tracked);
+    void tracked.catch(() => void 0);
+    return tracked;
+  };
+  const publisher = createFeedPublisher(
+    (method, params) => bridge.publish(method, {
+      ...params,
+      invocationId: bridge.invocationId
+    })
+  );
+  const wrapTransientHandle = (initial) => {
+    let current = initial;
+    const wrapped = {
+      get id() {
+        return current.id;
+      },
+      get ordinal() {
+        return current.ordinal;
+      },
+      get revision() {
+        return current.revision;
+      },
+      async update(text, options = {}) {
+        current = await track(
+          current.update(text, {
+            ...options,
+            operationId: options.operationId || nextOperationId("transient-update")
+          })
+        );
+        return wrapped;
+      },
+      settle(text, options = {}) {
+        return track(
+          current.settle(text, {
+            ...options,
+            operationId: options.operationId || nextOperationId("transient-settle")
+          })
+        );
+      }
+    };
+    return wrapped;
+  };
+  return {
+    feedback(text, options = {}) {
+      return track(
+        publisher.feedback(text, {
+          ...options,
+          operationId: options.operationId || nextOperationId("feedback")
+        })
+      );
+    },
+    transientFeedback(text, options = {}) {
+      return track(
+        publisher.transientFeedback(text, {
+          ...options,
+          operationId: options.operationId || nextOperationId("transient-create")
+        }).then(wrapTransientHandle)
+      );
+    },
+    async flush() {
+      let cursor = 0;
+      let firstError;
+      while (cursor < publications.length) {
+        const batch = publications.slice(cursor);
+        cursor = publications.length;
+        const results = await Promise.allSettled(batch);
+        for (const result of results) {
+          if (result.status === "rejected" && firstError === void 0) {
+            firstError = result.reason;
+          }
+        }
+      }
+      if (firstError !== void 0) {
+        throw firstError;
+      }
+    }
+  };
+}
+async function invokeRegisteredEffect(effectMap, request, options = {}) {
   const effect = selectRegisteredEffect(
     effectMap,
     request.effectKey,
@@ -22652,14 +23848,49 @@ async function invokeRegisteredEffect(effectMap, request) {
       mode: resolved.mode,
       sourceEffectKey: request.effectKey,
       sourceEffectName: request.effectName,
-      ...request.context?.invocation?.reverseHandler ? { reverseHandler: request.context.invocation.reverseHandler } : {}
+      ...request.context?.invocation?.reverseHandler ? { reverseHandler: request.context.invocation.reverseHandler } : {},
+      ...request.context?.invocation?.artifactId ? { artifactId: request.context.invocation.artifactId } : {},
+      ...request.context?.invocation?.artifactOptions ? { artifactOptions: request.context.invocation.artifactOptions } : {}
     }
   };
-  if (resolved.effect.className && !resolved.effect.static && request.input && typeof request.input === "object" && "_objectId" in request.input) {
-    const { _objectId, ...rest } = request.input;
-    return resolved.handler(_objectId, rest, context);
+  const feedbackContext = options.feedback ? createInvocationFeedbackContext(options.feedback) : null;
+  if (feedbackContext) {
+    context.feedback = feedbackContext.feedback;
+    context.transientFeedback = feedbackContext.transientFeedback;
+  }
+  let handlerResult;
+  let handlerError;
+  let handlerFailed = false;
+  try {
+    if (resolved.mode === "artifactOptions") {
+      handlerResult = await resolved.handler(request.input, context);
+    } else if (resolved.effect.className && !resolved.effect.static && request.input && typeof request.input === "object" && "_objectId" in request.input) {
+      const { _objectId, ...rest } = request.input;
+      handlerResult = await resolved.handler(_objectId, rest, context);
+    } else {
+      handlerResult = await resolved.handler(request.input, context);
+    }
+  } catch (error2) {
+    handlerFailed = true;
+    handlerError = error2;
+  }
+  let feedbackError;
+  let feedbackFailed = false;
+  if (feedbackContext) {
+    try {
+      await feedbackContext.flush();
+    } catch (error2) {
+      feedbackFailed = true;
+      feedbackError = error2;
+    }
+  }
+  if (handlerFailed) {
+    throw handlerError;
+  }
+  if (feedbackFailed) {
+    throw feedbackError;
   }
-  return resolved.handler(request.input, context);
+  return handlerResult;
 }
 
 // src/client-normalizers.ts
@@ -22986,6 +24217,36 @@ function buildEffectMetamodelMutations(toolPath, spec) {
 var DEFAULT_CONVERSATION_SESSION_LIST_LIMIT = 100;
 var MAX_CONVERSATION_SESSION_LIST_LIMIT = 500;
 var MAX_CONVERSATION_SESSION_LIST_OFFSET = 1e5;
+function requireUserEnvironmentSequence(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new Error(
+      `Invalid user-environment state: ${field} must be a non-negative safe integer.`
+    );
+  }
+  return value;
+}
+function normalizeReadThroughSequenceMap(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      "Invalid user-environment state: readThroughSequenceBySessionId is required."
+    );
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([sessionId, sequence]) => [
+      sessionId,
+      requireUserEnvironmentSequence(
+        sequence,
+        `readThroughSequenceBySessionId.${sessionId}`
+      )
+    ])
+  );
+}
+function requiredAssistantReplyString(value, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`Assistant reply ${field} must be a non-empty string.`);
+  }
+  return field === "text" ? value : value.trim();
+}
 function boundedSessionListInteger(value, name, fallback2, minimum, maximum) {
   if (value === void 0) return fallback2;
   if (!Number.isInteger(value) || value < minimum || value > maximum) {
@@ -24559,12 +25820,55 @@ var Environment = class _Environment {
 var EnvironmentSession = class extends Session {
   environment;
   sessionDataRoutePrefix;
+  sessionDataHeaders;
+  heartbeatTimer = null;
+  heartbeatInFlight = false;
   /** The last known graph container status, updated by checkReadiness() or on heartbeat */
   graphContainerStatus = null;
   constructor(client, environment, clientId, options = {}) {
     super(client, clientId, { initialQuota: options.initialQuota });
     this.environment = environment;
     this.sessionDataRoutePrefix = options.sessionDataRoutePrefix || "/orchestrator/ws/sessions";
+    this.sessionDataHeaders = options.sessionDataHeaders || {};
+    this.setFeedListTransport(
+      (feedOptions) => this.sessionDataRequest("/feed", feedOptions)
+    );
+  }
+  /**
+   * Keep the browser session transport observable from the client side.
+   * A worker/proxy restart can leave a browser WebSocket appearing OPEN even
+   * though the server-side Durable Object has already closed its peer. The
+   * heartbeat gives the SDK a bounded failure signal so it can revoke that
+   * stale socket and use WSClient's normal reconnect path.
+   */
+  startHeartbeat() {
+    if (this.heartbeatTimer) return;
+    this.heartbeatTimer = setInterval(() => {
+      if (this.heartbeatInFlight) return;
+      this.heartbeatInFlight = true;
+      void this.client.call("client.heartbeat", {}).then((result) => {
+        if (result?.graphContainerStatus) {
+          this.graphContainerStatus = result.graphContainerStatus;
+        }
+      }).catch((error2) => {
+        this.client.reportTransportFailure(error2);
+      }).finally(() => {
+        this.heartbeatInFlight = false;
+      });
+    }, 5e3);
+    this.heartbeatTimer.unref?.();
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    this.heartbeatInFlight = false;
+  }
+  async hello() {
+    const result = await super.hello();
+    this.startHeartbeat();
+    return result;
   }
   get environmentId() {
     return this.environment.environmentId;
@@ -24624,6 +25928,11 @@ var EnvironmentSession = class extends Session {
         const response = await fetch(url, {
           method: init2.method || "GET",
           headers,
+          // Session documents, feed pages, and artifact reads are live
+          // Automerge-backed state. A browser cache entry for the identical
+          // artifact URL can otherwise make the Dock poll the same stale
+          // `running` record until a full reload revalidates it.
+          cache: "no-store",
           ...typeof init2.body === "undefined" ? {} : { body: init2.body }
         });
         if (response.ok) {
@@ -24652,34 +25961,50 @@ var EnvironmentSession = class extends Session {
     const body = typeof init2.body === "undefined" ? void 0 : JSON.stringify(init2.body);
     const response = await this.sessionDataFetch(path7, query, {
       method: init2.method || "GET",
-      headers: { "Content-Type": "application/json" },
+      headers: {
+        ...this.sessionDataHeaders,
+        "Content-Type": "application/json"
+      },
       ...typeof body === "undefined" ? {} : { body }
     });
     return response.json();
   }
-  async collectAllSessionItems(listPage) {
-    const items = [];
-    let cursor = null;
-    do {
-      const page = await listPage({ limit: 500, cursor });
-      items.push(...page.items);
-      cursor = page.nextCursor;
-    } while (cursor);
-    return items;
-  }
   /**
    * Fetch the live session document from the runtime DO.
    *
-   * For history and saved artifacts, prefer the collection APIs on
-   * `messages`, `timeline`, `jobs`, and `heap`.
+   * For presentation history use `feed.list()` or `transcript.list()`.
+   * Timeline and job collections are diagnostic/execution data only.
    */
   async getDocument() {
     return this.sessionDataRequest("/document");
   }
-  get messages() {
-    return {
-      list: (options = {}) => this.sessionDataRequest("/messages", options)
-    };
+  /**
+   * Publish one terminal assistant reply from a trusted server integration.
+   *
+   * This uses the API-key-authenticated HTTP session boundary. Delegated
+   * browser sessions cannot use it and never receive assistant feed-authoring
+   * capability through their WebSocket.
+   */
+  async publishAssistantReply(input) {
+    if (this.sessionDataRoutePrefix === "/sdk/browser-sessions") {
+      throw new Error(
+        "Assistant replies require a server API-key session connection."
+      );
+    }
+    const id = requiredAssistantReplyString(input.id, "id");
+    const operationId2 = requiredAssistantReplyString(
+      input.operationId,
+      "operationId"
+    );
+    const text = requiredAssistantReplyString(input.text, "text");
+    return this.sessionDataRequest(
+      "/assistant-replies",
+      void 0,
+      {
+        method: "POST",
+        body: { id, operationId: operationId2, text }
+      }
+    );
   }
   get timeline() {
     return {
@@ -24721,7 +26046,12 @@ var EnvironmentSession = class extends Session {
         latestJob: true
       }),
       get: (artifactId) => this.sessionDataRequest(
-        `/artifacts/${encodeURIComponent(artifactId)}`
+        `/artifacts/${encodeURIComponent(artifactId)}`,
+        // The artifact endpoint is polled while an effect is running. Keep
+        // each read addressable as a fresh resource as well as using
+        // `cache: no-store`; this also bypasses intermediaries that ignore
+        // the Fetch cache directive for an otherwise identical GET URL.
+        { _granularLiveRead: Date.now() }
       ),
       create: (artifact) => this.sessionDataRequest(
         "/artifacts",
@@ -24731,6 +26061,14 @@ var EnvironmentSession = class extends Session {
           body: artifact
         }
       ),
+      acceptSuggestion: (sequence) => this.sessionDataRequest(
+        "/artifacts/suggestions/accept",
+        void 0,
+        {
+          method: "POST",
+          body: { sequence }
+        }
+      ),
       updateInputs: (artifactId, patch) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}`,
         void 0,
@@ -24739,6 +26077,16 @@ var EnvironmentSession = class extends Session {
           body: patch
         }
       ),
+      relationshipOptions: (artifactId, input) => this.sessionDataRequest(
+        `/artifacts/${encodeURIComponent(artifactId)}/relationship-options`,
+        void 0,
+        { method: "POST", body: input }
+      ),
+      relationshipCreate: (artifactId, input) => this.sessionDataRequest(
+        `/artifacts/${encodeURIComponent(artifactId)}/relationship-create`,
+        void 0,
+        { method: "POST", body: input }
+      ),
       validate: (artifactId) => this.sessionDataRequest(
         `/artifacts/${encodeURIComponent(artifactId)}/validate`,
         void 0,
@@ -24876,73 +26224,50 @@ var EnvironmentSession = class extends Session {
   get transcript() {
     return {
       list: async (options = {}) => {
-        const [messages, jobs, entries, lists, artifacts] = await Promise.all([
-          this.collectAllSessionItems(this.messages.list),
-          this.collectAllSessionItems(
-            (pageOptions) => this.jobs.list({ ...pageOptions, status: "all" })
-          ),
-          this.collectAllSessionItems(this.heap.entries.list),
-          this.collectAllSessionItems(this.heap.lists.list),
-          this.collectAllSessionItems(
-            (pageOptions) => this.artifacts.list({ ...pageOptions, status: "all" })
-          )
-        ]);
-        const liveDoc = {
-          conversation: { messages },
-          jobs: {
-            byId: Object.fromEntries(
-              jobs.map((job2) => {
-                const record = job2 && typeof job2 === "object" ? job2 : null;
-                const id = typeof record?.jobId === "string" ? record.jobId : typeof record?.id === "string" ? record.id : null;
-                return id ? [id, record] : null;
-              }).filter(
-                (entry) => Boolean(entry)
-              )
-            )
-          },
-          artifacts: {
-            byId: Object.fromEntries(
-              artifacts.map((artifact) => {
-                return artifact?.artifactId ? [
-                  artifact.artifactId,
-                  artifact
-                ] : null;
-              }).filter(
-                (entry) => Boolean(entry)
-              )
-            ),
-            order: artifacts.map((artifact) => artifact?.artifactId).filter(
-              (artifactId) => Boolean(artifactId)
-            )
+        if (!isCanonicalSessionFeedDocument(this.document)) {
+          throw new Error(
+            "Canonical session feed-v1 is required; transcript.list() does not reconstruct past message or job collections."
+          );
+        }
+        const canonicalFeedItems = [];
+        let afterSequence = 0;
+        let pageCount = 0;
+        for (; ; ) {
+          if (++pageCount > 1e4) {
+            throw new Error(
+              "Canonical transcript history exceeded its page limit."
+            );
           }
-        };
-        const heap = normalizeHeapSnapshot({
-          entriesByPath: Object.fromEntries(
-            entries.map((entry) => {
-              return entry?.path ? [entry.path, entry] : null;
-            }).filter(
-              (entry) => Boolean(entry)
-            )
-          ),
-          listsByName: Object.fromEntries(
-            lists.map((list) => {
-              return list?.name ? [list.name, list] : null;
-            }).filter(
-              (entry) => Boolean(entry)
-            )
-          ),
-          variablesByName: this.getHeap().variablesByName,
-          updatedAt: Date.now()
-        });
+          const page = await this.feed.list({
+            afterSequence,
+            limit: 500
+          });
+          if (page.items.length === 0) {
+            if (page.hasMoreAfter) {
+              throw new Error(
+                `Canonical transcript history stopped after sequence ${afterSequence}.`
+              );
+            }
+            break;
+          }
+          if (page.items[0].sequence !== afterSequence + 1) {
+            throw new Error(
+              `Canonical transcript history has a gap after sequence ${afterSequence}.`
+            );
+          }
+          canonicalFeedItems.push(...page.items);
+          afterSequence = page.items[page.items.length - 1].sequence;
+          if (!page.hasMoreAfter) break;
+        }
         const allItems = buildSessionTranscript({
-          liveDoc,
-          sessionHeap: heap
+          liveDoc: this.document,
+          canonicalFeedItems
         });
         const limit = Math.max(
           1,
           Math.min(500, Math.floor(options.limit ?? 100))
         );
-        const offset = typeof options.cursor === "string" ? Number.parseInt(options.cursor, 10) || 0 : 0;
+        const offset = options.latest ? Math.max(0, allItems.length - limit) : typeof options.cursor === "string" ? Number.parseInt(options.cursor, 10) || 0 : 0;
         const items = allItems.slice(offset, offset + limit);
         const nextOffset = offset + items.length;
         return {
@@ -25028,6 +26353,8 @@ var EnvironmentSession = class extends Session {
    * acknowledgement was observed.
    */
   async disconnect() {
+    this.stopHeartbeat();
+    this.disposeSessionFeed();
     let wsNotifiedRuntime = false;
     try {
       const goodbye = await this.rpc(
@@ -25066,6 +26393,7 @@ var EnvironmentSession = class extends Session {
    * Close only the socket transport without sending `client.goodbye`.
    */
   disconnectTransport() {
+    this.stopHeartbeat();
     this.client.disconnect({ reason: "Transport detach" });
   }
   /**
@@ -25530,24 +26858,72 @@ var Granular = class _Granular {
     if (!tagName) {
       throw new Error(`${methodName}() requires \`tag\`.`);
     }
-    const user = await this.resolveConnectUser(options);
-    if (!Array.isArray(user.permissions) || user.permissions.length === 0) {
+    const assignmentMode = options.assignmentMode ?? "ensure";
+    if (assignmentMode !== "ensure" && assignmentMode !== "require-existing") {
       throw new Error(
-        `${methodName}() requires at least one permission so the SDK can ensure assignments for new users.`
+        `${methodName}() received an unsupported assignmentMode: ${String(options.assignmentMode)}.`
       );
     }
-    const sandbox = await this.findOrCreateSandbox(ontology);
-    for (const profileName of user.permissions) {
-      const profileId = await this.ensurePermissionProfile(
-        sandbox.sandboxId,
-        profileName
+    const requiredGranularId = options.granularId?.trim();
+    if (assignmentMode === "require-existing" && (!requiredGranularId || options.userId || options.user)) {
+      throw new Error(
+        `${methodName}() with assignmentMode "require-existing" requires granularId and does not accept userId or user.`
       );
-      await this.ensureAssignment(
-        user.granularId,
-        sandbox.sandboxId,
-        profileId
+    }
+    const user = await this.resolveConnectUser(
+      assignmentMode === "require-existing" ? { ...options, granularId: requiredGranularId } : options
+    );
+    let requiredPermissionProfileId = null;
+    const sandbox = assignmentMode === "require-existing" ? { sandboxId: await this._resolveSandboxId(ontology) } : await this.findOrCreateSandbox(ontology);
+    if (assignmentMode === "require-existing") {
+      const assignments = await this.subjects.listAssignments(user.granularId);
+      const assignment = assignments.items.find(
+        (item) => item.sandboxId === sandbox.sandboxId
       );
+      if (!assignment) {
+        throw new Error(
+          `${methodName}() requires an existing assignment for subject ${user.granularId} in ontology ${sandbox.sandboxId}.`
+        );
+      }
+      const assignedPermissionProfileId = assignment.permissionProfileId?.trim();
+      if (!assignedPermissionProfileId) {
+        throw new Error(
+          `${methodName}() found an invalid assignment without a permission profile for subject ${user.granularId} in ontology ${sandbox.sandboxId}.`
+        );
+      }
+      const expectedPermissionProfileId = options.expectedPermissionProfileId?.trim();
+      if (expectedPermissionProfileId && assignedPermissionProfileId !== expectedPermissionProfileId) {
+        throw new Error(
+          `${methodName}() assignment mismatch for subject ${user.granularId}: expected permission profile ${expectedPermissionProfileId}, received ${assignedPermissionProfileId}.`
+        );
+      }
+      requiredPermissionProfileId = assignedPermissionProfileId;
+    } else {
+      if (!Array.isArray(user.permissions) || user.permissions.length === 0) {
+        throw new Error(
+          `${methodName}() requires at least one permission so the SDK can ensure assignments for new users.`
+        );
+      }
+      for (const profileName of user.permissions) {
+        const profileId = await this.ensurePermissionProfile(
+          sandbox.sandboxId,
+          profileName
+        );
+        await this.ensureAssignment(
+          user.granularId,
+          sandbox.sandboxId,
+          profileId
+        );
+      }
     }
+    const requireMatchingEnvironmentProfile = (environment2) => {
+      if (requiredPermissionProfileId && environment2.permissionProfileId !== requiredPermissionProfileId) {
+        throw new Error(
+          `${methodName}() resolved environment ${environment2.environmentId} with permission profile ${environment2.permissionProfileId || "none"}; current assignment requires ${requiredPermissionProfileId}.`
+        );
+      }
+      return environment2;
+    };
     const tags = await this.request(
       `/control/sandboxes/${sandbox.sandboxId}/tags`
     );
@@ -25570,6 +26946,9 @@ var Granular = class _Granular {
     const resolveActive = async (operationKey) => {
       const query = new URLSearchParams({ tagId: tag2.tagId, slot });
       if (operationKey) query.set("operationKey", operationKey);
+      if (requiredPermissionProfileId) {
+        query.set("expectedPermissionProfileId", requiredPermissionProfileId);
+      }
       try {
         const payload = await this.request(
           `/control/sandboxes/${encodeURIComponent(sandbox.sandboxId)}/subjects/${encodeURIComponent(user.granularId)}/active-environment?${query.toString()}`
@@ -25593,7 +26972,8 @@ var Granular = class _Granular {
             tagId: tag2.tagId,
             slot,
             operationKey: resetKey,
-            operation: resetKey ? "explicit_reset" : void 0
+            operation: resetKey ? "explicit_reset" : void 0,
+            expectedPermissionProfileId: requiredPermissionProfileId || void 0
           })
         }
       );
@@ -25603,7 +26983,7 @@ var Granular = class _Granular {
       const resetEnvironment = await resolveActive(resetKey);
       if (resetEnvironment) {
         return {
-          environment: resetEnvironment,
+          environment: requireMatchingEnvironmentProfile(resetEnvironment),
           requestedOntology: ontology,
           sandboxId: sandbox.sandboxId,
           subjectId: user.granularId,
@@ -25619,7 +26999,7 @@ var Granular = class _Granular {
       const active = await resolveActive();
       if (active && (active.versionId === targetVersionId || options.createFreshIfOutdated !== true)) {
         return {
-          environment: active,
+          environment: requireMatchingEnvironmentProfile(active),
           requestedOntology: ontology,
           sandboxId: sandbox.sandboxId,
           subjectId: user.granularId,
@@ -25637,7 +27017,10 @@ var Granular = class _Granular {
       )
     );
     if (!resetKey && currentMatches.length > 0) {
-      const environment2 = await activate(currentMatches[0]);
+      requireMatchingEnvironmentProfile(currentMatches[0]);
+      const environment2 = requireMatchingEnvironmentProfile(
+        await activate(currentMatches[0])
+      );
       return {
         environment: environment2,
         requestedOntology: ontology,
@@ -25650,7 +27033,10 @@ var Granular = class _Granular {
       userEnvironments.filter((environment2) => environment2.tagId === tag2.tagId)
     );
     if (outdatedMatches.length > 0 && options.createFreshIfOutdated !== true) {
-      const environment2 = await activate(outdatedMatches[0]);
+      requireMatchingEnvironmentProfile(outdatedMatches[0]);
+      const environment2 = requireMatchingEnvironmentProfile(
+        await activate(outdatedMatches[0])
+      );
       return {
         environment: environment2,
         requestedOntology: ontology,
@@ -25669,7 +27055,10 @@ var Granular = class _Granular {
       tagId: tag2.tagId,
       permissionProfileId: null
     });
-    const environment = await activate(created);
+    requireMatchingEnvironmentProfile(created);
+    const environment = requireMatchingEnvironmentProfile(
+      await activate(created)
+    );
     return {
       environment,
       requestedOntology: ontology,
@@ -25769,16 +27158,22 @@ var Granular = class _Granular {
     return this.normalizeUserEnvironmentState(state);
   }
   async markUserEnvironmentSessionsRead(options) {
+    const readThroughSequence = requireUserEnvironmentSequence(
+      options.readThroughSequence,
+      "readThroughSequence"
+    );
     const result = await this.request("/sdk/user-environment-state/read", {
       method: "POST",
       body: JSON.stringify({
         environmentId: options.environmentId,
         sessionId: options.sessionId,
         sessionIds: options.sessionIds,
-        readAt: options.readAt
+        readThroughSequence
       })
     });
-    return result.readAtBySessionId || {};
+    return normalizeReadThroughSequenceMap(
+      result.readThroughSequenceBySessionId
+    );
   }
   normalizeConversationSession(row) {
     const sessionId = String(row.sessionId ?? row.session_id ?? "");
@@ -25803,21 +27198,48 @@ var Granular = class _Granular {
     };
   }
   normalizeUserEnvironmentState(state) {
+    if (!Array.isArray(state.sessions)) {
+      throw new Error(
+        "Invalid user-environment state: sessions must be an array."
+      );
+    }
+    const sessions = state.sessions.map((item, index) => ({
+      ...item,
+      readThroughSequence: requireUserEnvironmentSequence(
+        item?.readThroughSequence,
+        `sessions[${index}].readThroughSequence`
+      ),
+      messagePreview: {
+        ...item.messagePreview,
+        latestMessageSequence: requireUserEnvironmentSequence(
+          item.messagePreview?.latestMessageSequence,
+          `sessions[${index}].messagePreview.latestMessageSequence`
+        ),
+        latestAssistantSequence: requireUserEnvironmentSequence(
+          item.messagePreview?.latestAssistantSequence,
+          `sessions[${index}].messagePreview.latestAssistantSequence`
+        ),
+        unreadProducingSequence: requireUserEnvironmentSequence(
+          item.messagePreview?.unreadProducingSequence,
+          `sessions[${index}].messagePreview.unreadProducingSequence`
+        )
+      },
+      session: this.normalizeConversationSession(
+        item.session
+      )
+    }));
     return {
       ...state,
-      sessions: Array.isArray(state.sessions) ? state.sessions.map((item) => ({
-        ...item,
-        session: this.normalizeConversationSession(
-          item.session
-        )
-      })) : [],
+      sessions,
       attention: {
         prompts: Array.isArray(state.attention?.prompts) ? state.attention.prompts : [],
         count: typeof state.attention?.count === "number" ? state.attention.count : 0,
         activePrompt: state.attention?.activePrompt || null
       },
       unreadCount: typeof state.unreadCount === "number" ? state.unreadCount : 0,
-      readAtBySessionId: state.readAtBySessionId || {}
+      readThroughSequenceBySessionId: normalizeReadThroughSequenceMap(
+        state.readThroughSequenceBySessionId
+      )
     };
   }
   static coerceIsoDate(value) {
@@ -25848,7 +27270,9 @@ var Granular = class _Granular {
         environmentId: options.environmentId,
         clientId,
         sessionScope,
-        capabilities: sessionScope ? { sessionScope } : void 0,
+        capabilities: {
+          ...sessionScope ? { sessionScope } : {}
+        },
         initialHeap: options.initialHeap
       })
     });
@@ -25879,22 +27303,16 @@ var Granular = class _Granular {
       metadata: options?.metadata
     });
   }
-  /**
-   * Mark a session closed in the control plane. If `environment` is the connected handle for that
-   * `sessionId`, disconnects the WebSocket so the runtime tears down cleanly.
-   */
+  /** End a session through the runtime, or disconnect its connected handle. */
   async closeSession(sessionId, environment) {
     if (environment && environment.sessionId === sessionId) {
       await environment.disconnect();
       return;
     }
-    await this.request(`/control/sessions/${encodeURIComponent(sessionId)}`, {
-      method: "PATCH",
-      body: JSON.stringify({
-        status: "closed",
-        lastSeenAt: (/* @__PURE__ */ new Date()).toISOString()
-      })
-    });
+    await this.request(
+      `/control/sessions/${encodeURIComponent(sessionId)}/close`,
+      { method: "POST" }
+    );
   }
   /**
    * Re-open a closed session in the index and connect to its existing runtime document.
@@ -26224,6 +27642,21 @@ var Granular = class _Granular {
           reconnectError
         );
         console.error("[Granular] Original heartbeat failure:", error2);
+        if (this.onReconnectError) {
+          try {
+            this.onReconnectError({
+              sessionId: `effect-host:${host.effectClientId}`,
+              error: reconnectError instanceof Error ? reconnectError.message : String(reconnectError),
+              timestamp: Date.now(),
+              terminal: false
+            });
+          } catch (callbackError) {
+            console.error(
+              "[Granular] onReconnectError callback failed after effect-host recovery failure:",
+              callbackError
+            );
+          }
+        }
       }
     );
   }
@@ -26326,7 +27759,13 @@ var Granular = class _Granular {
         const request = params;
         return invokeRegisteredEffect(
           this.getSandboxEffectMap(sandboxId),
-          request
+          request,
+          {
+            feedback: {
+              invocationId: request.callId,
+              publish: (method, publishParams) => wsClient.call(method, publishParams)
+            }
+          }
         );
       });
       wsClient.on("open", () => {
@@ -26340,14 +27779,20 @@ var Granular = class _Granular {
       wsClient.on("disconnect", () => {
         this.stopEffectHostHeartbeat(host);
       });
-      await withTimeout(
-        wsClient.connect(),
-        EFFECT_HOST_CONNECT_TIMEOUT_MS,
-        `effect host WebSocket connect for sandbox ${sandboxId}`
-      );
-      await this.synchronizeEffectHost(host);
-      this.sandboxEffectHosts.set(sandboxId, host);
-      return host;
+      try {
+        await withTimeout(
+          wsClient.connect(),
+          EFFECT_HOST_CONNECT_TIMEOUT_MS,
+          `effect host WebSocket connect for sandbox ${sandboxId}`
+        );
+        await this.synchronizeEffectHost(host);
+        this.sandboxEffectHosts.set(sandboxId, host);
+        return host;
+      } catch (error2) {
+        this.stopEffectHostHeartbeat(host);
+        wsClient.disconnect({ reason: "Effect host initialization failed" });
+        throw error2;
+      }
     })();
     this.sandboxEffectHostPromises.set(sandboxId, connectPromise);
     try {
@@ -28104,7 +29549,11 @@ async function tagMoveCommand(tagName, versionId) {
       process.exit(1);
     }
     const previousVersionId = tag2.targetVersionId || tag2.targetBuildId || null;
-    const moved = await api.moveVersionTag(tag2.tagId, versionId);
+    const moved = await api.moveVersionTag(
+      tag2.tagId,
+      versionId,
+      tag2.name === "prod" ? previousVersionId : void 0
+    );
     spin.succeed(`  ${tagName} now points to ${versionId}.`);
     console.log();
     keyValue({