@okostream/mcp 0.12.11 → 0.12.13

package/dist/server.js

@@ -116291,7 +116291,7 @@ function sanitizeScopes(scopes) {
 }
 
 // build/version.js
-var OKO_MCP_VERSION = "0.12.11";
+var OKO_MCP_VERSION = "0.12.13";
 
 // build/auth.js
 var state = null;
@@ -116416,9 +116416,8 @@ async function exchangeApiKey() {
     }
     throw status === 401 ? new OkoAuthError("invalid_key", "OKO API key is invalid or revoked. Create a fresh key in the OKO MCP install center and replace OKO_API_KEY.") : new OkoAuthError("unavailable", [
       `OKO organizer authentication failed with HTTP ${status}.`,
-      serverRefusalNote(errorBody),
-      "Check your connection and try again."
-    ].filter(Boolean).join(" "));
+      serverRefusalNote(errorBody) ?? "Check your connection and try again."
+    ].join(" "));
   }
   const data = await response.json();
   if (typeof data.customToken !== "string") {
@@ -116631,6 +116630,20 @@ var EVENT_ACCESS_FIELD_BY_MODE = {
   moderate: "chatModerators",
   notify: "notificationSenders"
 };
+var EVENT_ACCESS_COMPOSITION_FIELDS = [
+  ...Object.values(EVENT_ACCESS_FIELD_BY_MODE),
+  "moderators",
+  "participantUids"
+];
+function eventDocumentForOutput(data) {
+  const projected = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (EVENT_ACCESS_COMPOSITION_FIELDS.includes(key))
+      continue;
+    projected[key] = value;
+  }
+  return projected;
+}
 function grantAllowsMode(data, mode) {
   const field2 = EVENT_ACCESS_FIELD_BY_MODE[mode];
   return asRecord(data.capabilities)[field2] === true;
@@ -116689,7 +116702,16 @@ var MAX_CARD_BUTTON_LABEL_LENGTH = 80;
 var MAX_CARD_BUTTON_URL_LENGTH = 1e3;
 var MAX_SOURCE_IMAGE_BYTES = 15 * 1024 * 1024;
 var REMOTE_IMAGE_TIMEOUT_MS = 15e3;
+var REMOTE_IMAGE_TOTAL_TIMEOUT_MS = 4e4;
 var REMOTE_IMAGE_MAX_REDIRECTS = 3;
+function remoteImageHopBudget(deadlineAt, now, perHopMs) {
+  const left = deadlineAt - now;
+  if (left <= 0)
+    return { kind: "exhausted" };
+  if (left < perHopMs)
+    return { kind: "budget", ms: left, capped: true };
+  return { kind: "budget", ms: perHopMs, capped: false };
+}
 var ALLOWED_REMOTE_IMAGE_TYPES = /* @__PURE__ */ new Set(["image/jpeg", "image/jpg", "image/png", "image/webp", "image/gif", "image/avif"]);
 function storagePathFromDownloadUrl(downloadUrl) {
   if (!downloadUrl)
@@ -116803,7 +116825,7 @@ function shareLinkHint(url) {
   }
   return " Use a direct link to the image file (right-click the image \u2192 copy image address), or download the file and pass source.path.";
 }
-async function readRemoteImage(rawUrl, redirects = 0, notes = []) {
+async function readRemoteImage(rawUrl, redirects = 0, notes = [], deadlineAt = Date.now() + REMOTE_IMAGE_TOTAL_TIMEOUT_MS) {
   if (redirects > REMOTE_IMAGE_MAX_REDIRECTS) {
     throw new Error("Image URL has too many redirects.");
   }
@@ -116814,21 +116836,28 @@ async function readRemoteImage(rawUrl, redirects = 0, notes = []) {
   }
   let lastConnectError = null;
   for (const candidate of pinned.addresses) {
-    const attempt = await readRemoteImageFrom(url, rawUrl, candidate, redirects);
+    const attempt = await readRemoteImageFrom(url, rawUrl, candidate, redirects, deadlineAt);
     if ("buffer" in attempt)
       return attempt.buffer;
     if ("redirectTo" in attempt)
-      return readRemoteImage(attempt.redirectTo, redirects + 1, notes);
+      return readRemoteImage(attempt.redirectTo, redirects + 1, notes, deadlineAt);
     lastConnectError = attempt.connectError;
   }
   throw new Error(`Image URL host ${url.hostname} could not be reached at any of its addresses (${pinned.addresses.map((item) => item.address).join(", ")}): ${lastConnectError?.message ?? "connection failed"}.`);
 }
-async function readRemoteImageFrom(url, rawUrl, candidate, redirects) {
+function totalBudgetMessage() {
+  return `Image URL did not finish loading within ${REMOTE_IMAGE_TOTAL_TIMEOUT_MS / 1e3} seconds, including redirects.`;
+}
+async function readRemoteImageFrom(url, rawUrl, candidate, redirects, deadlineAt) {
+  const budget = remoteImageHopBudget(deadlineAt, Date.now(), REMOTE_IMAGE_TIMEOUT_MS);
+  if (budget.kind === "exhausted") {
+    throw new Error(totalBudgetMessage());
+  }
   const dispatcher = new import_undici.Agent({
     connect: { lookup: pinnedLookup(candidate.address, candidate.family) }
   });
   const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), REMOTE_IMAGE_TIMEOUT_MS);
+  const timeout = setTimeout(() => controller.abort(), budget.ms);
   try {
     let response;
     try {
@@ -116840,7 +116869,7 @@ async function readRemoteImageFrom(url, rawUrl, candidate, redirects) {
       });
     } catch (err) {
       if (err instanceof Error && err.name === "AbortError") {
-        throw new Error("Image URL fetch timed out.");
+        throw new Error(budget.capped ? totalBudgetMessage() : `Image URL did not respond within ${REMOTE_IMAGE_TIMEOUT_MS / 1e3} seconds.`);
       }
       return { connectError: err instanceof Error ? err : new Error(String(err)) };
     }
@@ -118034,6 +118063,27 @@ function markdownMetric(label, value, suffix = "") {
   const metric = value === null || value === void 0 || value === "" ? "n/a" : String(value);
   return `- ${label}: ${metric}${suffix}`;
 }
+function reportQualityCaveats(dataQuality) {
+  if (!dataQuality || typeof dataQuality !== "object" || Array.isArray(dataQuality))
+    return [];
+  const marks = dataQuality;
+  const caveats = [];
+  if (marks.baselineSource === "none")
+    caveats.push("baselineMissing");
+  if (marks.startedAtSource === "end_time")
+    caveats.push("startTimeUnknown");
+  if (marks.watchTime === "unavailable")
+    caveats.push("watchTimeUnmeasured");
+  if (marks.watchTime === "unknown_duration")
+    caveats.push("watchTimeUncapped");
+  return caveats;
+}
+var REPORT_QUALITY_CAVEAT_TEXT = {
+  baselineMissing: "The session baseline was not saved: every figure below is counted from zero and includes everything the event accumulated before this broadcast.",
+  startTimeUnknown: "The broadcast start time was not saved: the report is stamped with the moment it ended and its duration reads zero.",
+  watchTimeUnmeasured: "Watch time was not measured: the engagement snapshot could not be read.",
+  watchTimeUncapped: "Watch time is not capped by the broadcast length \u2014 it is unknown, so nothing vouches for the total, average and median times."
+};
 function sessionReportMarkdown({ eventId, event, sessionId, session }) {
   const lines = [
     `# OKO session report`,
@@ -118063,6 +118113,12 @@ function sessionReportMarkdown({ eventId, event, sessionId, session }) {
     markdownMetric("CTA clicks", session.ctaClicks),
     markdownMetric("Cards clicks", session.cardsClicks)
   ];
+  const caveats = reportQualityCaveats(session.dataQuality);
+  if (caveats.length > 0) {
+    lines.push("", "## What this report did not measure");
+    for (const caveat of caveats)
+      lines.push(`- ${REPORT_QUALITY_CAVEAT_TEXT[caveat]}`);
+  }
   return lines.join("\n");
 }
 var TELEGRAM_COPYABLE_KEYS = ["enabled", "channelIds", "autoReminder"];
@@ -118421,10 +118477,32 @@ async function addEventWithRtdbMirror(eventData) {
   try {
     const ensureRuntime = httpsCallable(functions, "ensureEventRuntime");
     await ensureRuntime({ eventId: eventRef.id });
+    return { ref: eventRef, runtime: { status: "ready" } };
   } catch (error3) {
-    console.error(`[OKO MCP] RTDB mirror deferred to onEventCreated for event ${eventRef.id}:`, error3);
+    const rawCode = error3?.code;
+    const code = typeof rawCode === "string" ? rawCode : "unknown";
+    console.error(`[OKO MCP] ensureEventRuntime failed for event ${eventRef.id}:`, error3);
+    return {
+      ref: eventRef,
+      runtime: {
+        status: "failed",
+        code,
+        message: error3 instanceof Error ? error3.message : String(error3)
+      }
+    };
   }
-  return eventRef;
+}
+function eventRuntimeHint(runtime) {
+  if (runtime.status === "ready")
+    return [];
+  if (runtime.code === "functions/not-found") {
+    return [
+      "The event document was created, but the server reports the event as already gone and could not confirm its runtime. Do not hand the links out: re-read it with oko_get_event and tell the organizer the creation did not complete."
+    ];
+  }
+  return [
+    `The event was created, but the server could not confirm its runtime mirrors (${runtime.code}). Chat and access rules may lag behind: run oko_validate_event_setup before relying on the links, and say so to the organizer.`
+  ];
 }
 
 // build/tools/setupValidation.js
@@ -118576,17 +118654,48 @@ function assertScheduleHasDate(fresh, patch) {
     return;
   throw new Error("sessionMode 'schedule' requires meta.eventDate: without a date OKO can never start the session automatically. Set eventDate in the same call, or switch sessionMode to 'manual' in the same call to clear the date.");
 }
+var BLOCK_FORM_BINDING_FIELDS = [
+  "blocks.promoBanner.formId",
+  "blocks.primaryCta.formId"
+];
+function formIdSet(formsValue) {
+  return new Set((Array.isArray(formsValue) ? formsValue : []).map((form) => typeof form?.id === "string" ? form.id : null).filter((id) => Boolean(id)));
+}
+function formBindingsAfterPatch(fresh, patch) {
+  const bindings = [];
+  for (const field2 of BLOCK_FORM_BINDING_FIELDS) {
+    const value = valueAfterPatch(fresh, patch, field2);
+    if (typeof value === "string" && value)
+      bindings.push({ field: field2, formId: value });
+  }
+  const cards = valueAfterPatch(fresh, patch, "blocks.cards.items");
+  if (Array.isArray(cards)) {
+    cards.forEach((card, index) => {
+      const formId = card && typeof card === "object" && !Array.isArray(card) ? card.formId : null;
+      if (typeof formId === "string" && formId) {
+        bindings.push({ field: `blocks.cards.items[${index}].formId`, formId });
+      }
+    });
+  }
+  return bindings;
+}
 function assertFormBindingsExist(fresh, patch) {
-  const formsAfterPatch = valueAfterPatch(fresh, patch, "forms");
-  const knownFormIds = new Set((Array.isArray(formsAfterPatch) ? formsAfterPatch : []).map((form) => typeof form?.id === "string" ? form.id : null).filter((id) => Boolean(id)));
-  for (const field2 of ["blocks.promoBanner.formId", "blocks.primaryCta.formId"]) {
+  const formsAfter = formIdSet(valueAfterPatch(fresh, patch, "forms"));
+  for (const field2 of BLOCK_FORM_BINDING_FIELDS) {
     if (!Object.prototype.hasOwnProperty.call(patch, field2))
       continue;
     const value = patch[field2];
-    if (typeof value === "string" && value && !knownFormIds.has(value)) {
+    if (typeof value === "string" && value && !formsAfter.has(value)) {
       throw new Error(`${field2}: form "${value}" not found in event.forms. Create the form in the same call (or beforehand) \u2014 a button bound to a missing form does nothing for viewers.`);
     }
   }
+  const formsBefore = formIdSet(valueAfterPatch(fresh, {}, "forms"));
+  const orphaned = formBindingsAfterPatch(fresh, patch).filter((binding) => !formsAfter.has(binding.formId) && formsBefore.has(binding.formId));
+  if (orphaned.length === 0)
+    return;
+  const listed = orphaned.map((binding) => `${binding.field} -> "${binding.formId}"`).join(", ");
+  const cardsAffected = orphaned.some((binding) => binding.field.startsWith("blocks.cards."));
+  throw new Error(`This call removes a form that buttons still point at: ${listed}. A button bound to a missing form does nothing for viewers, so the removal is refused while something still points at it. Unbind them first: pass promoBanner: {formId: null} and/or primaryCta: {formId: null} in this same call` + (cardsAffected ? ", and clear the card bindings with oko_configure_cards before removing the form." : "."));
 }
 function configureBlocksScopes(args) {
   return Object.keys(telegramBlocksPatch(args)).length > 0 ? ["setup:write", "telegram:write"] : ["setup:write"];
@@ -118600,7 +118709,7 @@ function registerEventTools(server2) {
         "limit: maximum events to return, default 30, max 100.",
         "cursor: pagination cursor returned as nextCursor by the previous page; reuse it with the same filters.",
         "workspaceId: optional workspace filter.",
-        'detail: "compact" (default) returns the light card projection; "full" returns complete event documents.',
+        'detail: "compact" (default) returns the light card projection; "full" returns event documents without the access composition, same shape as oko_get_event.',
         "from/to: optional ISO timestamps bounding meta.eventDate; sorting switches to eventDate descending and undated events are excluded."
       ],
       returns: "events plus count, limit, hasMore/has_more, nextCursor/next_cursor.",
@@ -118648,7 +118757,10 @@ function registerEventTools(server2) {
       let events;
       if (args.detail === "full") {
         const eventDocuments = await Promise.all(pageItems.map((item) => getDoc(doc(firestore, "events", item.id))));
-        events = eventDocuments.flatMap((item) => item.exists() ? [{ id: item.id, ...serialize(item.data()) }] : []);
+        events = eventDocuments.flatMap((item) => item.exists() ? [{
+          id: item.id,
+          ...serialize(eventDocumentForOutput(item.data()))
+        }] : []);
       } else {
         events = pageItems.map((item) => {
           const data = serialize(item.data());
@@ -118668,7 +118780,7 @@ function registerEventTools(server2) {
     description: toolDescription({
       summary: "Read one OKO event visible to the organizer.",
       args: ["eventId: OKO event document id."],
-      returns: "full event document fields plus id and public event URL.",
+      returns: "event document fields plus id and public event URL. The event's access composition (the historical uid arrays) is never returned; ask oko_list_workspace_access for who has access.",
       examples: ["Use after oko_create_webinar to verify setup and return the event URL to the user."],
       notes: [
         "blocks.chat.mode and blocks.chat.visibility are both legacy: the event page reads neither \u2014 the chat panel exists exactly when blocks.chat.enabled is true, and sending is opened or closed live with oko_set_chat_mode. Ignore both fields."
@@ -118680,7 +118792,11 @@ function registerEventTools(server2) {
   }, async ({ eventId }) => {
     const { uid } = await authed(["events:read"]);
     const data = await readEvent(eventId, uid, "read");
-    return textResult({ id: eventId, ...serialize(data), ...eventLinks(eventId) });
+    return textResult({
+      id: eventId,
+      ...serialize(eventDocumentForOutput(data)),
+      ...eventLinks(eventId)
+    });
   });
   server2.registerTool("oko_validate_event_setup", {
     title: "Validate event setup",
@@ -118736,7 +118852,7 @@ function registerEventTools(server2) {
     const workspaceId = args.workspaceId ?? uid;
     await assertCanCreateInWorkspace(uid, workspaceId);
     const video = normalizeVideo(args.videoUrl);
-    const docRef = await addEventWithRtdbMirror(buildCreateWebinarDocument({
+    const created = await addEventWithRtdbMirror(buildCreateWebinarDocument({
       uid,
       workspaceId,
       title: args.title,
@@ -118747,11 +118863,14 @@ function registerEventTools(server2) {
       chatEnabled: args.chatEnabled,
       createdAt: serverTimestamp2()
     }));
+    const docRef = created.ref;
     return textResult({
       id: docRef.id,
       ...eventLinks(docRef.id),
       workspaceId,
+      runtime: created.runtime,
       hints: [
+        ...eventRuntimeHint(created.runtime),
         "The page is live at publicUrl immediately; OKO has no draft state.",
         "Next: oko_configure_blocks for chat/CTA/placeholder, oko_configure_cards for cards, image uploads, then oko_validate_event_setup.",
         'The video placeholder (countdown/cover) is only shown to viewers after oko_set_block_visibility with block "placeholder" and visible true; enabling it in oko_configure_blocks alone keeps it hidden.'
@@ -118830,7 +118949,7 @@ function registerEventTools(server2) {
       args: [
         "eventId: event to edit.",
         "chat/promoBanner/primaryCta/videoPlaceholder: optional block patches.",
-        "forms: replaces configured lead forms when provided.",
+        "forms: replaces configured lead forms when provided; removing a form that a button still points at is refused.",
         "telegramChannelIds: replaces configured Telegram channels when provided; needs the telegram:write scope AND the notification permission on the event, and is refused before anything is written when either is missing."
       ],
       returns: "event id and the list of Firestore fields updated.",
@@ -118840,7 +118959,8 @@ function registerEventTools(server2) {
         "promoBanner has no text field by design: the banner is image+link. blocks.promoBanner.text seen in event documents is legacy and is never rendered on the event page.",
         'videoPlaceholder.enabled only allows the placeholder; viewers see it after oko_set_block_visibility with block "placeholder" and visible true (a live override, stored outside the event document). Chat, CTA, banner and cards appear as soon as they are enabled here.',
         "Setup toggle vs live override: enabled=false removes a block from the page for everyone and persists (its uploaded image stays); oko_set_block_visibility hides or shows an enabled block temporarily and is the tool for the live show. Uploading an image never enables a block.",
-        "telegramChannelIds is the only field here that is not a page setting: it decides which channel carries this event's messages, and the automatic reminder goes out under the event owner's name. Omit the field to configure blocks with setup:write alone; pass it only with a key that holds telegram:write and for an organizer who may send notifications for this event."
+        "telegramChannelIds is the only field here that is not a page setting: it decides which channel carries this event's messages, and the automatic reminder goes out under the event owner's name. Omit the field to configure blocks with setup:write alone; pass it only with a key that holds telegram:write and for an organizer who may send notifications for this event.",
+        "forms and the buttons bound to them travel together in both directions: binding a button to a form that does not exist is refused, and so is replacing forms in a way that removes a form the banner, the CTA or a card button still points at. Unbind in the same call with promoBanner/primaryCta formId:null; card bindings are cleared with oko_configure_cards first. A binding that was already broken before the call is not touched and does not block it."
       ]
     }),
     inputSchema: {
@@ -119265,7 +119385,6 @@ var MCP_AUDIT_TARGET_KEYS = /* @__PURE__ */ new Set([
   "postId",
   "messageId",
   "leadId",
-  "participantUid",
   "uid",
   "channelId",
   "cardId",
@@ -119681,7 +119800,7 @@ function registerLifecycleTools(server2) {
     await assertCanCreateInWorkspace(uid, workspaceId);
     const sourceHasTelegram = !!source.telegram && typeof source.telegram === "object";
     const mayCopyTelegram = sourceHasTelegram && currentScopes().includes("telegram:write") && await eventGrantsMode(eventId, uid, "notify");
-    const newRef = await addEventWithRtdbMirror({
+    const duplicated = await addEventWithRtdbMirror({
       ownerId: uid,
       workspaceId,
       createdAt: serverTimestamp2(),
@@ -119698,14 +119817,17 @@ function registerLifecycleTools(server2) {
       // (review 02.09, R3b-5).
       ...mayCopyTelegram ? { telegram: copyableTelegram(source.telegram) } : {}
     });
+    const newRef = duplicated.ref;
     return textResult({
       id: newRef.id,
       sourceEventId: eventId,
       workspaceId,
+      runtime: duplicated.runtime,
       ...eventLinks(newRef.id),
       liveStateNotCopied: ["chatMode", "placeholderVisible", "liveBadge", "block visibility overrides"],
       telegramCopied: mayCopyTelegram,
       hints: [
+        ...eventRuntimeHint(duplicated.runtime),
         ...sourceHasTelegram && !mayCopyTelegram ? ["Telegram config was NOT copied: this key needs telegram:write and the notification permission on the source event. The copy starts with Telegram off; ask the event owner to grant the permission, then configure channels on the copy."] : [],
         "Live state was not copied: chat mode is public and the placeholder is hidden on the copy. If the source had chat off or the placeholder shown, set them again with oko_set_chat_mode and oko_set_block_visibility on the new event.",
         "The copy is live at publicUrl immediately; edit title, eventDate, and video with oko_update_event, then run oko_validate_event_setup."
@@ -119792,6 +119914,7 @@ function registerLiveTools(server2) {
       examples: ["Use visible=false to hide the CTA live; use visible=null to return to setup defaults."],
       notes: [
         "block=chat with visible=false PAUSES message input: viewers keep seeing the chat history but cannot send. It does not hide the chat panel.",
+        "Chat is the only block whose override the SERVER enforces: it is written as the chat mode and mirrored into the chat security rules, so a paused chat refuses messages from every client. The other four overrides are page presentation only \u2014 they change what viewers see, not what the server accepts.",
         "Live overrides sit on top of setup: a block disabled in setup (oko_configure_blocks enabled=false) stays absent whatever the override; visible=null returns an enabled block to its setup default. Use overrides for the live show, setup toggles for permanent changes."
       ]
     }),
@@ -119846,10 +119969,10 @@ function registerLiveTools(server2) {
   server2.registerTool("oko_refresh_viewers", {
     title: "Refresh viewers",
     description: toolDescription({
-      summary: "Trigger a live viewer refresh tick for an event.",
+      summary: "Refresh what viewers see: recount the online viewers and make open event pages re-read their config.",
       args: ["eventId: event whose viewers should refresh.", "confirm: must be true."],
-      returns: "eventId and refreshed=true.",
-      examples: ["Use after a setup/live change if viewers should reload state immediately."]
+      returns: "eventId, refreshed=true, and online \u2014 the recounted number of viewers present.",
+      examples: ["Use after a setup/live change if viewers should reload state immediately.", "Use when the online counter looks wrong: it is recounted from the actual presence nodes."]
     }),
     inputSchema: { eventId: eventIdField, confirm: external_exports.boolean().optional().describe("Required true to refresh connected viewers.") },
     outputSchema: basicEventOutputSchema,
@@ -119858,8 +119981,13 @@ function registerLiveTools(server2) {
     const { uid } = await authed(["live:control"]);
     await readEvent(eventId, uid, "live");
     requireConfirm(confirm, "oko_refresh_viewers", { eventId });
-    await runTransaction(ref(rtdb, `events/${eventId}/ctrl/refreshTick`), (current) => (current ?? 0) + 1);
-    return textResult({ eventId, refreshed: true });
+    const resyncPresence = httpsCallable(functions, "resyncPresence");
+    const [resynced] = await Promise.all([
+      resyncPresence({ eventId }),
+      runTransaction(ref(rtdb, `events/${eventId}/ctrl/refreshTick`), (current) => (current ?? 0) + 1)
+    ]);
+    const online = typeof resynced.data?.online === "number" ? resynced.data.online : null;
+    return textResult({ eventId, refreshed: true, online });
   });
   server2.registerTool("oko_set_live_badge", {
     title: "Set live badge",
@@ -120074,6 +120202,63 @@ function summarizeSessionRepair(input) {
 }
 
 // build/tools/sessions.js
+function sessionBaselineFromRead(read) {
+  if (!read.ok)
+    return "unread";
+  return read.exists ? "present" : "absent";
+}
+function sessionRepairAction(input) {
+  if (input.liveSessionBaseline === "unread")
+    return "unknown";
+  return input.liveSessionBaseline === "present" ? "end" : "release";
+}
+function sessionRepairRefusal(action) {
+  if (action === "end") {
+    return "This session still has working state in RTDB, so clearing its pointers would leave a running broadcast without a report. End it instead: oko_end_session saves the report and clears the pointers itself.";
+  }
+  if (action === "unknown") {
+    return "Could not read the session working state (events/{eventId}/sessions/{sessionId}/baseline), so it is unknown whether the session is still running. Nothing was changed; retry, or end the session with oko_end_session.";
+  }
+  return null;
+}
+async function assertSessionHasNothingToEnd(eventId, sessionId) {
+  if (!sessionId)
+    return;
+  let read;
+  try {
+    const snap = await get(ref(rtdb, `events/${eventId}/sessions/${sessionId}/baseline`));
+    read = { ok: true, exists: snap.exists() };
+  } catch {
+    read = { ok: false };
+  }
+  const refusal = sessionRepairRefusal(sessionRepairAction({ liveSessionBaseline: sessionBaselineFromRead(read) }));
+  if (refusal)
+    throw new Error(refusal);
+}
+async function attemptCleanup(path, run) {
+  try {
+    await run();
+    return { path, status: "fulfilled" };
+  } catch (error3) {
+    return { path, status: "rejected", error: error3 instanceof Error ? error3.message : String(error3) };
+  }
+}
+async function releaseSessionPointers(eventId, sessionId) {
+  const rtdbUpdates = {
+    [`events/${eventId}/ctrl/activeSessionId`]: null
+  };
+  if (sessionId)
+    rtdbUpdates[`activeSessions/${sessionId}`] = null;
+  const rtdbPaths = sessionId ? ["ctrl/activeSessionId", `activeSessions/${sessionId}`] : ["ctrl/activeSessionId"];
+  const rtdbOutcome = await attemptCleanup("rtdb", () => update(ref(rtdb), rtdbUpdates));
+  const attempts = rtdbPaths.map((path) => ({ ...rtdbOutcome, path }));
+  if (rtdbOutcome.status === "rejected") {
+    attempts.push({ path: "events.activeAnalyticsSessionId", status: "rejected", error: "skipped: RTDB pointers were not released" });
+    return attempts;
+  }
+  attempts.push(await attemptCleanup("events.activeAnalyticsSessionId", () => updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: deleteField() })));
+  return attempts;
+}
 function registerSessionTools(server2) {
   server2.registerTool("oko_start_session", {
     title: "Start analytics session",
@@ -120135,7 +120320,11 @@ function registerSessionTools(server2) {
       ],
       returns: "eventId, cleared sessionId if found, and cleaned paths.",
       examples: ["Use when oko_end_session says the baseline is missing or dashboard shows a stuck/orphan session."],
-      notes: ["This does not stop the video stream; OKO Start/End controls analytics sessions only."]
+      notes: [
+        "This does not stop the video stream; OKO Start/End controls analytics sessions only.",
+        "Refuses when the session still has working state in RTDB: clearing the pointers would leave a running broadcast without a report. Use oko_end_session for that case.",
+        "Both RTDB pointers are cleared in one atomic update, and the Firestore pointer only after it succeeds: the repair leaves either all pointers cleared or none."
+      ]
     }),
     inputSchema: {
       eventId: eventIdField,
@@ -120150,41 +120339,11 @@ function registerSessionTools(server2) {
     const ctrlSnap = await get(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`));
     const sessionId = safeString(event.activeAnalyticsSessionId) || safeString(ctrlSnap.val());
     requireConfirm(confirm, "oko_fix_orphan_session", { eventId, sessionId: sessionId || null, deleteRtdbSessionData });
-    const cleanup = [
-      {
-        path: "events.activeAnalyticsSessionId",
-        promise: updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: deleteField() })
-      },
-      {
-        path: "ctrl/activeSessionId",
-        promise: remove(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`))
-      }
-    ];
-    if (sessionId) {
-      cleanup.push({
-        path: `activeSessions/${sessionId}`,
-        promise: remove(ref(rtdb, `activeSessions/${sessionId}`))
-      });
-    }
+    await assertSessionHasNothingToEnd(eventId, sessionId);
+    const attempts = await releaseSessionPointers(eventId, sessionId);
     if (sessionId && deleteRtdbSessionData) {
-      cleanup.push({
-        path: `events/${eventId}/sessions/${sessionId}`,
-        promise: remove(ref(rtdb, `events/${eventId}/sessions/${sessionId}`))
-      });
+      attempts.push(await attemptCleanup(`events/${eventId}/sessions/${sessionId}`, () => remove(ref(rtdb, `events/${eventId}/sessions/${sessionId}`))));
     }
-    const settled = await Promise.allSettled(cleanup.map((operation) => operation.promise));
-    const attempts = settled.map((result, index) => {
-      const operation = cleanup[index];
-      if (!operation)
-        throw new Error("Session repair result has no matching cleanup operation.");
-      return {
-        path: operation.path,
-        status: result.status,
-        ...result.status === "rejected" ? {
-          error: result.reason instanceof Error ? result.reason.message : String(result.reason)
-        } : {}
-      };
-    });
     let firestorePointer = null;
     let rtdbPointer = null;
     let verificationError;
@@ -120220,7 +120379,11 @@ function registerSessionTools(server2) {
       ],
       returns: "eventId, sessionId, deleted=true, and cleaned paths.",
       examples: ["Use only after confirming the exact session id with the organizer."],
-      notes: ["Destructive. If the session is active, active pointers are cleared first. RTDB session data cleanup is best-effort because rules may deny deleting historical session snapshots."]
+      notes: [
+        "Destructive. If the session is active, all three pointers are released first \u2014 atomically in RTDB, then in Firestore \u2014 and only then is the document deleted; the platform refuses to delete the report of a session it still considers active.",
+        "Refuses an active session that still has working state in RTDB: end it with oko_end_session, which saves the report.",
+        "RTDB session data cleanup is best-effort because rules may deny deleting historical session snapshots."
+      ]
     }),
     inputSchema: {
       eventId: eventIdField,
@@ -120235,17 +120398,19 @@ function registerSessionTools(server2) {
     const event = await readEvent(eventId, uid, "session");
     requireConfirm(confirm, "oko_delete_session", { eventId, sessionId, deleteRtdbData });
     const isActive = safeString(event.activeAnalyticsSessionId) === sessionId;
-    const cleanup = [];
+    const warnings = [];
     if (isActive) {
-      cleanup.push(updateDoc(doc(firestore, "events", eventId), { activeAnalyticsSessionId: deleteField() }));
-      cleanup.push(remove(ref(rtdb, `events/${eventId}/ctrl/activeSessionId`)));
-      cleanup.push(remove(ref(rtdb, `activeSessions/${sessionId}`)));
-    }
-    cleanup.push(deleteDoc(doc(firestore, "events", eventId, "analyticsSessions", sessionId)));
-    const results = await Promise.allSettled(cleanup);
-    const warnings = results.filter((result) => result.status === "rejected").map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason));
-    if (warnings.length > 0)
-      throw new Error(`Session delete partially failed: ${warnings.join("; ")}`);
+      await assertSessionHasNothingToEnd(eventId, sessionId);
+      const attempts = await releaseSessionPointers(eventId, sessionId);
+      warnings.push(...attempts.filter((attempt) => attempt.status === "rejected").map((attempt) => `${attempt.path}: ${attempt.error || "cleanup failed"}`));
+      if (warnings.length > 0)
+        throw new Error(`Session delete partially failed: ${warnings.join("; ")}`);
+    }
+    try {
+      await deleteDoc(doc(firestore, "events", eventId, "analyticsSessions", sessionId));
+    } catch (error3) {
+      throw new Error(`Session delete partially failed: ${error3 instanceof Error ? error3.message : String(error3)}`);
+    }
     const rtdbCleanupWarnings = [];
     if (deleteRtdbData) {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@okostream/mcp",
-  "version": "0.12.11",
+  "version": "0.12.13",
   "description": "Control OKO Stream webinars from Claude, Codex, and other MCP clients.",
   "license": "UNLICENSED",
   "author": {