slidemind 0.1.6 → 0.1.8

package/src/bridge/client.mjs

@@ -6,8 +6,11 @@
 // open PowerPoint pane. No localhost, no shared loopback token, no cert.
 
 import { randomUUID } from "node:crypto";
+import fs from "node:fs";
 import http from "node:http";
 import https from "node:https";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   deriveEnvLabel,
@@ -15,6 +18,39 @@ import {
   readSessions,
 } from "./config.mjs";
 
+// This CLI's own version, for the add-in's minCliVersion floor (see
+// assertCliVersionSupported). Read lazily from the package manifest so the
+// module stays importable even from an odd install layout.
+let cliVersionCache = null;
+export function cliVersion() {
+  if (cliVersionCache) return cliVersionCache;
+  try {
+    const pkgPath = path.join(
+      path.dirname(fileURLToPath(import.meta.url)),
+      "..",
+      "..",
+      "package.json",
+    );
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    cliVersionCache = typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    cliVersionCache = "0.0.0";
+  }
+  return cliVersionCache;
+}
+
+// Numeric-aware dotted-version compare (no prerelease semantics — the CLI
+// releases plain X.Y.Z). Returns <0 / 0 / >0 like a comparator.
+export function compareCliVersions(a, b) {
+  const pa = String(a ?? "").split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = String(b ?? "").split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
 function isLoopbackHostname(hostname) {
   return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
 }
@@ -52,6 +88,19 @@ const NOT_PAIRED_MESSAGE =
   'slidemind is not paired. In the slidemind add-in, click "Connect CLI" ' +
   "and run the shown `slidemind pair …` command, then retry.";
 
+// The one-command remedy every host-precondition error now points at:
+// `slidemind ready` runs the whole pairing → reachability → version → window →
+// design ladder and materializes the bundle, so a stuck author has a single
+// next step instead of a scavenger hunt across doctor/presentations/download.
+// Appended (never substituted) to the existing prose so callers' assert.match
+// on the original text keeps passing.
+const READY_HINT =
+  "Run `slidemind ready` to check the connection and set up in one step.";
+// pickPresentationEntry's variant: the caller already HAS a host, it's just
+// ambiguous — `ready` resolves the window AND the design in one shot.
+const READY_HINT_PICK =
+  "Or run `slidemind ready` first — it resolves the window and design in one step.";
+
 // One transient blip — a pane mid-reconnect after a backend deploy, a stale
 // registration the pane is about to refresh — should not fail a whole skill
 // step. Idempotent reads retry a couple of times; mutations never do (the
@@ -270,12 +319,23 @@ async function readinessForBackend(backendURL) {
     const presentations = Array.isArray(data.presentations)
       ? data.presentations.map((p) => ({ ...p, backendURL, env }))
       : [];
+    // Version-floor check for diagnostics (doctor / connection_status): newer
+    // add-ins advertise minCliVersion in the readiness capabilities, so the
+    // skew is visible BEFORE a render trips over it.
+    const minCliVersion =
+      typeof data.capabilities?.minCliVersion === "string"
+        ? data.capabilities.minCliVersion
+        : null;
     return {
       env,
       backendURL,
       ok: true,
       readinessV1: data.readinessV1 === true,
       capabilities: data.capabilities ?? null,
+      minCliVersion,
+      cliUpdateRequired: Boolean(
+        minCliVersion && compareCliVersions(cliVersion(), minCliVersion) < 0,
+      ),
       presentations,
       summary: data.summary ?? null,
     };
@@ -372,8 +432,10 @@ export async function listOpenPresentations() {
 // The user/agent-facing shape of a presentation entry. `backendURL` is internal
 // routing state — every caller targets a presentation by `presId` (the backend
 // is re-resolved server-side from it), so the URL must never leave the process
-// in any printed line or MCP payload. Keeps presId, title, fileName, connected,
-// suspendedAt, and the short `env` label (the only discriminator a user sees).
+// in any printed line or command output. Keeps everything else — presId, title,
+// fileName, connected, suspendedAt, the short `env` label, and the readiness
+// fields (connectionState, designState, capabilities, nextAction) that agents
+// parse from `presentations --json` to decide whether/how to target a pane.
 export function toPublicPresentation(p) {
   const { backendURL, ...rest } = p;
   return rest;
@@ -412,13 +474,15 @@ export async function requireHost() {
       "Open PowerPoint with the slidemind add-in and an active corporate design, then retry.\n" +
         unreachable
           .map((u) => `  (bridge: ${u.env}: ${u.error})`)
-          .join("\n"),
+          .join("\n") +
+        `\n${READY_HINT}`,
     );
   }
   throw new Error(
     "No PowerPoint window is registered with the slidemind add-in.\n" +
       "If PowerPoint is already open, bring it to the foreground and click the slidemind pane once so it re-registers, then retry.\n" +
-      "Otherwise open PowerPoint with the slidemind add-in and an active corporate design, then retry.",
+      "Otherwise open PowerPoint with the slidemind add-in and an active corporate design, then retry.\n" +
+      READY_HINT,
   );
 }
 
@@ -467,6 +531,32 @@ async function waitForReadyPresentation(predicate, { timeoutMs = null } = {}) {
   }
 }
 
+// The bounded poll behind `slidemind presentations`. Unlike
+// waitForReadyPresentation it PURPOSELY does NOT early-return on an empty
+// registry: the empty window right after a pane reload / PowerPoint wake is
+// exactly the flaky case this papers over. Polls the merged registry every
+// SLIDEMIND_BRIDGE_READY_POLL_MS (default 1.5s) up to
+// SLIDEMIND_BRIDGE_PRESENTATIONS_WAIT_MS (default 6s), stopping as soon as at
+// least one pane is pane-ready. A `timeoutMs` of 0 means single-shot — one
+// fetch, no sleep. Returns { all, ready } so the caller can list EVERY entry
+// (suspended included, with its status) yet still know which are live. Does not
+// touch waitForReadyPresentation / requirePaneHost — agent target selection
+// still uses only ready panes.
+export async function listReadyPresentationsWithWait({ timeoutMs = null } = {}) {
+  const waitMs =
+    timeoutMs ?? envInt("SLIDEMIND_BRIDGE_PRESENTATIONS_WAIT_MS", 6000);
+  const pollMs = envInt("SLIDEMIND_BRIDGE_READY_POLL_MS", 1500);
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    const all = await listOpenPresentations();
+    const ready = all.filter(isPaneReadyPresentation);
+    if (ready.length > 0 || waitMs <= 0 || Date.now() >= deadline) {
+      return { all, ready };
+    }
+    await sleep(pollMs);
+  }
+}
+
 export async function requireRenderHost({ timeoutMs = null } = {}) {
   const first = await listOpenPresentationsDetailed();
   if (first.presentations.some(isRenderReadyPresentation)) {
@@ -482,7 +572,8 @@ export async function requireRenderHost({ timeoutMs = null } = {}) {
     }
     throw new Error(
       "PowerPoint is registered with the slidemind add-in, but no window is render-ready yet. " +
-        "Wait for the corporate design to finish matching, or pick/create a corporate design in the add-in, then retry.",
+        "Wait for the corporate design to finish matching, or pick/create a corporate design in the add-in, then retry. " +
+        READY_HINT,
     );
   }
   return requireHost();
@@ -491,19 +582,20 @@ export async function requireRenderHost({ timeoutMs = null } = {}) {
 export async function requirePaneHost({ timeoutMs = null } = {}) {
   const first = await listOpenPresentationsDetailed();
   if (first.presentations.some(isPaneReadyPresentation)) {
-    return first.presentations;
+    return first.presentations.filter(isPaneReadyPresentation);
   }
   if (first.presentations.length > 0) {
     const waited = await waitForReadyPresentation(isPaneReadyPresentation, {
       timeoutMs,
     });
-    if (Array.isArray(waited)) return waited;
+    if (Array.isArray(waited)) return waited.filter(isPaneReadyPresentation);
     if (waited.presentations.some(isPaneReadyPresentation)) {
-      return waited.presentations;
+      return waited.presentations.filter(isPaneReadyPresentation);
     }
     throw new Error(
       "PowerPoint is registered with the slidemind add-in, but the task pane is not ready for pane operations. " +
-        "Bring PowerPoint forward and click or reopen the slidemind pane, then retry.",
+        "Bring PowerPoint forward and click or reopen the slidemind pane, then retry. " +
+        READY_HINT,
     );
   }
   return requireHost();
@@ -612,7 +704,7 @@ export async function waitForPaneReady(
 }
 
 // The one actionable line a human needs when a pane op is waiting. stderr so
-// it reaches the terminal from the CLI and the MCP server log alike.
+// it reaches the terminal from the CLI.
 function paneWaitNotice(seconds) {
   process.stderr.write(
     "task pane suspended — click the slidemind pane in PowerPoint to wake it " +
@@ -639,6 +731,64 @@ export async function getDesignBundle(
   });
 }
 
+// GET the design bundle by brandId over the pane-free brand route. 404
+// `unknown_brand` is definitive (unknown / cross-tenant / not granted to this
+// user), so no transient retry. Requires the resolved backendURL — use
+// getDesignBundleForBrandAnyBackend when it isn't known yet.
+export async function getDesignBundleForBrand(brandId, { backendURL } = {}) {
+  if (!brandId) {
+    throw new Error("getDesignBundleForBrand: brandId is required");
+  }
+  if (!backendURL) {
+    throw new Error("getDesignBundleForBrand: backendURL is required");
+  }
+  const res = await bridgeFetch(
+    `/api/cli/brands/${encodeURIComponent(brandId)}/design-bundle`,
+    {},
+    backendURL,
+  );
+  return res.json();
+}
+
+// Resolve WHICH paired backend serves a brand by asking each one that
+// advertises brand routes — a bound deck has no open window, so there is no
+// registry entry to resolve a backend from. presFP/brandId is globally unique
+// across deployments (the bundle-cache contract), so at most one backend
+// answers 2xx. Returns { wire, backendURL }; throws a typed
+// `brand_route_unavailable` when no backend serves the brand (old add-ins,
+// unknown brand, missing grant) so callers fall back to the pane flow.
+export async function getDesignBundleForBrandAnyBackend(brandId) {
+  if (!brandId) {
+    throw new Error("getDesignBundleForBrandAnyBackend: brandId is required");
+  }
+  const sessions = sessionsInScope();
+  const failures = [];
+  for (const s of sessions) {
+    try {
+      if (!(await backendSupportsBrandRoutes(s.backendURL))) {
+        failures.push({ env: deriveEnvLabel(s.backendURL), reason: "no brand routes" });
+        continue;
+      }
+      const wire = await getDesignBundleForBrand(brandId, {
+        backendURL: s.backendURL,
+      });
+      return { wire, backendURL: s.backendURL };
+    } catch (err) {
+      failures.push({
+        env: deriveEnvLabel(s.backendURL),
+        reason: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  const detail = failures.map((f) => `${f.env}: ${f.reason}`).join("; ");
+  const err = new Error(
+    `no paired backend serves design '${brandId}' over the pane-free brand ` +
+      `route${detail ? ` (${detail})` : ""}.`,
+  );
+  err.code = "brand_route_unavailable";
+  throw err;
+}
+
 // List the LIVE engine catalog (NOT the bundle's curated set) for the paired
 // backend(s). `GET /api/cli/engines` is backend-scoped, not presId-scoped, so
 // when several environments are paired this fans out and tags each engine with
@@ -665,8 +815,8 @@ async function listEnginesForBackend(backendURL, { type = null, subtype = null }
   });
 }
 
-export async function listEngines({ type = null, subtype = null } = {}) {
-  const sessions = sessionsInScope();
+export async function listEngines({ type = null, subtype = null, backendURL = null } = {}) {
+  const sessions = backendURL ? [sessionForBackend(backendURL)] : sessionsInScope();
   const settled = await Promise.allSettled(
     sessions.map((s) => listEnginesForBackend(s.backendURL, { type, subtype })),
   );
@@ -716,10 +866,10 @@ function sleep(ms) {
 // One capability probe per backend per process. Keyed by the RESOLVED backend
 // URL (callers always resolve before probing), so multiple paired backends on
 // mixed versions each get their own answer.
-const renderJobsCapability = new Map();
+const backendCapabilitiesCache = new Map();
 
-function backendSupportsRenderJobs(backendURL) {
-  let probe = renderJobsCapability.get(backendURL);
+function backendCapabilities(backendURL) {
+  let probe = backendCapabilitiesCache.get(backendURL);
   if (!probe) {
     probe = (async () => {
       try {
@@ -728,26 +878,59 @@ function backendSupportsRenderJobs(backendURL) {
           { timeoutMs: listTimeoutMs() },
           backendURL,
         );
-        const data = await res.json();
-        return data?.renderJobs === true;
+        return (await res.json()) ?? {};
       } catch {
-        // Older backends 404 this path (with a non-JSON body) — sync render.
-        return false;
+        // Older backends 404 this path (with a non-JSON body) — no
+        // capabilities: sync render, no version floor.
+        return {};
       }
     })();
-    renderJobsCapability.set(backendURL, probe);
+    backendCapabilitiesCache.set(backendURL, probe);
   }
   return probe;
 }
 
+async function backendSupportsRenderJobs(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.renderJobs === true;
+}
+
+// Pane-free brand-scoped routes (/api/cli/brands/:brandId/*): design-bundle,
+// translate and render keyed by the brandId the deck's .bundle-ref.json already
+// stores (presFP == brandId), instead of the pane registry — so a bound deck
+// keeps building after every pane key aged out of the add-in's registry (or
+// with PowerPoint closed entirely). Advertised by newer add-ins only.
+export async function backendSupportsBrandRoutes(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  return caps?.brandRoutes === true;
+}
+
+// The add-in's hard version floor: /api/cli/capabilities advertises the oldest
+// CLI it still speaks (`minCliVersion`). An older CLI must refuse to proceed —
+// mid-rollout skew otherwise surfaces as confusing route/contract errors deep
+// in a render — and prompt the one actionable fix. No-op when the backend
+// doesn't advertise a floor (older add-ins) or the CLI meets it.
+export async function assertCliVersionSupported(backendURL) {
+  const caps = await backendCapabilities(backendURL);
+  const min = typeof caps?.minCliVersion === "string" ? caps.minCliVersion : null;
+  if (!min || compareCliVersions(cliVersion(), min) >= 0) return;
+  const err = new Error(
+    `slidemind CLI ${cliVersion()} is older than the minimum this add-in ` +
+      `supports (${min}). Run \`slidemind update\` (or ` +
+      "`npm install -g slidemind@latest`), then retry.",
+  );
+  err.code = "cli_update_required";
+  throw err;
+}
+
 // Rebuild a job failure into the exact error shape bridgeFetch throws for the
-// sync route, so callers (etag self-heal, MCP error texts) can't tell the
+// sync route, so callers (etag self-heal, error texts) can't tell the
 // protocols apart.
-function jobFailureError(jobError, presId) {
+function jobFailureError(jobError, label) {
   const status = jobError?.status ?? 500;
   const detail = jobError?.error ?? "render_failed";
   const err = new Error(
-    `slidemind bridge ${status} render job failed for ${presId}: ${detail}`,
+    `slidemind bridge ${status} render job failed for ${label}: ${detail}`,
   );
   err.status = status;
   err.code = detail;
@@ -755,9 +938,18 @@ function jobFailureError(jobError, presId) {
   return err;
 }
 
-async function renderViaSync({ presId, body, backendURL }) {
+// The render/translate routes exist on two surfaces sharing one contract:
+//   /api/cli/presentations/:presId  — brandId resolved from the pane registry
+//   /api/cli/brands/:brandId        — pane-free (bound deck, window optional)
+function renderBasePath({ presId, brandId }) {
+  return brandId
+    ? `/api/cli/brands/${encodeURIComponent(brandId)}`
+    : `/api/cli/presentations/${encodeURIComponent(presId)}`;
+}
+
+async function renderViaSync({ basePath, body, backendURL }) {
   const res = await bridgeFetch(
-    `/api/cli/presentations/${encodeURIComponent(presId)}/render-pptx`,
+    `${basePath}/render-pptx`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -774,7 +966,7 @@ async function renderViaSync({ presId, body, backendURL }) {
   return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
 }
 
-async function renderViaJob({ presId, body, backendURL, onProgress }) {
+async function renderViaJob({ basePath, label, body, backendURL, onProgress }) {
   const pollMs = envInt("SLIDEMIND_BRIDGE_RENDER_POLL_MS", 2500);
   const deadlineMs = envInt("SLIDEMIND_BRIDGE_RENDER_DEADLINE_MS", 900000);
   const resultTimeoutMs = envInt(
@@ -787,7 +979,7 @@ async function renderViaJob({ presId, body, backendURL, onProgress }) {
     // would re-upload a multi-MB slide payload, and creation errors (stale
     // etag, no CD, unknown presId) are definitive.
     const res = await bridgeFetch(
-      `/api/cli/presentations/${encodeURIComponent(presId)}/render-jobs`,
+      `${basePath}/render-jobs`,
       {
         method: "POST",
         headers: { "content-type": "application/json" },
@@ -832,7 +1024,7 @@ async function renderViaJob({ presId, body, backendURL, onProgress }) {
       // The job record vanished (backend Redis flush/restart) — same recovery
       // as a lost replica: resubmit once.
       if (err?.code === "job_not_found") {
-        if (resubmitted) throw jobFailureError({ status: 500, error: "job_lost" }, presId);
+        if (resubmitted) throw jobFailureError({ status: 500, error: "job_lost" }, label);
         resubmitted = true;
         onProgress?.({ state: "restarted" });
         jobId = await createJob();
@@ -867,7 +1059,7 @@ async function renderViaJob({ presId, body, backendURL, onProgress }) {
         jobId = await createJob();
         continue;
       }
-      throw jobFailureError(jobError, presId);
+      throw jobFailureError(jobError, label);
     }
 
     if (status.state === "done") {
@@ -901,8 +1093,15 @@ async function renderViaJob({ presId, body, backendURL, onProgress }) {
 // `slides`: { "<file>.jsx": "<jsx source>" }. `deckAssets`: { "assets/<f>": "<base64>" }.
 // `onProgress` (optional) receives `{ state, done?, total?, stage? }` ticks on
 // the job protocol; the sync fallback emits none.
+//
+// Target is EXACTLY ONE of:
+//   presId  — render via the pane registry (any add-in version)
+//   brandId — render via the pane-free brand route (needs backendURL + a
+//             backend advertising `brandRoutes`); `deckName` labels the render.
 export async function renderPptx({
-  presId,
+  presId = null,
+  brandId = null,
+  deckName = null,
   slides,
   deckAssets = null,
   nativeSlides = null,
@@ -910,13 +1109,25 @@ export async function renderPptx({
   backendURL = null,
   onProgress = null,
 }) {
-  if (!presId) throw new Error("renderPptx: presId is required");
+  if (!presId && !brandId) {
+    throw new Error("renderPptx: presId or brandId is required");
+  }
   const hasSlides = slides && Object.keys(slides).length > 0;
   const hasNative = nativeSlides && Object.keys(nativeSlides).length > 0;
   if (!hasSlides && !hasNative) {
     throw new Error("renderPptx: slides or nativeSlides is required");
   }
-  const be = backendURL || (await resolveBackendForPres(presId));
+  let be = backendURL;
+  if (!be) {
+    if (brandId) throw new Error("renderPptx: backendURL is required with brandId");
+    be = await resolveBackendForPres(presId);
+  }
+  // Version floor first: shipping a whole deck to a backend that no longer
+  // speaks this CLI's contract fails deep and confusingly; fail here instead
+  // with the actionable `slidemind update`.
+  await assertCliVersionSupported(be);
+  const basePath = renderBasePath({ presId, brandId });
+  const label = brandId ? (deckName ?? brandId) : presId;
   const body = { slides: slides ?? {} };
   if (deckAssets && Object.keys(deckAssets).length > 0) {
     body.deckAssets = deckAssets;
@@ -925,17 +1136,20 @@ export async function renderPptx({
   // server splices them in by numeric-aware sorted filename (contract #7).
   if (hasNative) body.nativeSlides = nativeSlides;
   if (etag) body.etag = etag;
+  // The brand surface has no presId to label the render with — pass the deck
+  // slug so job records/temp dirs stay readable (server-side sanitized).
+  if (brandId && deckName) body.deckName = deckName;
 
   if (await backendSupportsRenderJobs(be)) {
     try {
-      return await renderViaJob({ presId, body, backendURL: be, onProgress });
+      return await renderViaJob({ basePath, label, body, backendURL: be, onProgress });
     } catch (err) {
       // The backend speaks the protocol but its job store is down — the sync
       // route renders in-process without Redis, so fall back to it.
       if (err?.code !== "jobs_unavailable") throw err;
     }
   }
-  return renderViaSync({ presId, body, backendURL: be });
+  return renderViaSync({ basePath, body, backendURL: be });
 }
 
 // Translate a deck the CLI captured LOCALLY (the shipped capture engine) into a
@@ -943,15 +1157,24 @@ export async function renderPptx({
 // single synchronous request — the server runs only the IP-sensitive boxes→OOXML
 // half. Returns the same shape as renderPptx ({ ok, base64, slideCount, … }).
 export async function translateDeck({
-  presId,
+  presId = null,
+  brandId = null,
+  deckName = null,
   captured,
   nativeSlides = null,
   etag = null,
   backendURL = null,
 }) {
-  if (!presId) throw new Error("translateDeck: presId is required");
+  if (!presId && !brandId) {
+    throw new Error("translateDeck: presId or brandId is required");
+  }
   if (!captured) throw new Error("translateDeck: captured is required");
-  const be = backendURL || (await resolveBackendForPres(presId));
+  let be = backendURL;
+  if (!be) {
+    if (brandId) throw new Error("translateDeck: backendURL is required with brandId");
+    be = await resolveBackendForPres(presId);
+  }
+  await assertCliVersionSupported(be);
   const body = { captured };
   // Reused native one-slide .pptx (base64), keyed by play-order filename — the
   // server splices them in alongside the locally-captured JSX slides (contract
@@ -960,8 +1183,9 @@ export async function translateDeck({
     body.nativeSlides = nativeSlides;
   }
   if (etag) body.etag = etag;
+  if (brandId && deckName) body.deckName = deckName;
   const res = await bridgeFetch(
-    `/api/cli/presentations/${encodeURIComponent(presId)}/translate`,
+    `${renderBasePath({ presId, brandId })}/translate`,
     {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -978,14 +1202,20 @@ export async function translateDeck({
 }
 
 // Run a pane-relayed engine op; on `pane_suspended` (the server already waited
-// ~25s for a reconnect) wait CLIENT-side for the pane to wake — one actionable
-// line, then a single retry against the live entry (covers presId churn too).
-// Engine ops are idempotent reads, so the retry is safe.
+// ~25s for a reconnect) OR `pane_timeout` (the pane looked connected but never
+// acked within the server's 60s window — the server marks it suspended on the
+// way out, so the same wake applies) wait CLIENT-side for the pane to wake —
+// one actionable line, then a single retry against the live entry (covers
+// presId churn too). Engine ops are idempotent reads, and the one mutation
+// (live insert) rides the SAME operationId through the retry so the pane-side
+// dedup makes a re-send safe.
 async function engineOpWithPaneWait(presId, backendURL, attempt) {
   try {
     return await attempt(presId, backendURL);
   } catch (err) {
-    if (err?.code !== "pane_suspended") throw err;
+    if (err?.code !== "pane_suspended" && err?.code !== "pane_timeout") {
+      throw err;
+    }
     const live = await waitForPaneReady(presId, {
       backendURL,
       onWait: paneWaitNotice,
@@ -1266,7 +1496,7 @@ export async function viewSlide({
 }
 
 // Read the CURRENT content of an open presentation (the "pull content" path
-// behind `slidemind read` / slidemind_read_presentation). `mode` selects the
+// behind `slidemind read`). `mode` selects the
 // depth: "summary" returns a per-slide outline (index, layout, title, subtitle);
 // "raw" (default) returns each slide's full plain text — NOT the add-in's editing
 // markup. Unlike engine ops, content is WINDOW-BOUND: it reads THAT presentation,
@@ -1356,6 +1586,106 @@ export async function replaceSlides({
   return ensurePaneAckOk(await res.json().catch(() => ({})), "replace");
 }
 
+// Non-throwing, PURE (no network) sibling of pickPresentationEntry that answers
+// the one question `slidemind ready` needs: which corporate design should this
+// session bind to? Where pickPresentationEntry PROMPTS the user by throwing,
+// resolveDesignSource returns a STRUCTURED verdict the CLI turns into a bound
+// bundle, a single blocker, or a "which design?" question — no exceptions as
+// control flow.
+//
+// The bar is RENDER-ready, never pane-ready: the add-in is the source of truth
+// for the design, and a backgrounded (pane-suspended) window still serves its
+// bundle and still renders — so it is a valid design source (the caller reports
+// `paneSuspended` but stays exit 0). Pane readiness only matters later, when a
+// push/search actually needs the live pane.
+//
+// The ONE user-facing ambiguity is ≥2 render-ready windows on DISTINCT designs
+// (distinct `brandId`). We deliberately do NOT let the deck's own bundle ref
+// (`deckPresFP`) break that tie — the open add-in wins; a deck never pins a
+// design preference. The deck ref only:
+//   (a) tie-breaks ONE window mirrored across paired backends (same presId on
+//       dev+prod) via tieBreakMatches — the SAME rule pickPresentationEntry
+//       uses, and its only sanctioned use here; and
+//   (b) surfaces the matching candidate as `suggested`, so the agent can say
+//       "this deck was last built against X" WITHOUT the CLI silently deciding.
+//
+// Returns exactly one of:
+//   { status: "none" }                    — nothing render-ready is open.
+//   { status: "unknown_presid", presId }  — an explicit --to names no
+//                                            render-ready window.
+//   { status: "resolved", entry }         — the RAW registry entry (backendURL
+//                                            intact; the caller strips it before
+//                                            any user-facing output).
+//   { status: "ambiguous", candidates, suggested }
+//                                          — candidates deduped to ONE entry per
+//                                            distinct design; suggested is the
+//                                            presId of the deck-ref match, else
+//                                            null.
+export function resolveDesignSource(
+  registry,
+  { explicitPresId = null, deckPresFP = null } = {},
+) {
+  const all = (Array.isArray(registry) ? registry : []).filter(
+    isRenderReadyPresentation,
+  );
+  if (all.length === 0) return { status: "none" };
+
+  // Group by DESIGN. A render-ready pane always carries a brandId, but be
+  // defensive: a missing brandId is treated as its OWN pseudo-design keyed by
+  // presId so two CD-less windows never collapse into one false match.
+  const designKey = (p) =>
+    p.brandId != null && p.brandId !== ""
+      ? `brand:${p.brandId}`
+      : `pres:${p.presId}`;
+
+  // Collapse a set of entries to one representative per distinct design,
+  // preferring a live (pane-ready) pane over a suspended mirror, then compute
+  // the deck-ref `suggested` presId over those representatives.
+  const dedupeCandidates = (entries) => {
+    const byKey = new Map();
+    for (const p of entries) {
+      const k = designKey(p);
+      const cur = byKey.get(k);
+      if (!cur || (!isPaneReadyPresentation(cur) && isPaneReadyPresentation(p))) {
+        byKey.set(k, p);
+      }
+    }
+    const candidates = [...byKey.values()];
+    const suggested =
+      (deckPresFP && candidates.find((c) => c.brandId === deckPresFP)?.presId) ||
+      null;
+    return { candidates, suggested };
+  };
+
+  if (explicitPresId) {
+    const matches = all.filter((p) => p.presId === explicitPresId);
+    if (matches.length === 0) {
+      return { status: "unknown_presid", presId: explicitPresId };
+    }
+    if (matches.length === 1) return { status: "resolved", entry: matches[0] };
+    // >1 render-ready match == ONE window mirrored across paired backends.
+    // Tie-break exactly as pickPresentationEntry; only a genuine tie is asked.
+    const winner = tieBreakMatches(matches, deckPresFP);
+    if (winner) return { status: "resolved", entry: winner };
+    return { status: "ambiguous", ...dedupeCandidates(matches) };
+  }
+
+  const distinctDesigns = new Set(all.map(designKey));
+  if (distinctDesigns.size === 1) {
+    // One design open (possibly one window mirrored across backends, or several
+    // windows on the SAME CD). Pick via the mirror tie-break, else a live pane,
+    // else the first — the design is unambiguous either way.
+    const entry =
+      tieBreakMatches(all, deckPresFP) ??
+      all.find(isPaneReadyPresentation) ??
+      all[0];
+    return { status: "resolved", entry };
+  }
+  // ≥2 distinct designs open — the only case that asks the user (the deck ref
+  // does NOT auto-pick; it only annotates `suggested`).
+  return { status: "ambiguous", ...dedupeCandidates(all) };
+}
+
 // Pick a target presentation given the (possibly multi-backend) registry and an
 // optional explicit presId. Returns the matched registry ENTRY (which carries
 // `backendURL`/`env` after a fan-out list), or throws with a helpful message if
@@ -1410,7 +1740,7 @@ export function pickPresentationEntry(
     )
     .join("\n");
   throw new Error(
-    `Multiple PowerPoint windows are open. Pick one with --to <presId>:\n${list}`,
+    `Multiple PowerPoint windows are open. Pick one with --to <presId>:\n${list}\n${READY_HINT_PICK}`,
   );
 }