slidemind 0.3.13 → 0.3.14

package/src/bridge/client.mjs

@@ -5,3456 +5,84 @@
 // The add-in's cloud
 // backend runs render/bundle in-process and relays insert/replace/engine to the
 // 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 os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-import {
-  deriveEnvLabel,
-  envPhrase,
-  getSessionFor,
-  isMultiEnv,
-  readSessions,
-} from "./config.mjs";
-import {
-  ensureSignedIn,
-  getGraphToken,
-  getSharePointToken,
-} from "./graph-auth.mjs";
-import { updateCliInstruction } from "../install-channel.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;
-}
-
-// The one error every version-floor check raises, so the probe path
-// (assertCliVersionSupported) and the per-response header path are
-// indistinguishable to callers and to the skills that relay the text.
-function cliUpdateRequiredError(min) {
-  const err = new Error(
-    `slidemind CLI ${cliVersion()} is older than the minimum this add-in ` +
-      `supports (${min}). ${updateCliInstruction()}`,
-  );
-  err.code = "cli_update_required";
-  return err;
-}
-
-// `doctor` and `ready` exist to EXPLAIN a broken connection, version skew
-// included — they render it as a structured blocker with an `actor` and a
-// nextAction. Throwing the raw error out of bridgeFetch would break the one
-// command that diagnoses the problem, so they opt out of the header check
-// (their own ladder still reports cli_update_required, terminally).
-let diagnosticMode = false;
-export function setDiagnosticMode(on) {
-  diagnosticMode = on !== false;
-}
-
-// Every add-in response carries the version floor in `x-slidemind-min-cli`.
-// Checking it here covers routes no capability probe guards — the pane ops
-// (search/read/insert) and pairing itself — for zero extra round-trips, and it
-// fires BEFORE the status handling below so a stale CLI hitting a route that
-// does not exist yet reads "run slidemind update" instead of a bare 404.
-function enforceVersionFloor(response) {
-  if (diagnosticMode) return;
-  const min = response?.headers?.["x-slidemind-min-cli"];
-  if (typeof min !== "string" || !min) return;
-  if (compareCliVersions(cliVersion(), min) >= 0) return;
-  throw cliUpdateRequiredError(min);
-}
-
-function isLoopbackHostname(hostname) {
-  return hostname === "127.0.0.1" || hostname === "localhost" || hostname === "::1";
-}
-
-// The fan-out probe (listing presentations across every paired backend) uses a
-// shorter timeout than ordinary calls so one dead/slow backend — a local relay
-// that isn't running — can't stall the whole sweep for the full 35s default.
-function listTimeoutMs() {
-  return (
-    parseInt(process.env.SLIDEMIND_BRIDGE_LIST_TIMEOUT_MS || "8000", 10) || 8000
-  );
-}
-
-// Engine ops (list / search / download / extract) are RELAYED through the task
-// pane: the server waits up to ~25s for a suspended pane to reconnect, then up
-// to 60s for the pane's ack. Budget above that sum so a typed pane error
-// (pane_suspended / pane_timeout) wins over a client timeout. Note `ls engines`
-// is pane-relayed too — using the 8s list timeout there masked the real
-// pane_suspended as a bare "timed out after 8000ms".
-function engineTimeoutMs() {
-  return (
-    parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
-    90000
-  );
-}
-
-function readinessTimeoutMs() {
-  return (
-    parseInt(process.env.SLIDEMIND_BRIDGE_READY_TIMEOUT_MS || "20000", 10) ||
-    20000
-  );
-}
-
-const NOT_PAIRED_MESSAGE =
-  "slidemind is not connected. In PowerPoint open slidemind → Settings → " +
-  "General → Connect CLI, press the link button, and run the command it shows.";
-
-// The one-command remedy every host-precondition error now points at:
-// `slidemind ready` runs authorization → 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
-// request may already have been delivered).
-function transientRetryDelays() {
-  const raw = process.env.SLIDEMIND_BRIDGE_RETRY_DELAYS_MS || "1500,4000";
-  return raw
-    .split(",")
-    .map((s) => parseInt(s.trim(), 10))
-    .filter((n) => Number.isFinite(n) && n >= 0);
-}
-
-// A 401 from either bridge transport. Carries the remediation as its message
-// AND a machine-readable shape, because callers that probe several backends in
-// a row have to tell "this environment doesn't have that record" (routing
-// information) from "this session is dead" (the user's problem) — see
-// resolveSearchBackend.
-function sessionInvalidError() {
-  // Deliberately does NOT say `logout --all`: a 401 means the add-in answered
-  // "no such session" (revoked in Settings → Connect CLI, or expired). Running
-  // `setup` with a fresh command replaces this backend's record in place, so
-  // nothing has to be wiped first — and a user with two environments who wipes
-  // everything on every 401 is how the 2026-08-27 reconnect loop happened.
-  const err = new Error(
-    "slidemind session is invalid or expired: the add-in no longer knows this session " +
-      "(revoked under Settings → General → Connect CLI, or expired). Reconnect with a fresh " +
-      "command from that panel; other environments and your Microsoft 365 sign-in stay as they are.",
-  );
-  err.status = 401;
-  err.code = "session_invalid";
-  return err;
-}
-
-// True for the 401 class above, and for anything else that arrives with a 401
-// status (an older path, or a rethrown response error).
-export function isSessionInvalidError(err) {
-  if (!err) return false;
-  if (err.status === 401 || err.code === "session_invalid") return true;
-  return /slidemind session is invalid or expired/i.test(String(err.message ?? ""));
-}
-
-function isTransientBridgeError(err) {
-  if (!err) return false;
-  // pane_suspended needs the user (foreground PowerPoint), not a blind retry —
-  // the relay already waited for a reconnect before returning it.
-  if (err.code === "pane_suspended") return false;
-  if (err.status === 404 || err.status === 502 || err.status === 503) return true;
-  if (err.status === 409 && err.code === "pane_disconnected") return true;
-  return /relay unreachable/i.test(String(err.message || ""));
-}
-
-async function withTransientRetry(fn, isRetryable = isTransientBridgeError) {
-  const delays = transientRetryDelays();
-  for (let attempt = 0; ; attempt += 1) {
-    try {
-      return await fn();
-    } catch (err) {
-      if (attempt >= delays.length || !isRetryable(err)) throw err;
-      await new Promise((resolve) => setTimeout(resolve, delays[attempt]));
-    }
-  }
-}
-
-// The paired backends in scope for this invocation. Defaults to every paired
-// session (fan-out); `SLIDEMIND_BACKEND` narrows it to one (the CLI sets that
-// env from a `--backend <url|env>` flag) for speed or to disambiguate. Throws
-// the same actionable message as a missing pairing when nothing matches.
-function sessionsInScope() {
-  const all = readSessions();
-  if (all.length === 0) throw new Error(NOT_PAIRED_MESSAGE);
-  const scope = process.env.SLIDEMIND_BACKEND;
-  if (scope && scope.trim()) {
-    const want = scope.trim();
-    const match = all.filter(
-      (s) =>
-        s.backendURL === want ||
-        s.label === want ||
-        deriveEnvLabel(s.backendURL) === want ||
-        s.backendURL.includes(want),
-    );
-    if (match.length === 0) {
-      throw new Error(
-        `slidemind is not paired with '${want}'. Run 'slidemind whoami' to see paired environments.`,
-      );
-    }
-    return match;
-  }
-  return all;
-}
-
-// Resolve the credential for one backend (or the default session when no
-// backendURL is given — the back-compat single-session path).
-function sessionForBackend(backendURL) {
-  if (backendURL) {
-    const s = getSessionFor(backendURL);
-    if (!s)
-      throw new Error(
-        `slidemind is not paired with '${deriveEnvLabel(backendURL)}'.`,
-      );
-    return s;
-  }
-  const all = readSessions();
-  if (all.length === 0) throw new Error(NOT_PAIRED_MESSAGE);
-  return all[0];
-}
-
-async function bridgeFetch(pathPart, init = {}, backendURL = null) {
-  const session = sessionForBackend(backendURL);
-  const url = `${session.backendURL}${pathPart}`;
-  const headers = {
-    accept: "application/json",
-    ...init.headers,
-    authorization: `Bearer ${session.sessionToken}`,
-  };
-
-  let response;
-  try {
-    response = await nodeRequest(url, { ...init, headers });
-  } catch (err) {
-    if (err && /ECONNREFUSED|ECONNRESET|ENOTFOUND|self-signed|fetch failed/i.test(String(err.message || err))) {
-      throw new Error(
-        `slidemind relay unreachable${envPhrase(deriveEnvLabel(session.backendURL), "on")}. Check your connection; ` +
-          "if it persists, reconnect from the add-in's Connect CLI panel.",
-      );
-    }
-    throw err;
-  }
-  enforceVersionFloor(response);
-  if (response.status === 401) throw sessionInvalidError();
-  if (response.status < 200 || response.status >= 300) {
-    let parsed = null;
-    try {
-      parsed = response.body ? JSON.parse(response.body) : null;
-    } catch {
-      /* non-JSON error body — fall back to the raw text */
-    }
-    // Prefer the machine-readable `code` (e.g. "pane_suspended",
-    // "engine_auth_expired"); fall back to the human `error` string for routes
-    // that don't emit a discrete code yet. Keep the human text in the message.
-    const machineCode =
-      parsed && typeof parsed.code === "string" ? parsed.code : null;
-    const humanError =
-      parsed && typeof parsed.error === "string" ? parsed.error : null;
-    const detail =
-      humanError ?? (response.body ? response.body.slice(0, 400) : "");
-    const err = new Error(
-      `slidemind bridge ${response.status} ${response.statusText} for ${pathPart}` +
-        (detail ? `: ${detail}` : ""),
-    );
-    err.status = response.status;
-    const code = machineCode ?? humanError;
-    if (code) err.code = code;
-    if (parsed) err.body = parsed;
-    throw err;
-  }
-  return {
-    json: async () => (response.body ? JSON.parse(response.body) : null),
-    text: async () => response.body,
-    // Exposed for routes that carry their answer partly in headers (the
-    // source-presentation read reports slide counts and truncation there, so a
-    // caller learns the deck was windowed without parsing the Markdown).
-    headers: response.headers ?? {},
-  };
-}
-
-function nodeRequest(urlString, init = {}) {
-  const url = new URL(urlString);
-  const isHttps = url.protocol === "https:";
-  const transport = isHttps ? https : http;
-  const body = init.body ?? null;
-  const headers = { ...(init.headers ?? {}) };
-  if (body && headers["content-length"] === undefined && headers["Content-Length"] === undefined) {
-    headers["content-length"] = Buffer.byteLength(body);
-  }
-
-  const timeoutMs =
-    init.timeoutMs ??
-    (parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) || 35000);
-  return new Promise((resolve, reject) => {
-    const req = transport.request(
-      url,
-      {
-        method: init.method ?? "GET",
-        headers,
-        // Validate the cloud's real cert; only skip for a loopback dev backend
-        // (self-signed) when pointing the CLI at a local add-in for development.
-        rejectUnauthorized: isHttps ? !isLoopbackHostname(url.hostname) : undefined,
-      },
-      (res) => {
-        const chunks = [];
-        res.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
-        res.on("end", () => {
-          resolve({
-            status: res.statusCode ?? 0,
-            statusText: res.statusMessage ?? "",
-            headers: res.headers,
-            body: Buffer.concat(chunks).toString("utf8"),
-          });
-        });
-      },
-    );
-    // Default 35s > the relay's 25s wait-for-pane-reconnect, so a suspended
-    // pane surfaces a typed `pane_suspended` rather than a client timeout. A
-    // real timeout is tagged `bridge_timeout` so non-idempotent callers
-    // (insert) know the request may already have been delivered and must NOT
-    // auto-retry it.
-    req.setTimeout(timeoutMs, () => {
-      const err = new Error(
-        `slidemind bridge request timed out after ${timeoutMs}ms`,
-      );
-      err.code = "bridge_timeout";
-      req.destroy(err);
-    });
-    req.on("error", reject);
-    if (body) req.write(body);
-    req.end();
-  });
-}
-
-// A streaming sibling of `nodeRequest`, for responses too large to hold in
-// memory. `nodeRequest` concatenates the whole body and decodes it as UTF-8 —
-// fine for JSON, but it would both balloon memory and CORRUPT binary. This pipes
-// a success response straight to `destPath` and never materializes it.
 //
-// Error and JSON bodies are still buffered: both are small by construction (an
-// error message, or the inline SVG the download route answers with), and the
-// caller needs them whole to act on.
-function nodeRequestToFile(urlString, init = {}, destPath) {
-  const url = new URL(urlString);
-  const isHttps = url.protocol === "https:";
-  const transport = isHttps ? https : http;
-  const body = init.body ?? null;
-  const headers = { ...(init.headers ?? {}) };
-  if (
-    body &&
-    headers["content-length"] === undefined &&
-    headers["Content-Length"] === undefined
-  ) {
-    headers["content-length"] = Buffer.byteLength(body);
-  }
-  const timeoutMs =
-    init.timeoutMs ??
-    (parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) || 35000);
-
-  return new Promise((resolve, reject) => {
-    const req = transport.request(
-      url,
-      {
-        method: init.method ?? "GET",
-        headers,
-        rejectUnauthorized: isHttps
-          ? !isLoopbackHostname(url.hostname)
-          : undefined,
-      },
-      (res) => {
-        const status = res.statusCode ?? 0;
-        const contentType = String(res.headers["content-type"] ?? "");
-        const buffered = status < 200 || status >= 300 || contentType.includes("application/json");
-        if (buffered) {
-          const chunks = [];
-          res.on("data", (c) => chunks.push(Buffer.from(c)));
-          res.on("end", () =>
-            resolve({
-              status,
-              statusText: res.statusMessage ?? "",
-              headers: res.headers,
-              body: Buffer.concat(chunks).toString("utf8"),
-              streamed: false,
-            }),
-          );
-          res.on("error", reject);
-          return;
-        }
-        const out = fs.createWriteStream(destPath);
-        let bytesWritten = 0;
-        const total = Number.parseInt(
-          String(res.headers["content-length"] ?? ""),
-          10,
-        );
-        res.on("data", (c) => {
-          bytesWritten += c.length;
-          init.onProgress?.(bytesWritten, Number.isFinite(total) ? total : null);
-        });
-        res.pipe(out);
-        // A stream that dies mid-flight must reject, not resolve with a truncated
-        // file — the caller deletes the partial and surfaces the failure.
-        res.on("error", (err) => {
-          out.destroy();
-          reject(err);
-        });
-        out.on("error", reject);
-        out.on("finish", () =>
-          resolve({
-            status,
-            statusText: res.statusMessage ?? "",
-            headers: res.headers,
-            bytesWritten,
-            streamed: true,
-          }),
-        );
-      },
-    );
-    req.setTimeout(timeoutMs, () => {
-      const err = new Error(
-        `slidemind bridge request timed out after ${timeoutMs}ms`,
-      );
-      err.code = "bridge_timeout";
-      req.destroy(err);
-    });
-    req.on("error", reject);
-    if (body) req.write(body);
-    req.end();
-  });
-}
-
-// `bridgeFetch` for a response streamed to disk. Shares the session lookup,
-// auth header and non-2xx error mapping so a streaming call fails exactly like
-// every other bridge call.
-async function bridgeStreamToFile(pathPart, init, destPath, backendURL = null) {
-  const session = sessionForBackend(backendURL);
-  const url = `${session.backendURL}${pathPart}`;
-  const headers = {
-    accept: "application/octet-stream, application/json",
-    ...init.headers,
-    authorization: `Bearer ${session.sessionToken}`,
-  };
-  let response;
-  try {
-    response = await nodeRequestToFile(url, { ...init, headers }, destPath);
-  } catch (err) {
-    if (
-      err &&
-      /ECONNREFUSED|ECONNRESET|ENOTFOUND|self-signed|fetch failed/i.test(
-        String(err.message || err),
-      )
-    ) {
-      throw new Error(
-        `slidemind relay unreachable${envPhrase(deriveEnvLabel(session.backendURL), "on")}. Check your connection; ` +
-          "if it persists, reconnect from the add-in's Connect CLI panel.",
-      );
-    }
-    throw err;
-  }
-  enforceVersionFloor(response);
-  if (response.status === 401) throw sessionInvalidError();
-  if (response.status < 200 || response.status >= 300) {
-    let parsed = null;
-    try {
-      parsed = response.body ? JSON.parse(response.body) : null;
-    } catch {
-      /* non-JSON error body */
-    }
-    const machineCode =
-      parsed && typeof parsed.code === "string" ? parsed.code : null;
-    const humanError =
-      parsed && typeof parsed.error === "string" ? parsed.error : null;
-    const detail =
-      humanError ?? (response.body ? response.body.slice(0, 400) : "");
-    const err = new Error(
-      `slidemind bridge ${response.status} ${response.statusText} for ${pathPart}` +
-        (detail ? `: ${detail}` : ""),
-    );
-    err.status = response.status;
-    const code = machineCode ?? humanError;
-    if (code) err.code = code;
-    if (parsed) err.body = parsed;
-    throw err;
-  }
-  return response;
-}
-
-// List one backend's open presentations, tagging each entry with its origin
-// (backendURL + a short env label) so the merged registry can be routed and
-// displayed per environment. Transient blips retry per-backend.
-async function listPresentationsForBackend(backendURL) {
-  return withTransientRetry(async () => {
-    const res = await bridgeFetch(
-      "/api/cli/presentations",
-      { timeoutMs: listTimeoutMs() },
-      backendURL,
-    );
-    const data = await res.json();
-    const arr = Array.isArray(data?.presentations) ? data.presentations : [];
-    const env = deriveEnvLabel(backendURL);
-    return arr.map((p) => ({ ...p, backendURL, env }));
-  });
-}
-
-async function readinessForBackend(backendURL) {
-  const env = deriveEnvLabel(backendURL);
-  try {
-    // Retry only a 503: the add-in answers that (code `backend_unavailable`)
-    // while its session store cannot respond, and a 404 here means an older
-    // add-in without the readiness route, which the fallback below handles
-    // without waiting out the retry delays.
-    const res = await withTransientRetry(
-      () =>
-        bridgeFetch(
-          "/api/cli/readiness",
-          { timeoutMs: listTimeoutMs() },
-          backendURL,
-        ),
-      (err) => err?.status === 503 && err?.code !== "pane_suspended",
-    );
-    const data = (await res.json()) ?? {};
-    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,
-    };
-  } catch (err) {
-    if (err?.status !== 404) throw err;
-    // Older add-ins do not serve /readiness. Fall back to the legacy
-    // presentations route and mark the result as a compatibility response.
-    const presentations = await listPresentationsForBackend(backendURL);
-    return {
-      env,
-      backendURL,
-      ok: true,
-      readinessV1: false,
-      capabilities: null,
-      presentations,
-      summary: null,
-    };
-  }
-}
-
-export async function connectionStatus() {
-  const sessions = sessionsInScope();
-  const settled = await Promise.allSettled(
-    sessions.map((s) => readinessForBackend(s.backendURL)),
-  );
-  const backends = settled.map((r, i) => {
-    const backendURL = sessions[i].backendURL;
-    const env = deriveEnvLabel(backendURL);
-    if (r.status === "fulfilled") return r.value;
-    return {
-      env,
-      backendURL,
-      ok: false,
-      error: r.reason?.message ? r.reason.message : String(r.reason),
-      // Machine code of the failure (`backend_unavailable`, `session_invalid`,
-      // …) so the readiness ladder can tell "retry shortly" from "re-pair".
-      code: typeof r.reason?.code === "string" ? r.reason.code : null,
-      // The HTTP status too: a proxy's 503 carries no machine code (or only a
-      // prose `error`), and the ladder must still read it as "wait".
-      status: typeof r.reason?.status === "number" ? r.reason.status : null,
-      presentations: [],
-    };
-  });
-  return {
-    paired: sessions.length > 0,
-    backendCount: sessions.length,
-    backends,
-    presentations: backends.flatMap((b) => b.presentations ?? []),
-  };
-}
-
-// Fan out across every backend in scope, concurrently. Never rejects: each
-// backend's outcome is partitioned into merged presentations vs. a failure
-// record, so one unreachable environment can't hide the others.
-async function fanOutPresentations() {
-  const sessions = sessionsInScope();
-  const settled = await Promise.allSettled(
-    sessions.map((s) => listPresentationsForBackend(s.backendURL)),
-  );
-  const presentations = [];
-  const failures = [];
-  let fulfilledCount = 0;
-  settled.forEach((r, i) => {
-    const backendURL = sessions[i].backendURL;
-    if (r.status === "fulfilled") {
-      fulfilledCount += 1;
-      presentations.push(...r.value);
-    } else {
-      failures.push({
-        backendURL,
-        env: deriveEnvLabel(backendURL),
-        err: r.reason,
-      });
-    }
-  });
-  return { presentations, failures, fulfilledCount };
-}
-
-// Merged registry across all paired backends. Stays a flat array (every caller
-// expects one). Preserves single-backend behaviour: when nothing is reachable
-// AND no backend answered, the underlying bridge error propagates (so a typed
-// code like `pane_suspended` or a 401 still surfaces) — for several failing
-// backends it's an aggregate message.
-export async function listOpenPresentations() {
-  const { presentations, failures, fulfilledCount } =
-    await fanOutPresentations();
-  if (presentations.length === 0 && fulfilledCount === 0 && failures.length > 0) {
-    if (failures.length === 1) throw failures[0].err;
-    const err = new Error(
-      "slidemind: every paired backend failed to list presentations:\n" +
-        failures
-          .map((f) => `  ${f.env}: ${f.err.message}`)
-          .join("\n"),
-    );
-    throw err;
-  }
-  return presentations;
-}
-
-// 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 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;
-}
-
-// Like listOpenPresentations but never throws on per-backend failures — returns
-// the merged registry plus which backends were unreachable, for callers that
-// want to report partial results (requireHost, whoami).
-export async function listOpenPresentationsDetailed() {
-  const { presentations, failures } = await fanOutPresentations();
-  return {
-    presentations,
-    unreachable: failures.map((f) => ({
-      backendURL: f.backendURL,
-      env: f.env,
-      error: f.err?.message ? f.err.message : String(f.err),
-    })),
-  };
-}
-
-// Probe the bridge for an open PowerPoint host across every paired backend.
-// Returns the merged registry, or throws a single actionable message — the
-// shared precondition for every author/render command now that the design truth
-// lives in the add-in. Suspended entries (task-pane socket dropped, e.g.
-// PowerPoint backgrounded) count as registered: render + bundle work without
-// the pane, and a push waits server-side for the pane to reconnect.
-export async function requireHost() {
-  const { presentations, unreachable } = await listOpenPresentationsDetailed();
-  if (Array.isArray(presentations) && presentations.length > 0) {
-    return presentations;
-  }
-  // Nothing registered. Distinguish "a backend was unreachable" from "backends
-  // answered but no window is open" so the user gets the right next step.
-  if (unreachable.length > 0) {
-    throw new Error(
-      "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") +
-        `\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.\n" +
-      READY_HINT,
-  );
-}
-
-function hasReadinessFields(p) {
-  return (
-    p &&
-    (typeof p.connectionState === "string" ||
-      typeof p.designState === "string" ||
-      (p.capabilities && typeof p.capabilities === "object"))
-  );
-}
-
-export function isRenderReadyPresentation(p) {
-  if (!p) return false;
-  if (!hasReadinessFields(p)) return true;
-  if (p.capabilities?.render === true) return true;
-  if (p.designState === "ready" && p.capabilities?.render !== false) return true;
-  return false;
-}
-
-export function isPaneReadyPresentation(p) {
-  if (!p) return false;
-  if (!hasReadinessFields(p)) return p.connected !== false && !p.suspendedAt;
-  if (p.capabilities?.paneOps === true) return true;
-  return (
-    p.connectionState === "connected" &&
-    p.connected !== false &&
-    !p.suspendedAt &&
-    p.connectionState !== "stale"
-  );
-}
-
-async function waitForReadyPresentation(predicate, { timeoutMs = null } = {}) {
-  const waitMs = timeoutMs ?? readinessTimeoutMs();
-  const pollMs = envInt("SLIDEMIND_BRIDGE_READY_POLL_MS", 1500);
-  const deadline = Date.now() + waitMs;
-  for (;;) {
-    const { presentations, unreachable } = await listOpenPresentationsDetailed();
-    if (presentations.some(predicate)) return presentations;
-    // Do not wait when nothing is registered at all. Waiting helps only for an
-    // already-open pane that is still hydrating brand/readiness metadata.
-    if (presentations.length === 0 || Date.now() >= deadline) {
-      return { presentations, unreachable, timedOut: presentations.length > 0 };
-    }
-    await sleep(pollMs);
-  }
-}
-
-// 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)) {
-    return first.presentations;
-  }
-  if (first.presentations.length > 0) {
-    const waited = await waitForReadyPresentation(isRenderReadyPresentation, {
-      timeoutMs,
-    });
-    if (Array.isArray(waited)) return waited;
-    if (waited.presentations.some(isRenderReadyPresentation)) {
-      return waited.presentations;
-    }
-    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. " +
-        READY_HINT,
-    );
-  }
-  return requireHost();
-}
-
-export async function requirePaneHost({ timeoutMs = null } = {}) {
-  const first = await listOpenPresentationsDetailed();
-  if (first.presentations.some(isPaneReadyPresentation)) {
-    return first.presentations.filter(isPaneReadyPresentation);
-  }
-  if (first.presentations.length > 0) {
-    const waited = await waitForReadyPresentation(isPaneReadyPresentation, {
-      timeoutMs,
-    });
-    if (Array.isArray(waited)) return waited.filter(isPaneReadyPresentation);
-    if (waited.presentations.some(isPaneReadyPresentation)) {
-      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. " +
-        READY_HINT,
-    );
-  }
-  return requireHost();
-}
-
-// "Is a task pane available RIGHT NOW?" — the non-throwing twin of
-// requirePaneHost, for paths where an open pane is an OPTION rather than a
-// precondition (a stale permission snapshot can be routed around by relaying
-// through a live pane, which signs each request with a fresh browser token).
-// Never waits for hydration and never authors a blocker: an empty array means
-// "no, carry on with what you were doing", not "stop".
-export async function paneReadyPresentations() {
-  try {
-    const { presentations } = await listOpenPresentationsDetailed();
-    return presentations.filter(isPaneReadyPresentation);
-  } catch {
-    return [];
-  }
-}
-
-// Tie-break a multi-backend presId collision without bothering the user when
-// only one candidate can actually serve the deck:
-//   (a) exactly one CONNECTED pane whose active CD matches the deck's bundle
-//       ref (`preferBrandId` — the deck's presFP, which equals the pane's
-//       brandId by the bundle-cache contract);
-//   (b) else exactly one connected pane with ANY active CD (brandId set) —
-//       e.g. a local dev backend connected without a CD next to prod with one.
-// Returns the winning entry or null when genuinely ambiguous.
-function tieBreakMatches(matches, preferBrandId) {
-  const live = matches.filter(isPaneReadyPresentation);
-  if (preferBrandId) {
-    const want = live.filter((m) => m.brandId === preferBrandId);
-    if (want.length === 1) return want[0];
-  }
-  const withCd = live.filter((m) => m.brandId);
-  if (withCd.length === 1) return withCd[0];
-  return null;
-}
-
-// Resolve which backend a presId lives on via a LIVE fan-out list (never a
-// cached map — a presId can move backends on re-pair/redeploy). Throws an
-// actionable message on a miss, or an ambiguity error when the same presId is
-// open on more than one reachable backend and no tie-break rule settles it.
-export async function resolveBackendForPres(
-  presId,
-  { preferBrandId = null } = {},
-) {
-  if (!presId) throw new Error("resolveBackendForPres: presId is required");
-  const { presentations } = await fanOutPresentations();
-  const matches = presentations.filter((p) => p.presId === presId);
-  if (matches.length === 1) return matches[0].backendURL;
-  if (matches.length > 1) {
-    const winner = tieBreakMatches(matches, preferBrandId);
-    if (winner) return winner.backendURL;
-    const envs = matches.map((m) => m.env).join(", ");
-    throw new Error(
-      `Presentation '${presId}' is open on multiple environments: ${envs}, ` +
-        "and no single connected one has the deck's corporate design active. " +
-        "Disambiguate with --backend <env|label> (or SLIDEMIND_BACKEND).",
-    );
-  }
-  throw new Error(
-    `No open PowerPoint window registered with presId='${presId}' on any paired backend. ` +
-      "Run 'slidemind presentations' to see what's open.",
-  );
-}
-
-// Wait for a presentation's task pane to come back after a `pane_suspended`
-// (PowerPoint backgrounded → webview suspended → socket dropped). Polls the
-// live registry; succeeds on the same presId reconnecting, OR on a CONNECTED
-// entry matching `fileName` + `brandId` — a pane reconnect can mint a NEW
-// presId for the same window, so identity-by-content covers the churn. Returns
-// the live registry entry (caller re-targets from it), or null on timeout.
-// `onWait` fires once with the wait budget in seconds — the caller's single
-// actionable "click the pane" line.
-//
-// `otherPresIds` are windows the caller already knows are NOT the target (the
-// rest of the registry it picked from). They are excluded from the last-resort
-// design-fingerprint match — see below.
-export async function waitForPaneReady(
-  presId,
-  {
-    backendURL = null,
-    fileName = null,
-    brandId = null,
-    otherPresIds = null,
-    timeoutMs = null,
-    pollMs = null,
-    onWait = null,
-  } = {},
-) {
-  const notTheTarget = new Set(otherPresIds ?? []);
-  const waitMs =
-    timeoutMs ?? envInt("SLIDEMIND_BRIDGE_PANE_READY_TIMEOUT_MS", 120000);
-  const stepMs = pollMs ?? envInt("SLIDEMIND_BRIDGE_PANE_READY_POLL_MS", 3000);
-  const deadline = Date.now() + waitMs;
-  let notified = false;
-  for (;;) {
-    let list = [];
-    try {
-      list = backendURL
-        ? await listPresentationsForBackend(backendURL)
-        : (await fanOutPresentations()).presentations;
-    } catch {
-      /* transient list failure — poll again until the deadline */
-    }
-    const connected = list.filter(
-      (p) => isPaneReadyPresentation(p),
-    );
-    const same = connected.find((p) => p.presId === presId);
-    if (same) return same;
-    if (fileName || brandId) {
-      const rematch = connected.find(
-        (p) =>
-          (!fileName || p.fileName === fileName || p.title === fileName) &&
-          (!brandId || p.brandId === brandId),
-      );
-      if (rematch) return rematch;
-      // Last resort: match on the design fingerprint alone (presFP == brandId).
-      // A reconnect can report a different name for the same window — the user
-      // hit Save As, or the pane reports the title where it used to report the
-      // file name — but the active corporate design does not change with it.
-      // Only when EXACTLY one connected window carries it: two windows on the
-      // same design are indistinguishable, and pushing into the wrong one is
-      // worse than waiting.
-      //
-      // A window the caller ALREADY saw next to the target is not a churned
-      // target — it is a different presentation that merely shares the design
-      // (most tenants run exactly one), and retargeting to it would append the
-      // deck's slides to an unrelated file. Most tenants run a single corporate
-      // design, so brandId alone is not window identity.
-      if (fileName && brandId) {
-        const byBrand = connected.filter(
-          (p) => p.brandId === brandId && !notTheTarget.has(p.presId),
-        );
-        if (byBrand.length === 1) return byBrand[0];
-      }
-    }
-    if (Date.now() >= deadline) return null;
-    if (!notified) {
-      notified = true;
-      onWait?.(Math.round(waitMs / 1000));
-    }
-    await sleep(stepMs);
-  }
-}
-
-// The one actionable line a human needs when a pane op is waiting. stderr so
-// 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 " +
-      `(waiting up to ${seconds}s)…\n`,
-  );
-}
-
-// The window is gone from the registry but its pane may already be back under a
-// new presId (churn on every reconnect) — nothing for the user to do here, so
-// say what the CLI is doing rather than asking for a click.
-function paneRetargetNotice(seconds) {
-  process.stderr.write(
-    "the target PowerPoint window re-registered — re-matching it by corporate " +
-      `design (up to ${seconds}s)…\n`,
-  );
-}
-
-// GET the full design bundle (tokens, css, layouts, designRules, signed asset
-// URLs, engines) for the presentation's active corporate design.
-export async function getDesignBundle(
-  presId,
-  { backendURL = null, preferBrandId = null } = {},
-) {
-  if (!presId) throw new Error("getDesignBundle: presId is required");
-  const be =
-    backendURL || (await resolveBackendForPres(presId, { preferBrandId }));
-  return withTransientRetry(async () => {
-    const res = await bridgeFetch(
-      `/api/cli/presentations/${encodeURIComponent(presId)}/design-bundle`,
-      {},
-      be,
-    );
-    return res.json();
-  });
-}
-
-// 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;
-}
-
-// The corporate designs this user may build against, straight off the CLI
-// session — no open window, no pane. One entry per design: `{ presFP, name,
-// env }`, where presFP IS the brandId every pane-free route is keyed by. Only
-// backends advertising `brandsList` are asked (older ones have no such route);
-// a backend that fails is skipped rather than failing the whole answer, so one
-// unreachable environment can't hide another's designs.
-export async function listBrands() {
-  const out = [];
-  for (const s of sessionsInScope()) {
-    if (!(await backendSupportsBrandsList(s.backendURL))) continue;
-    const env = deriveEnvLabel(s.backendURL);
-    try {
-      const res = await bridgeFetch(
-        "/api/cli/brands",
-        { timeoutMs: listTimeoutMs() },
-        s.backendURL,
-      );
-      const data = (await res.json()) ?? {};
-      const arr = Array.isArray(data.brands) ? data.brands : [];
-      for (const b of arr) {
-        // The wire may name the design by either of its two equivalent keys
-        // (presFP on the bundle contract, brandId on the routes) — normalize to
-        // the one the deck ref stores.
-        const presFP = b?.presFP ?? b?.brandId ?? b?.id ?? null;
-        if (!presFP) continue;
-        out.push({
-          presFP,
-          name: b?.name ?? b?.designName ?? null,
-          env,
-          backendURL: s.backendURL,
-        });
-      }
-    } catch {
-      /* unreachable / not granted — that environment simply contributes none */
-    }
-  }
-  return out;
-}
-
-// Concept-image generation is a heavy provider call (per-image cap ~180s
-// server-side). Budget just over that so a typed server error wins over a
-// client timeout, but keep it below the relay's ~240s ingress cap — the CLI
-// batches per-slide so no single request approaches that ceiling.
-function conceptTimeoutMs() {
-  return (
-    parseInt(process.env.SLIDEMIND_BRIDGE_CONCEPT_TIMEOUT_MS || "200000", 10) ||
-    200000
-  );
-}
-
-async function postConceptImages(
-  brandId,
-  { planMarkdown, slideNumbers, references },
-  backendURL,
-) {
-  const body = { planMarkdown };
-  if (Array.isArray(slideNumbers) && slideNumbers.length > 0) {
-    body.slideNumbers = slideNumbers;
-  }
-  // The user's own images, inline: `{ role: "concept" | "style", image:
-  // <data URI>, slides?: number[], name? }`. A concept replaces the generated
-  // mockup for its slides; a style reference leads the generation.
-  if (Array.isArray(references) && references.length > 0) {
-    body.references = references;
-  }
-  const res = await bridgeFetch(
-    `/api/cli/brands/${encodeURIComponent(brandId)}/concept-images`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
-      timeoutMs: conceptTimeoutMs(),
-    },
-    backendURL,
-  );
-  const data = (await res.json()) ?? {};
-  // Tag the response with the backend that answered so a per-slide batch can
-  // pin subsequent calls to the same one (routing state only — never printed).
-  return { ...data, backendURL };
-}
-
-// Generate concept mockup images for a brand over the pane-free brand route.
-// Body `{ planMarkdown, slideNumbers?, references? }`; the optional `slideNumbers`
-// filters which storyboard beats are rendered (the CLI batches per-slide);
-// `references` carries the user's own concept/style images inline. Returns the
-// server's `{ ok, images, slideCount }` augmented with the resolved
-// `backendURL`. When `backendURL` is given it posts directly; otherwise it
-// fans out — like getDesignBundleForBrandAnyBackend, presFP/brandId is globally
-// unique so at most one paired backend answers 2xx. Throws a typed
-// `concept_route_unavailable` when no backend serves the brand (old add-ins,
-// unknown brand, missing grant) so callers can degrade to "continue without".
-export async function generateConceptImagesForBrand(
-  brandId,
-  { planMarkdown, slideNumbers = null, references = null, backendURL = null } = {},
-) {
-  if (!brandId) {
-    throw new Error("generateConceptImagesForBrand: brandId is required");
-  }
-  if (typeof planMarkdown !== "string" || !planMarkdown.trim()) {
-    throw new Error("generateConceptImagesForBrand: planMarkdown is required");
-  }
-  if (backendURL) {
-    return postConceptImages(
-      brandId,
-      { planMarkdown, slideNumbers, references },
-      backendURL,
-    );
-  }
-  const sessions = sessionsInScope();
-  const failures = [];
-  for (const s of sessions) {
-    try {
-      if (!(await backendSupportsConceptImages(s.backendURL))) {
-        failures.push({
-          env: deriveEnvLabel(s.backendURL),
-          reason: "no concept-images route",
-        });
-        continue;
-      }
-      return await postConceptImages(
-        brandId,
-        { planMarkdown, slideNumbers, references },
-        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 generates concept mockups for design '${brandId}'` +
-      `${detail ? ` (${detail})` : ""}.`,
-  );
-  err.code = "concept_route_unavailable";
-  throw err;
-}
-
-// gpt-image calls routinely take 60-120s; budget like the concept relay so a
-// typed server error wins over a client timeout.
-function imagenTimeoutMs() {
-  return (
-    parseInt(process.env.SLIDEMIND_BRIDGE_IMAGEN_TIMEOUT_MS || "200000", 10) ||
-    200000
-  );
-}
-
-async function postGenerateImage(brandId, body, backendURL) {
-  const res = await bridgeFetch(
-    `/api/cli/brands/${encodeURIComponent(brandId)}/images`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
-      timeoutMs: imagenTimeoutMs(),
-    },
-    backendURL,
-  );
-  const data = (await res.json()) ?? {};
-  return { ...data, backendURL };
-}
-
-// Generate ONE regular image over the pane-free brand route
-// (`slidemind imagen`). Body `{ prompt, size?, quality? }`;
-// returns the server's `{ ok, image }` augmented with the
-// resolved `backendURL`. Fan-out and degradation mirror
-// generateConceptImagesForBrand: throws a typed `imagen_route_unavailable`
-// when no paired backend serves the route (older add-ins, unknown brand,
-// missing grant) so callers can print the one actionable fix.
-export async function generateImageForBrand(
-  brandId,
-  { prompt, size = null, quality = null, backendURL = null } = {},
-) {
-  if (!brandId) {
-    throw new Error("generateImageForBrand: brandId is required");
-  }
-  if (typeof prompt !== "string" || !prompt.trim()) {
-    throw new Error("generateImageForBrand: prompt is required");
-  }
-  const body = { prompt };
-  if (size) body.size = size;
-  if (quality) body.quality = quality;
-  if (backendURL) {
-    return postGenerateImage(brandId, body, backendURL);
-  }
-  const sessions = sessionsInScope();
-  const failures = [];
-  for (const s of sessions) {
-    try {
-      if (!(await backendSupportsImageGeneration(s.backendURL))) {
-        failures.push({
-          env: deriveEnvLabel(s.backendURL),
-          reason: "no image-generation route (update the add-in)",
-        });
-        continue;
-      }
-      return await postGenerateImage(brandId, body, 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 generates images for design '${brandId}'` +
-      `${detail ? ` (${detail})` : ""}.`,
-  );
-  err.code = "imagen_route_unavailable";
-  throw err;
-}
-
-// Deterministic PPTX→JSX conversion is a per-slide OOXML parse + a render pass
-// per converted slide — a whole foreign deck runs in render-grade time, not
-// list-grade. Budget like the render routes.
-function convertTimeoutMs() {
-  return (
-    parseInt(process.env.SLIDEMIND_BRIDGE_CONVERT_TIMEOUT_MS || "300000", 10) ||
-    300000
-  );
-}
-
-// Minimal multipart/form-data body. The route takes an uploaded PPTX, and
-// nodeRequest writes a Buffer verbatim — no fetch/FormData involved, so the
-// envelope is assembled here (fields first, file last, boundary never appearing
-// in the parts because it carries a random suffix).
-function multipartBody(fields, file) {
-  const boundary = `----slidemind${randomUUID().replace(/-/g, "")}`;
-  const chunks = [];
-  for (const [name, value] of Object.entries(fields)) {
-    if (value === null || value === undefined) continue;
-    chunks.push(
-      Buffer.from(
-        `--${boundary}\r\nContent-Disposition: form-data; name="${name}"\r\n\r\n${value}\r\n`,
-      ),
-    );
-  }
-  // The file name reaches this from a path on disk; a quote or a newline in it
-  // would break out of the Content-Disposition header and forge a part.
-  const safeFileName = String(file.fileName).replace(/[\r\n"\\]/g, "_");
-  chunks.push(
-    Buffer.from(
-      `--${boundary}\r\nContent-Disposition: form-data; name="${file.name}"; ` +
-        `filename="${safeFileName}"\r\nContent-Type: ${file.contentType}\r\n\r\n`,
-    ),
-    Buffer.from(file.bytes),
-    Buffer.from(`\r\n--${boundary}--\r\n`),
-  );
-  return {
-    body: Buffer.concat(chunks),
-    contentType: `multipart/form-data; boundary=${boundary}`,
-  };
-}
-
-// Whether a backend deterministically converts foreign PPTX slides to jsx
-// (`POST /api/cli/brands/:brandId/convert-pptx`). Advertised only by add-ins
-// running with the reverse-conversion flag on; everywhere else `slidemind
-// adopt` folds untagged slides in as native .pptx exactly as before.
-export async function backendSupportsConvertPptx(backendURL) {
-  const caps = await backendCapabilities(backendURL);
-  return caps?.convertPptx === true;
-}
-
-async function postConvertPptx(brandId, { bytes, fileName, slides }, backendURL) {
-  const { body, contentType } = multipartBody(
-    {
-      // 1-based play-order slide numbers to convert. Omitted = the whole deck;
-      // `adopt` always names the untagged ones so tagged slides are not re-parsed.
-      slides: Array.isArray(slides) && slides.length > 0 ? slides.join(",") : null,
-    },
-    {
-      name: "file",
-      fileName: path.basename(fileName || "deck.pptx"),
-      contentType:
-        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-      bytes,
-    },
-  );
-  const res = await bridgeFetch(
-    `/api/cli/brands/${encodeURIComponent(brandId)}/convert-pptx`,
-    {
-      method: "POST",
-      headers: { "content-type": contentType },
-      body,
-      timeoutMs: convertTimeoutMs(),
-    },
-    backendURL,
-  );
-  const data = (await res.json()) ?? {};
-  return { ...data, backendURL };
-}
-
-// Convert a FILE deck's foreign slides to converted-dialect jsx over the
-// pane-free brand route (`slidemind adopt`). Body is multipart: the .pptx plus
-// the 1-based slide numbers to convert. Returns the server's
-// `{ slides, layouts, assets, sourceBaselines, conversionEvidence, skipped,
-// warnings }` (add-in `ConvertPptxResponse`) augmented with the resolved
-// `backendURL`. Identity and evidence are keyed by each slide's jsx `path`, not
-// carried on the slide — `src/lib/adopt.mjs` `convertedByNumber()` is the one
-// place that key shape is unfolded.
-//
-// LIVE decks are NOT convertible through this route in v1: converting an open
-// presentation needs a slide export + tag read over the relay, and neither
-// event exists (design D9) — the add-in path owns that flow.
-//
-// Fan-out and degradation mirror generateConceptImagesForBrand: throws a typed
-// `convert_route_unavailable` when no paired backend serves the route (older
-// add-ins, the reverse flag off, unknown brand, missing grant) so `adopt` falls
-// back to the native fold instead of failing.
-export async function convertPptxForBrand(
-  brandId,
-  { bytes, fileName = "deck.pptx", slides = null, backendURL = null } = {},
-) {
-  if (!brandId) throw new Error("convertPptxForBrand: brandId is required");
-  if (!bytes) throw new Error("convertPptxForBrand: bytes is required");
-  if (backendURL) {
-    return postConvertPptx(brandId, { bytes, fileName, slides }, backendURL);
-  }
-  const sessions = sessionsInScope();
-  const failures = [];
-  for (const s of sessions) {
-    try {
-      if (!(await backendSupportsConvertPptx(s.backendURL))) {
-        failures.push({
-          env: deriveEnvLabel(s.backendURL),
-          reason: "no convert-pptx route",
-        });
-        continue;
-      }
-      return await postConvertPptx(
-        brandId,
-        { bytes, fileName, slides },
-        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 converts foreign slides for design '${brandId}'` +
-      `${detail ? ` (${detail})` : ""}.`,
-  );
-  err.code = "convert_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
-// its short `env` label (never the backendURL — the no-URL rule). Filter by
-// engine `type` (collection|search) and/or `subtype` (image|slide|template|
-// content). Returns a flat `{ engines: [...], catalog }` like the single-backend
-// route.
-//
-// `catalog` is the pane-free route's summary — `{totalEngines, totalScopes,
-// filtered, emptyEngines}`, counted BEFORE the type/subtype filter — and it is
-// what separates "this filter matched nothing" from "this deployment has no
-// engines". Older backends (and the pane-relay path) send none; it stays null
-// there and every caller falls back to its pre-summary wording.
-function readCatalogSummary(data) {
-  const c = data?.catalog;
-  if (!c || typeof c !== "object" || Array.isArray(c)) return null;
-  const num = (v) => (Number.isFinite(v) ? v : 0);
-  return {
-    totalEngines: num(c.totalEngines),
-    totalScopes: num(c.totalScopes),
-    filtered: Boolean(c.filtered),
-    emptyEngines: num(c.emptyEngines),
-  };
-}
-
-async function listEnginesForBackend(backendURL, { type = null, subtype = null } = {}) {
-  return withTransientRetry(async () => {
-    const params = new URLSearchParams();
-    if (type) params.set("type", type);
-    if (subtype) params.set("subtype", subtype);
-    const qs = params.toString();
-    const res = await bridgeFetch(
-      `/api/cli/engines${qs ? `?${qs}` : ""}`,
-      // Pane-relayed on the add-in side — needs the engine budget, not the 8s
-      // list timeout (which bailed before the pane could ever answer). The
-      // delegated tokens authorize the pane-free catalog (login_required
-      // without them); older add-ins ignore the headers.
-      { timeoutMs: engineTimeoutMs(), headers: await graphHeaders(backendURL) },
-      backendURL,
-    );
-    const data = await res.json();
-    const arr = Array.isArray(data?.engines) ? data.engines : [];
-    const env = deriveEnvLabel(backendURL);
-    return {
-      engines: arr.map((e) => ({ ...e, env })),
-      catalog: readCatalogSummary(data),
-    };
-  });
-}
-
-// A scope (scope:all / scope:sharepoint) is not one environment's object: it is
-// the same saved search target, named identically on every deployment. Pooling
-// two backends' catalogs therefore repeats it verbatim — same id, same label —
-// which reads as two different things to choose between. Real engines DO differ
-// per environment and keep their duplicates; their `env` tag tells them apart.
-function isScopeRow(e) {
-  return e?.type === "scope" || /^scope:/.test(String(e?.id ?? ""));
-}
-
-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 })),
-  );
-  const engines = [];
-  const catalogs = [];
-  const failures = [];
-  // Which environments actually contributed. NOT derivable from the pooled rows
-  // any more: a second environment that only repeated the scopes leaves no row
-  // of its own, and the human renderer keys its `[env]` tags off this.
-  const envs = [];
-  // Scope id → the one pooled row kept for it.
-  const scopeRows = new Map();
-  let fulfilledCount = 0;
-  settled.forEach((r, i) => {
-    if (r.status === "fulfilled") {
-      fulfilledCount += 1;
-      envs.push(deriveEnvLabel(sessions[i].backendURL));
-      for (const e of r.value.engines) {
-        const id = typeof e?.id === "string" ? e.id : null;
-        if (id && isScopeRow(e)) {
-          const kept = scopeRows.get(id);
-          if (kept) {
-            // Contributed by more than one environment, so it belongs to none
-            // of them in particular — drop the tag rather than crediting
-            // whichever backend happened to answer first.
-            kept.env = null;
-            continue;
-          }
-          const row = { ...e };
-          scopeRows.set(id, row);
-          engines.push(row);
-          continue;
-        }
-        engines.push(e);
-      }
-      if (r.value.catalog) catalogs.push(r.value.catalog);
-    } else {
-      failures.push({ env: deriveEnvLabel(sessions[i].backendURL), err: r.reason });
-    }
-  });
-  // Mirror listOpenPresentations: only surface an error when nothing answered.
-  if (engines.length === 0 && fulfilledCount === 0 && failures.length > 0) {
-    if (failures.length === 1) throw failures[0].err;
-    throw new Error(
-      "slidemind: every paired backend failed to list engines:\n" +
-        failures.map((f) => `  ${f.env}: ${f.err.message}`).join("\n"),
-    );
-  }
-  // Fanned out, the summary is the sum of what each environment reported: the
-  // engines are pooled into one list, so their counts pool too. SCOPES are the
-  // exception — the same named targets everywhere, deduped above — so summing
-  // them double-counts; the distinct total is the largest environment's count,
-  // or the number of distinct scope rows actually pooled when that is larger.
-  // (The catalog counts are pre-filter and the rows post-filter, which is why
-  // both terms are needed.) `filtered` is the same question asked of every
-  // backend, so any one of them saying yes is the answer. Null when no backend
-  // supplied one (old add-in / pane relay).
-  const catalog = catalogs.length
-    ? {
-        totalEngines: catalogs.reduce((n, c) => n + c.totalEngines, 0),
-        totalScopes: Math.max(...catalogs.map((c) => c.totalScopes), scopeRows.size),
-        filtered: catalogs.some((c) => c.filtered),
-        emptyEngines: catalogs.reduce((n, c) => n + c.emptyEngines, 0),
-      }
-    : null;
-  return { engines, catalog, envs };
-}
-
-// ---------------------------------------------------------------------------
-// Server-side OOXML render
-// ---------------------------------------------------------------------------
-//
-// Two protocols, newest first:
-//   1. Render JOBS (preferred): POST creates a job, the CLI polls cheap status
-//      GETs and fetches the result when done. A full deck render routinely
-//      outlives the cloud ingress's ~240s request cap — only short polling
-//      requests survive that reliably, and they carry per-slide progress.
-//   2. Sync render (fallback): one POST held open for the whole render. Kept
-//      for older backends that don't serve /api/cli/capabilities yet.
-
-function envInt(name, fallback) {
-  const n = parseInt(process.env[name] || "", 10);
-  return Number.isFinite(n) && n > 0 ? n : fallback;
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, 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 backendCapabilitiesCache = new Map();
-
-// The probe result, failure included. Every ordinary caller wants the graceful
-// `{}` (an older backend simply 404s this path), but a caller that is DIAGNOSING
-// has to see a 401 — "this session is revoked" must never be reported as "this
-// add-in is too old". Kept as one cached promise so the distinction costs no
-// extra round-trip.
-function backendCapabilitiesResult(backendURL) {
-  let probe = backendCapabilitiesCache.get(backendURL);
-  if (!probe) {
-    probe = (async () => {
-      try {
-        const res = await bridgeFetch(
-          "/api/cli/capabilities",
-          { timeoutMs: listTimeoutMs() },
-          backendURL,
-        );
-        return { caps: (await res.json()) ?? {}, error: null };
-      } catch (err) {
-        // Older backends 404 this path (with a non-JSON body) — no
-        // capabilities: sync render, no version floor.
-        return { caps: {}, error: err };
-      }
-    })();
-    backendCapabilitiesCache.set(backendURL, probe);
-  }
-  return probe;
-}
-
-async function backendCapabilities(backendURL) {
-  return (await backendCapabilitiesResult(backendURL)).caps;
-}
-
-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;
-}
-
-// Whether a backend generates concept mockup images for a brand over the
-// pane-free `/api/cli/brands/:brandId/concept-images` route (see
-// generateConceptImagesForBrand). Advertised by newer add-ins only; older ones
-// omit the flag and the caller degrades to "continue without".
-export async function backendSupportsConceptImages(backendURL) {
-  const caps = await backendCapabilities(backendURL);
-  return caps?.conceptImages === true;
-}
-
-// Whether a backend generates regular images over the pane-free
-// `/api/cli/brands/:brandId/images` route (see generateImageForBrand).
-// Advertised by newer add-ins only.
-export async function backendSupportsImageGeneration(backendURL) {
-  const caps = await backendCapabilities(backendURL);
-  return caps?.imageGeneration === true;
-}
-
-// Whether a backend can list the corporate designs a user may build against
-// (`GET /api/cli/brands`). It is what lets `ready` bind a deck with PowerPoint
-// closed — without it the only way to learn a design's identity is an open
-// window. Advertised by newer add-ins only.
-export async function backendSupportsBrandsList(backendURL) {
-  const caps = await backendCapabilities(backendURL);
-  return caps?.brandsList === true;
-}
-
-// Whether a backend can read the SOURCE deck behind a chosen slide search
-// result (`/api/cli/presentations/:presId/source-presentation`). Advertised by
-// newer add-ins only; older ones omit the flag and the caller must say so
-// rather than surfacing a bare 404.
-export async function backendSupportsSourcePresentation(backendURL) {
-  const caps = await backendCapabilities(backendURL);
-  return caps?.sourcePresentation === true;
-}
-
-// Pane-free ENGINE routes (`/api/cli/engines`, `/api/cli/searches/*`): engine
-// discovery, search and every per-result fetch answered off the CLI session
-// itself instead of being relayed through the task-pane webview — the one
-// transport that a backgrounded PowerPoint is free to suspend mid-run.
-// Advertised by newer add-ins only; older ones keep the pane relay, which stays
-// as the compat path (see the direct-route block further down).
-export async function backendSupportsEngineRoutes(backendURL) {
-  const caps = await backendCapabilities(backendURL);
-  return caps?.engineRoutes === true;
-}
-
-// Whether a backend honours a delegated Microsoft Graph token on the pane-free
-// engine routes — the CLI's own identity for SharePoint-backed content
-// (`slidemind login`, src/bridge/graph-auth.mjs). Gates BOTH the attach and the
-// remediation text: naming `slidemind login` on an add-in that ignores the token
-// would send a user through a browser flow that changes nothing.
-export async function backendSupportsGraphDelegated(backendURL) {
-  const caps = await backendCapabilities(backendURL);
-  return caps?.graphDelegated === 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;
-  throw cliUpdateRequiredError(min);
-}
-
-// Rebuild a job failure into the exact error shape bridgeFetch throws for the
-// sync route, so callers (etag self-heal, error texts) can't tell the
-// protocols apart.
-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 ${label}: ${detail}`,
-  );
-  err.status = status;
-  err.code = detail;
-  err.body = { error: detail, ...(jobError?.extra ?? {}) };
-  return err;
-}
-
-// 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(
-    `${basePath}/render-pptx`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
-      // Server-side OOXML render is a heavy operation — a full deck of richly
-      // composed slides routinely runs well past the 35s default. Treat it like
-      // a mutation: give it a generous default and let env override it.
-      timeoutMs:
-        parseInt(process.env.SLIDEMIND_BRIDGE_RENDER_TIMEOUT_MS || "300000", 10) ||
-        300000,
-    },
-    backendURL,
-  );
-  return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
-}
-
-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(
-    "SLIDEMIND_BRIDGE_RENDER_RESULT_TIMEOUT_MS",
-    120000,
-  );
-
-  const createJob = async () => {
-    // Deliberately NOT wrapped in withTransientRetry: its blanket 404 retry
-    // would re-upload a multi-MB slide payload, and creation errors (stale
-    // etag, no CD, unknown presId) are definitive.
-    const res = await bridgeFetch(
-      `${basePath}/render-jobs`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
-        timeoutMs:
-          parseInt(process.env.SLIDEMIND_BRIDGE_TIMEOUT_MS || "35000", 10) ||
-          35000,
-      },
-      backendURL,
-    );
-    const data = await res.json();
-    if (!data?.jobId) throw new Error("render-jobs returned no jobId");
-    return data.jobId;
-  };
-
-  let jobId = await createJob();
-  let resubmitted = false;
-  let lastReported = "";
-  const deadline = Date.now() + deadlineMs;
-
-  for (;;) {
-    if (Date.now() > deadline) {
-      const err = new Error(
-        `slidemind render did not finish within ${deadlineMs}ms ` +
-          "(raise SLIDEMIND_BRIDGE_RENDER_DEADLINE_MS for very large decks). " +
-          "The render keeps running server-side — retrying may pick up a warm cache.",
-      );
-      err.code = "bridge_timeout";
-      throw err;
-    }
-    await sleep(pollMs);
-
-    let status;
-    try {
-      const res = await bridgeFetch(
-        `/api/cli/render-jobs/${encodeURIComponent(jobId)}`,
-        { timeoutMs: 15000 },
-        backendURL,
-      );
-      status = await res.json();
-    } catch (err) {
-      // 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" }, label);
-        resubmitted = true;
-        onProgress?.({ state: "restarted" });
-        jobId = await createJob();
-        continue;
-      }
-      // Rate-limited poll: honor the window, then resume.
-      if (err?.status === 429) {
-        const retryAfterSec = err?.body?.retryAfterSec;
-        await sleep(Math.min((retryAfterSec || 5) * 1000, 30000));
-        continue;
-      }
-      // Anything else (network blip, 5xx, replica restart) — polling is
-      // idempotent; just poll again until the deadline.
-      continue;
-    }
-
-    if (onProgress) {
-      const snapshot = JSON.stringify([status.state, status.progress]);
-      if (snapshot !== lastReported) {
-        lastReported = snapshot;
-        onProgress({ state: status.state, ...(status.progress ?? {}) });
-      }
-    }
-
-    if (status.state === "failed") {
-      const jobError = status.error ?? { status: 500, error: "render_failed" };
-      // The rendering replica died (deploy, crash, scale-in). Renders are
-      // idempotent — resubmit once before giving up.
-      if (jobError.error === "job_lost" && !resubmitted) {
-        resubmitted = true;
-        onProgress?.({ state: "restarted" });
-        jobId = await createJob();
-        continue;
-      }
-      throw jobFailureError(jobError, label);
-    }
-
-    if (status.state === "done") {
-      // The result may be tens of MB — generous timeout, and a couple of
-      // retries for transient blips (the stored result is re-fetchable).
-      for (let attempt = 0; ; attempt += 1) {
-        try {
-          const res = await bridgeFetch(
-            `/api/cli/render-jobs/${encodeURIComponent(jobId)}/result`,
-            { timeoutMs: resultTimeoutMs },
-            backendURL,
-          );
-          return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
-        } catch (err) {
-          if (
-            attempt >= 2 ||
-            err?.code === "result_expired" ||
-            err?.code === "job_not_found"
-          ) {
-            throw err;
-          }
-          await sleep(pollMs);
-        }
-      }
-    }
-  }
-}
-
-// Server-side OOXML render: ship authored slide JSX (+ deck-local assets) and
-// get back a native .pptx (base64) rendered against the presentation's own CD.
-// `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 = null,
-  brandId = null,
-  deckName = null,
-  slides,
-  deckAssets = null,
-  nativeSlides = null,
-  etag = null,
-  sourceGuids = null,
-  conversions = null,
-  reconcile = null,
-  backendURL = null,
-  onProgress = null,
-}) {
-  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");
-  }
-  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;
-  }
-  // Reused native one-slide .pptx (base64), keyed by play-order filename — the
-  // server splices them in by numeric-aware sorted filename (contract #7).
-  if (hasNative) body.nativeSlides = nativeSlides;
-  if (etag) body.etag = etag;
-  // Deck-embedded source: known slide GUIDs (jsx path → sm-<uuid>) so the
-  // server's tag bake keeps identities stable; minted ones ride back as
-  // `sourceGuids` on the response.
-  if (sourceGuids && Object.keys(sourceGuids).length > 0) {
-    body.sourceGuids = sourceGuids;
-  }
-  // Reverse-converted slides (`slidemind adopt`): identity + fidelity evidence
-  // per converted jsx file, so the server can gate the first replacement of a
-  // converted slide against what it originally converted, plus the verbatim
-  // source package whose preserved natives (chart / OLE / SmartArt) it splices
-  // back into the rendered slide. Keyed exactly like `slides`. Additive: a deck
-  // with no conversions sends the same body it always did.
-  if (conversions && Object.keys(conversions).length > 0) {
-    body.conversions = conversions;
-  }
-  // Manual-edit reconcile: for every slide the user edited in PowerPoint since
-  // the last build, the baked baseline projection and the current one, keyed
-  // exactly like `slides`. The server diffs them, folds text edits into the jsx
-  // it renders, and reports the rest — the CLI owns no diff source. Additive: a
-  // deck with no pending edits sends the same body it always did, and the
-  // response's `reconcile` echo is what proves the backend understood it.
-  if (reconcile && Object.keys(reconcile).length > 0) {
-    body.reconcile = reconcile;
-  }
-  // 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({ 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({ basePath, body, backendURL: be });
-}
-
-// Translate a deck the CLI captured LOCALLY (the shipped capture engine) into a
-// native .pptx. The slow Chrome work already ran client-side, so this is a fast
-// 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 = null,
-  brandId = null,
-  deckName = null,
-  captured,
-  nativeSlides = null,
-  etag = null,
-  backendURL = null,
-}) {
-  if (!presId && !brandId) {
-    throw new Error("translateDeck: presId or brandId is required");
-  }
-  if (!captured) throw new Error("translateDeck: captured is required");
-  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
-  // #7). The slow capture already ran client-side; native slides are pass-through.
-  if (nativeSlides && Object.keys(nativeSlides).length > 0) {
-    body.nativeSlides = nativeSlides;
-  }
-  if (etag) body.etag = etag;
-  if (brandId && deckName) body.deckName = deckName;
-  const res = await bridgeFetch(
-    `${renderBasePath({ presId, brandId })}/translate`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
-      // The body carries inlined image bytes and the response a base64 .pptx —
-      // bandwidth, not server compute. Give it the render-grade timeout.
-      timeoutMs:
-        parseInt(process.env.SLIDEMIND_BRIDGE_RENDER_TIMEOUT_MS || "300000", 10) ||
-        300000,
-    },
-    be,
-  );
-  return res.json(); // { ok, base64, slideCount, warnings, skippedSlides }
-}
-
-// A 404 the RELAY emitted about the presId itself (the window is no longer in
-// the registry — a pane reconnect mints a new presId for the same window)
-// rather than one a ROUTE emitted about something else it was asked for (a
-// stale `unknown_search`, an unimplemented route). Only the former is worth
-// re-targeting: the same window is probably back under a new id.
-//
-// Read the PARSED code, never `err.code`: bridgeFetch falls that back to the
-// human error string, and the relay's vanished-presId 404 carries prose only
-// ("No PowerPoint window registered for presId='X'") — so testing `err.code`
-// saw a truthy, unmatched value and never retargeted anything.
-function isMissingPresentationError(err) {
-  if (err?.status !== 404) return false;
-  const code = err?.body?.code ?? null;
-  return !code || code === "unknown_presentation" || code === "presentation_not_found";
-}
-
-// Run a pane-relayed engine op; on `pane_suspended` (the server already waited
-// ~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.
-//
-// `fileName`/`brandId` identify the WINDOW so the wait can re-match it after a
-// presId churn (see waitForPaneReady). `retargetOnMissing` additionally treats a
-// vanished presId as recoverable — opt-in, because for most engine ops a 404 is
-// the search record talking, not the window: it re-lists the registry, re-matches
-// by presFP and retries ONCE on a short budget before the caller surfaces the
-// wake-PowerPoint blocker.
-async function engineOpWithPaneWait(
-  presId,
-  backendURL,
-  attempt,
-  {
-    fileName = null,
-    brandId = null,
-    otherPresIds = null,
-    retargetOnMissing = false,
-  } = {},
-) {
-  try {
-    return await attempt(presId, backendURL);
-  } catch (err) {
-    const suspended =
-      err?.code === "pane_suspended" || err?.code === "pane_timeout";
-    const churned = retargetOnMissing && isMissingPresentationError(err);
-    if (!suspended && !churned) throw err;
-    const live = await waitForPaneReady(presId, {
-      backendURL,
-      fileName,
-      brandId,
-      otherPresIds,
-      // A churned presId needs a re-list, not a user: the window is already
-      // there under a new id, so poll briefly instead of holding the full
-      // click-the-pane budget. A suspended pane keeps that budget.
-      timeoutMs: churned && !suspended ? envInt("SLIDEMIND_BRIDGE_PANE_RETARGET_TIMEOUT_MS", 15000) : null,
-      onWait: churned && !suspended ? paneRetargetNotice : paneWaitNotice,
-    });
-    if (!live) throw err;
-    return attempt(live.presId, live.backendURL ?? backendURL);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Pane-free engine routes (the DIRECT path)
-// ---------------------------------------------------------------------------
-//
-// Newer add-ins serve the whole engine surface off the CLI session:
-//   GET  /api/cli/engines                                  catalog (same path,
-//                                                          answered pane-free)
-//   POST /api/cli/searches                                 → { searchId, results }
-//   GET  /api/cli/searches/:id/results/:sel/image           stream
-//   GET  /api/cli/searches/:id/results/:sel/thumbnail       stream
-//   GET  /api/cli/searches/:id/results/:sel/slide           stream (one-slide .pptx)
-//   GET  /api/cli/searches/:id/results/:sel/source-presentation
-//
-// The searchId is SERVER-owned (per user, short TTL) rather than bound to a
-// window's pane, and a request carries only that searchId plus the selection
-// index — the server resolves the source config it stored at search time, so no
-// client ever names a file, site or drive.
-//
-// How a function picks its path: a `presId` means "relay through THAT window"
-// (the compat path old add-ins need and live insert always needs); NO presId
-// plus an explicit `backendURL`/`brandId` means "run this pane-free". Callers
-// resolve the backend once with resolveEngineBackend(), which returns null when
-// nothing paired advertises the routes — that null is the signal to fall back
-// to the pane relay, never a failure.
-
-function searchRoute(searchId, suffix = "") {
-  return `/api/cli/searches/${encodeURIComponent(String(searchId))}${suffix}`;
-}
-
-// A searchId is a number on the pane relay (the pane mints it per window) and an
-// opaque server-minted id on the direct routes — accept either, reject anything
-// else before a call goes near the network.
-function assertSearchId(fn, searchId) {
-  const ok =
-    (typeof searchId === "number" && Number.isFinite(searchId)) ||
-    (typeof searchId === "string" && searchId.trim().length > 0);
-  if (!ok) throw new Error(`${fn}: searchId is required`);
-}
-
-// A large asset legitimately takes longer than an engine op: the server is
-// fetching from SharePoint/blob AND piping. Separate budget so raising it
-// doesn't loosen every other bridge call.
-function downloadTimeoutMs() {
-  return (
-    parseInt(process.env.SLIDEMIND_BRIDGE_DOWNLOAD_TIMEOUT_MS || "600000", 10) ||
-    600000
-  );
-}
-
-function resultRoute(searchId, selection, leaf, params = null) {
-  const qs = params && [...params.keys()].length > 0 ? `?${params}` : "";
-  return `${searchRoute(searchId, `/results/${encodeURIComponent(String(selection))}/${leaf}`)}${qs}`;
-}
-
-// Per-process memo of which backend serves a brand's engine routes, so a
-// multi-environment session pays the brand probe at most once per design.
-const engineBackendForBrand = new Map();
-
-// A searchId is opaque (server-minted, hex) on the direct routes and numeric on
-// the pane relay. The distinction routes: an opaque id names a record on the
-// backend that minted it, and the pane can NEVER serve it — its handler only
-// understands its own per-window numeric ids.
-export function isOpaqueSearchId(searchId) {
-  return (
-    typeof searchId === "string" &&
-    searchId.trim() !== "" &&
-    !/^\d+$/.test(searchId.trim())
-  );
-}
-
-// Which paired backend minted this server-owned search record. Search records
-// are oid-scoped, so a foreign environment answers the same 404 as an expired
-// id — probing every engine-routes candidate with the record's own GET is both
-// exact and cheap (2h TTL, at most a couple of environments). Returns null when
-// no candidate holds it: expired, or minted by an environment no longer in
-// scope. Never falls back to the pane — see isOpaqueSearchId.
-//
-// One failure class is NOT routing information: a 401 means the session itself
-// is dead (revoked in the add-in's Connect CLI panel, or aged past its hard
-// lifetime). Swallowing it reports a revoked session as "that search expired",
-// and the user then re-runs a search that 401s the same way. So per-candidate
-// failures are collected and a session-invalid one is rethrown instead.
-export async function resolveSearchBackend(searchId) {
-  if (!isOpaqueSearchId(searchId)) return null;
-  const failures = [];
-  for (const s of sessionsInScope()) {
-    // A revoked session 401s the capability probe too, and that answer is
-    // indistinguishable from "old add-in" unless the failure is kept.
-    const probe = await backendCapabilitiesResult(s.backendURL);
-    if (probe.error && isSessionInvalidError(probe.error)) {
-      failures.push(probe.error);
-      continue;
-    }
-    if (probe.caps?.engineRoutes !== true) continue;
-    try {
-      await bridgeFetch(searchRoute(searchId), {}, s.backendURL);
-      return s.backendURL;
-    } catch (err) {
-      // 404 (not this environment's record / expired) or unreachable — try the
-      // next candidate; the distinction doesn't matter to routing.
-      failures.push(err);
-    }
-  }
-  // The two failures that are NOT the record talking: a dead session, and a
-  // missing Microsoft 365 sign-in (the record re-read is an engine route, so
-  // it refuses with the rest of corpus search). Reported as "that search
-  // expired", both send the user to re-run a search that fails the same way —
-  // so they outrank the expired-record answer.
-  const blocking = failures.find(
-    (e) => isSessionInvalidError(e) || e?.code === "login_required",
-  );
-  if (blocking) throw blocking;
-  return null;
-}
-
-// Which paired backend runs the pane-free engine routes for this call. An
-// explicit backendURL is honoured as-is (the caller already resolved a window or
-// a deck). Otherwise: every session in scope that advertises the routes is a
-// candidate — with ONE connected environment (the normal case) that IS the
-// answer, and no probe is worth paying for it. With several connected, the
-// DECK's bound design decides, never an open window's origin. presFP/brandId is
-// content-derived, so the SAME design onboarded in two environments carries the
-// SAME id — candidates are therefore probed FIRST, and only when none serves
-// the design does the caller fall back to the pane relay (the design lives on
-// an older add-in, and searching a different corpus would fold ITS slides into
-// this deck). Returns null for that fallback and when nothing paired serves the
-// routes at all.
-export async function resolveEngineBackend({ backendURL = null, brandId = null } = {}) {
-  if (backendURL) {
-    return (await backendSupportsEngineRoutes(backendURL)) ? backendURL : null;
-  }
-  const sessions = sessionsInScope();
-  const candidates = [];
-  for (const s of sessions) {
-    if (await backendSupportsEngineRoutes(s.backendURL)) candidates.push(s.backendURL);
-  }
-  if (candidates.length === 0) return null;
-  // Exactly one CONNECTED environment: there is nothing else the deck could
-  // belong to. Note the test is on the sessions, not on the candidates — during
-  // a rollout only one of several environments serves the routes, and taking it
-  // regardless would have searched the wrong corpus.
-  if (sessions.length === 1) return candidates[0];
-  if (brandId) {
-    // The memo only stands while that environment is still a candidate.
-    const memo = engineBackendForBrand.get(brandId);
-    if (memo) return candidates.includes(memo) ? memo : null;
-    // Candidates first: an environment that serves both the design AND the
-    // engine routes wins outright, even when an older environment also has the
-    // (content-identical) design.
-    for (const be of candidates) {
-      try {
-        await getDesignBundleForBrand(brandId, { backendURL: be });
-        engineBackendForBrand.set(brandId, be);
-        return be;
-      } catch {
-        // This candidate doesn't serve the design — try the next.
-      }
-    }
-    try {
-      const { backendURL: be } = await getDesignBundleForBrandAnyBackend(brandId);
-      engineBackendForBrand.set(brandId, be);
-      // Only a non-candidate can answer here: the design's environment is an
-      // older add-in with no engine routes. null sends the caller to that
-      // environment's pane relay instead of a different corpus.
-      return null;
-    } catch {
-      // No backend owns the design (unknown brand, old add-in) — fall through
-      // rather than guessing an environment.
-    }
-  }
-  if (candidates.length === 1) return candidates[0];
-  const err = new Error(
-    `Several connected environments run engine search (${candidates
-      .map((u) => deriveEnvLabel(u))
-      .join(", ")}). Scope the command with --backend <env>, point it at a ` +
-      "bound deck (--deck) so the deck's design picks one, or name an open " +
-      "window with --to <presId> to relay through it.",
-  );
-  err.code = "engine_backend_ambiguous";
-  throw err;
-}
-
-// Which connected environments answer the pane-free engine routes — the
-// "backend authoring ready" half of the readiness picture (`doctor`, `ready`),
-// reported as ENV LABELS so no URL can reach a printed line. Pass
-// connectionStatus()'s `backends` to skip environments that are already known
-// unreachable; without it every session in scope is probed.
-export async function engineReachability({ backends = null } = {}) {
-  const urls = Array.isArray(backends)
-    ? backends.filter((b) => b?.ok && b.backendURL).map((b) => b.backendURL)
-    : sessionsInScope().map((s) => s.backendURL);
-  const envs = [];
-  for (const url of urls) {
-    if (await backendSupportsEngineRoutes(url)) envs.push(deriveEnvLabel(url));
-  }
-  return { available: envs.length > 0, envs };
-}
-
-// Resolve + verify the backend for a direct engine call. Throws a typed
-// `engine_routes_unavailable` when the caller asked for the pane-free path on a
-// backend that doesn't serve it — a programming error by then, since callers go
-// through resolveEngineBackend first, but it must never surface as a bare 404.
-async function directEngineBackend(fn, { backendURL = null, brandId = null }) {
-  const be = backendURL ?? (await resolveEngineBackend({ brandId }));
-  if (be && (await backendSupportsEngineRoutes(be))) return be;
-  const err = new Error(
-    `${fn}: no connected slidemind add-in serves pane-free engine routes` +
-      `${be ? ` ('${deriveEnvLabel(be)}' is too old)` : ""}. ` +
-      "Open PowerPoint with the slidemind pane so the search can be relayed, or update the add-in.",
-  );
-  err.code = "engine_routes_unavailable";
-  throw err;
-}
-
-// The user's delegated tokens for a backend, or nulls. Attached ONLY to the
-// pane-free engine ops: they are the user's own Entra identity, and render,
-// bundle, whoami and the pane relay have no business carrying them (the pane
-// signs its own requests with a browser token that is strictly fresher).
-//
-// When nothing is stored, the sign-in RUNS HERE — browser opens, the command
-// blocks until the human finishes (graph-auth.ensureSignedIn, once per
-// process). So login is not a separate ritual: the first engine command of a
-// fresh machine walks the user through it, and every later one rides the
-// stored refresh token silently. Null only when the add-in doesn't honour the
-// tokens, or the sign-in was refused/abandoned — the backend then answers its
-// typed `login_required`, which the blocker below renders.
-async function engineGraphToken(backendURL) {
-  if (!backendURL) return null;
-  if (!(await backendSupportsGraphDelegated(backendURL))) return null;
-  let token = await getGraphToken(backendURL);
-  if (!token && (await ensureSignedIn(backendURL))) {
-    token = await getGraphToken(backendURL);
-  }
-  return token;
-}
-
-// The SharePoint-resource sibling (same sign-in, same refresh token): the
-// backend resolves `sg:` site-group membership from the PAIR, and on a
-// SharePoint-configured deployment refuses corpus search without it.
-async function engineSpToken(backendURL) {
-  if (!backendURL) return null;
-  if (!(await backendSupportsGraphDelegated(backendURL))) return null;
-  let token = await getSharePointToken(backendURL);
-  if (!token && (await ensureSignedIn(backendURL))) {
-    token = await getSharePointToken(backendURL);
-  }
-  return token;
-}
-
-// Both delegated tokens as body fields, for the POST routes. Empty when there
-// is nothing to attach, so an older backend sees the body it always did.
-async function delegatedBodyFields(backendURL) {
-  const [graphToken, spToken] = await Promise.all([
-    engineGraphToken(backendURL),
-    engineSpToken(backendURL),
-  ]);
-  return {
-    ...(graphToken ? { graphApiToken: graphToken } : {}),
-    ...(spToken ? { spApiToken: spToken } : {}),
-  };
-}
-
-// The byte routes are GETs, so the delegated tokens ride headers instead of
-// body fields. Empty (not absent-valued) when there is no token, so the request
-// headers are unchanged for everyone who never signed in.
-async function graphHeaders(backendURL) {
-  const [graphToken, spToken] = await Promise.all([
-    engineGraphToken(backendURL),
-    engineSpToken(backendURL),
-  ]);
-  return {
-    ...(graphToken ? { "x-slidemind-graph-token": graphToken } : {}),
-    ...(spToken ? { "x-slidemind-sp-token": spToken } : {}),
-  };
-}
-
-// Corpus search runs as the USER: the pane-free engine routes resolve the
-// caller's group membership live from the delegated tokens `slidemind login`
-// minted, and answer `401 { code: "login_required", action: "…" }` without
-// them. Shape it like the connection ladder's rungs — `{ code, actor, message }`
-// — so the CLI can print ONE actionable line and an agent knows it cannot clear
-// this one itself (the sign-in needs a browser and a human). Returns null for
-// any other error.
-export function loginRequiredBlocker(err) {
-  if (err?.code !== "login_required") return null;
-  const action =
-    typeof err?.body?.action === "string" && err.body.action.trim()
-      ? err.body.action.trim()
-      : "run `slidemind login` to sign in to Microsoft 365";
-  return {
-    code: "login_required",
-    actor: "user",
-    message:
-      `slidemind needs your Microsoft 365 sign-in before it can search the corpus — ${action}. ` +
-      "Everything else (render, bundle, imagery already downloaded) keeps working.",
-  };
-}
-
-
-// Brand-engine search through the local bridge. New add-ins run this
-// server-side with the relayed user token; older add-ins may fall back to a
-// task-pane proxy. Returns a searchId + numbered results (image thumbnails, or
-// slide results carrying per-slide text + metadata). `subtype`/`intent`/`top`
-// are passed through for slide engines (image engines ignore intent); omit them
-// and the server uses its defaults (back-compat with older add-ins).
-//
-// `engineId` may also be a SCOPE sentinel (`scope:all` / `scope:sharepoint`) —
-// an unfiltered search over the whole corpus rather than one engine's saved
-// folder filter. A scope has no subtype to derive its index from, so it needs an
-// explicit `resultType`; the add-in rejects a scope search without one.
-//
-// With NO presId and a resolved `backendURL`/`brandId` this runs pane-free
-// against `POST /api/cli/searches` (same body) and tags the answer with the
-// backend that owns the searchId.
-export async function engineSearch({
-  presId = null,
-  engineId,
-  query,
-  subtype = null,
-  resultType = null,
-  intent = null,
-  top = null,
-  backendURL = null,
-  brandId = null,
-  // When the chosen pane is suspended, wait CLIENT-side for THIS window to wake
-  // (the single-window default). engineSearchAnyPane sets this false for all but
-  // the last candidate so it can fail over to another live window instead.
-  waitOnSuspend = true,
-  timeoutMs = null,
-}) {
-  if (!engineId) throw new Error("engineSearch: engineId is required");
-  if (!query) throw new Error("engineSearch: query is required");
-  const direct = !presId && Boolean(backendURL || brandId);
-  if (!presId && !direct) throw new Error("engineSearch: presId is required");
-  const body = { engineId, query };
-  if (subtype) body.subtype = subtype;
-  // Additive: omitted unless set, so the body an older add-in sees is unchanged.
-  if (resultType) body.resultType = resultType;
-  if (intent) body.intent = intent;
-  if (typeof top === "number") body.top = top;
-  if (direct) {
-    const be = await directEngineBackend("engineSearch", { backendURL, brandId });
-    // The user's own identity: the backend resolves the caller's group
-    // membership from these tokens per request and refuses without them
-    // (login_required). Search also seeds the speculative insert cache
-    // server-side, which is why it carries the Graph token as well as the
-    // byte GETs.
-    const delegated = await delegatedBodyFields(be);
-    const res = await bridgeFetch(
-      "/api/cli/searches",
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ ...body, ...delegated }),
-        timeoutMs: timeoutMs ?? engineTimeoutMs(),
-      },
-      be,
-    );
-    const data = (await res.json()) ?? {};
-    // Tag the routing state (like the brand routes do) so every follow-up pick
-    // hits the backend that owns the searchId. `env` is the printable half —
-    // callers must never surface backendURL.
-    return { ...data, backendURL: be, env: deriveEnvLabel(be) };
-  }
-  const be = backendURL || (await resolveBackendForPres(presId));
-  const run = async (pid, b) => {
-    const res = await bridgeFetch(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/search`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
-        timeoutMs: timeoutMs ?? engineTimeoutMs(),
-      },
-      b,
-    );
-    return res.json(); // { ok, searchId, engineId, subtype, intent, resultCount, gridDataUri?, results }
-  };
-  return waitOnSuspend ? engineOpWithPaneWait(presId, be, run) : run(presId, be);
-}
-
-// A suspended/throttled background webview must not strand a window-AGNOSTIC
-// engine search: the catalog is per-user, so any connected pane can answer it.
-// Try the picked pane first, then every other connected pane on the same
-// backend (non-suspended first), failing fast past each unresponsive one; the
-// LAST candidate keeps the normal "click the pane to wake it" wait so a genuine
-// single-window/all-asleep case still surfaces the actionable prompt. Returns
-// the search result tagged with the presId/backendURL that actually answered —
-// the searchId is bound to THAT window, so callers must thread it into
-// follow-up view/insert/add-slide. An explicit presId pins the window (no
-// failover — the caller asked for that specific one).
-export async function engineSearchAnyPane({
-  registry,
-  explicitPresId = null,
-  engineId,
-  query,
-  subtype = null,
-  resultType = null,
-  intent = null,
-  top = null,
-}) {
-  const primary = pickAnyPresentationEntry(registry, explicitPresId);
-  const primaryBackend = primary.backendURL ?? null;
-  let candidates;
-  if (explicitPresId) {
-    candidates = [primary];
-  } else {
-    const others = (Array.isArray(registry) ? registry : [])
-      .filter(
-        (p) =>
-          p.presId !== primary.presId &&
-          p.connected !== false &&
-          (p.backendURL ?? null) === primaryBackend,
-      )
-      .sort((a, b) => (a.suspendedAt ? 1 : 0) - (b.suspendedAt ? 1 : 0));
-    candidates = [primary, ...others];
-  }
-  const failoverTimeout = envInt(
-    "SLIDEMIND_BRIDGE_ENGINE_FAILOVER_TIMEOUT_MS",
-    25000,
-  );
-  let lastErr = null;
-  for (let i = 0; i < candidates.length; i++) {
-    const cand = candidates[i];
-    const isLast = i === candidates.length - 1;
-    try {
-      const res = await engineSearch({
-        presId: cand.presId,
-        engineId,
-        query,
-        subtype,
-        resultType,
-        intent,
-        top,
-        backendURL: cand.backendURL ?? primaryBackend,
-        waitOnSuspend: isLast,
-        timeoutMs: isLast ? null : failoverTimeout,
-      });
-      return {
-        ...res,
-        presId: cand.presId,
-        backendURL: cand.backendURL ?? primaryBackend,
-      };
-    } catch (err) {
-      lastErr = err;
-      // A suspended/frozen/slow pane is recoverable by trying the next window;
-      // anything else (bad engineId, auth, 4xx) is real — surface it now.
-      const recoverable =
-        err?.code === "pane_suspended" ||
-        err?.code === "pane_timeout" ||
-        err?.code === "bridge_timeout" ||
-        err?.status === 503 ||
-        err?.status === 504;
-      if (isLast || !recoverable) throw err;
-    }
-  }
-  throw lastErr ?? new Error("engineSearchAnyPane: no candidate panes");
-}
-
-// Fetch a chosen engine result's bytes through the local bridge. For image
-// engines this returns SVG/PNG bytes (+ optional recoloured svgMarkup) WITHOUT
-// inserting onto a slide.
-//
-// Pane-only by design: the pane-free route table streams (see
-// engineDownloadToFile), and this base64-through-the-ack path only exists for
-// add-ins that predate streaming — which by definition predate the direct
-// routes too.
-export async function engineDownload({
-  presId,
-  searchId,
-  selection,
-  iconColor = null,
-  backendURL = null,
-}) {
-  if (!presId) throw new Error("engineDownload: presId is required");
-  assertSearchId("engineDownload", searchId);
-  if (typeof selection !== "number") {
-    throw new Error("engineDownload: selection (number) is required");
-  }
-  const be = backendURL || (await resolveBackendForPres(presId));
-  const body = { searchId, selection };
-  if (iconColor) body.iconColor = iconColor;
-  return engineOpWithPaneWait(presId, be, async (pid, b) => {
-    const res = await bridgeFetch(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/download`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
-        // Same relay path as engine/search — outlast the server's reconnect
-        // wait + pane ack timeout.
-        timeoutMs:
-          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
-          90000,
-      },
-      b,
-    );
-    return res.json(); // { ok, base64, mimeType, svgMarkup }
-  });
-}
-
-// Stream a chosen engine result's bytes to `destPath`. The size-unbounded
-// download: the pane's Socket.IO ack carries only a signed source reference, and
-// the add-in server fetches it and pipes the body here — so nothing buffers the
-// whole image and there is no base64 4/3 inflation. `engineDownload` above sends
-// the bytes through the pane ack instead and is therefore capped by the relay's
-// 10 MB frame limit; prefer this for anything that might be large.
-//
-// An SVG result comes back as JSON (`{ ok, mimeType, svgMarkup }`) rather than a
-// byte stream: it is kilobytes and its recolour happens pane-side. Callers get
-// `{ svgMarkup }` in that case and `{ bytesWritten, mimeType }` otherwise, so they
-// can persist whichever arrived.
-//
-// With NO presId and a resolved `backendURL`/`brandId` this streams pane-free
-// from `GET /api/cli/searches/:searchId/results/:selection/image` — same answer
-// shape, no window involved.
-export async function engineDownloadToFile({
-  presId = null,
-  searchId,
-  selection,
-  destPath,
-  iconColor = null,
-  backendURL = null,
-  brandId = null,
-  onProgress = null,
-}) {
-  const direct = !presId && Boolean(backendURL || brandId);
-  if (!presId && !direct) {
-    throw new Error("engineDownloadToFile: presId is required");
-  }
-  assertSearchId("engineDownloadToFile", searchId);
-  if (typeof selection !== "number") {
-    throw new Error("engineDownloadToFile: selection (number) is required");
-  }
-  if (!destPath) throw new Error("engineDownloadToFile: destPath is required");
-  // Both paths answer with the same two shapes (streamed bytes, or the inline
-  // SVG as JSON), so the response shaping is authored once.
-  const shape = (res) => {
-    if (!res.streamed) {
-      // The inline-SVG answer (kilobytes) arrives as JSON, not as a byte stream.
-      const parsed = res.body ? JSON.parse(res.body) : {};
-      return { ok: true, streamed: false, ...parsed };
-    }
-    const warningsHeader = res.headers?.["x-slidemind-warnings"];
-    let warnings;
-    if (warningsHeader) {
-      try {
-        warnings = JSON.parse(warningsHeader);
-      } catch {
-        // A malformed header must not fail a download that otherwise succeeded.
-      }
-    }
-    return {
-      ok: true,
-      streamed: true,
-      mimeType: String(res.headers?.["content-type"] ?? "") || null,
-      bytesWritten: res.bytesWritten,
-      ...(warnings ? { warnings } : {}),
-    };
-  };
-  if (direct) {
-    const b = await directEngineBackend("engineDownloadToFile", {
-      backendURL,
-      brandId,
-    });
-    // Only the recolour rides the query string — the RESOURCE is never
-    // client-supplied on this path; the server resolves it from searchId+selection.
-    const params = new URLSearchParams();
-    if (iconColor) params.set("iconColor", iconColor);
-    const res = await bridgeStreamToFile(
-      resultRoute(searchId, selection, "image", params),
-      {
-        method: "GET",
-        headers: await graphHeaders(b),
-        timeoutMs: downloadTimeoutMs(),
-        onProgress,
-      },
-      destPath,
-      b,
-    );
-    return shape(res);
-  }
-  const be = backendURL || (await resolveBackendForPres(presId));
-  const body = { searchId, selection };
-  if (iconColor) body.iconColor = iconColor;
-  return engineOpWithPaneWait(presId, be, async (pid, b) => {
-    const res = await bridgeStreamToFile(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/download-stream`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
-        timeoutMs: downloadTimeoutMs(),
-        onProgress,
-      },
-      destPath,
-      b,
-    );
-    return shape(res);
-  });
-}
-
-// Stream a chosen slide-search result to `destPath` as a native one-slide .pptx.
-// The size-unbounded sibling of `extractSlide`: the pane ack carries only the
-// request, and the add-in server performs it and pipes the (base64-decoded) bytes
-// here. `extractSlide` puts the whole slide through the pane's Socket.IO ack as
-// base64, so it is capped at ~7 MB of real bytes — which real reused slides reach.
-//
-// With NO presId and a resolved `backendURL`/`brandId` this streams pane-free
-// from `GET /api/cli/searches/:searchId/results/:selection/slide`.
-export async function extractSlideToFile({
-  presId = null,
-  searchId,
-  selection,
-  destPath,
-  backendURL = null,
-  brandId = null,
-  onProgress = null,
-}) {
-  const direct = !presId && Boolean(backendURL || brandId);
-  if (!presId && !direct) throw new Error("extractSlideToFile: presId is required");
-  assertSearchId("extractSlideToFile", searchId);
-  if (typeof selection !== "number") {
-    throw new Error("extractSlideToFile: selection (number) is required");
-  }
-  if (!destPath) throw new Error("extractSlideToFile: destPath is required");
-  const shape = (res) => {
-    const title = res.headers?.["x-slidemind-presentation-title"];
-    return {
-      ok: true,
-      bytesWritten: res.bytesWritten,
-      slideId: res.headers?.["x-slidemind-slide-id"] ?? undefined,
-      presentationTitle: title ? decodeURIComponent(String(title)) : undefined,
-    };
-  };
-  if (direct) {
-    const b = await directEngineBackend("extractSlideToFile", {
-      backendURL,
-      brandId,
-    });
-    const res = await bridgeStreamToFile(
-      resultRoute(searchId, selection, "slide"),
-      {
-        method: "GET",
-        headers: await graphHeaders(b),
-        timeoutMs: downloadTimeoutMs(),
-        onProgress,
-      },
-      destPath,
-      b,
-    );
-    return shape(res);
-  }
-  const be = backendURL || (await resolveBackendForPres(presId));
-  return engineOpWithPaneWait(presId, be, async (pid, b) => {
-    const res = await bridgeStreamToFile(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-extract-stream`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ searchId, selection }),
-        timeoutMs: downloadTimeoutMs(),
-        onProgress,
-      },
-      destPath,
-      b,
-    );
-    return shape(res);
-  });
-}
-
-// Extract a chosen slide-search result as a standalone one-slide .pptx (base64),
-// WITHOUT inserting it anywhere — the "fold into a deck" path. Relayed through
-// the pane like search/download, and pane-only for the same reason as
-// engineDownload: the pane-free route streams (extractSlideToFile above), and
-// this capped ack path exists only for add-ins that predate it.
-export async function extractSlide({
-  presId,
-  searchId,
-  selection,
-  backendURL = null,
-}) {
-  if (!presId) throw new Error("extractSlide: presId is required");
-  assertSearchId("extractSlide", searchId);
-  if (typeof selection !== "number") {
-    throw new Error("extractSlide: selection (number) is required");
-  }
-  const be = backendURL || (await resolveBackendForPres(presId));
-  return engineOpWithPaneWait(presId, be, async (pid, b) => {
-    const res = await bridgeFetch(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-extract`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ searchId, selection }),
-        timeoutMs:
-          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
-          90000,
-      },
-      b,
-    );
-    return res.json(); // { ok, base64, slideId?, presentationTitle? }
-  });
-}
-
-// Insert one or more chosen slide-search results live into the open
-// presentation (the "reuse → insert live" path). Relayed through the pane.
-//
-// `fileName`/`brandId` identify the target WINDOW (brandId == the deck's presFP).
-// They cost nothing on the happy path and are what lets the single retry find
-// the same window again after a pane reconnect churned its presId — the same
-// self-healing `push` does around its insert.
-export async function insertSlideLive({
-  presId,
-  searchId,
-  selections,
-  at = null,
-  backendURL = null,
-  fileName = null,
-  brandId = null,
-  otherPresIds = null,
-}) {
-  if (!presId) throw new Error("insertSlideLive: presId is required");
-  assertSearchId("insertSlideLive", searchId);
-  if (!Array.isArray(selections) || selections.length === 0) {
-    throw new Error("insertSlideLive: selections (number[]) is required");
-  }
-  const be = backendURL || (await resolveBackendForPres(presId));
-  // Live insert is a MUTATION, so it carries an operationId for the add-in's
-  // runMutationOnce dedup (the slide-insert handler keys an LRU on it). Generate
-  // it ONCE here, before engineOpWithPaneWait — the body is built once and
-  // reused across the wrapper's single pane_suspended retry, so the SAME id
-  // rides both attempts and a retry can never double-insert. Mirrors how
-  // buildAndPush makes one push operationId reused across attempts.
-  const operationId = `insert-${randomUUID()}`;
-  const body = { searchId, selections, operationId };
-  if (typeof at === "number") body.at = at;
-  return engineOpWithPaneWait(
-    presId,
-    be,
-    async (pid, b) => {
-      const res = await bridgeFetch(
-        `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-insert`,
-        {
-          method: "POST",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify(body),
-          timeoutMs:
-            parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
-            90000,
-        },
-        b,
-      );
-      // Tag the window the insert actually landed in: after a retarget it is no
-      // longer the presId the caller passed, and the caller reports it.
-      return { ...(await res.json()), presId: pid }; // { ok, insertedCount, insertedSlideIds, presId }
-    },
-    // A vanished presId is recoverable HERE (unlike the engine reads, whose
-    // 404s are about the search record): the insert never landed, so re-listing
-    // and retrying against the re-registered window is safe — and the same
-    // operationId rides along, so even an ambiguous first attempt can't
-    // double-insert.
-    { fileName, brandId, otherPresIds, retargetOnMissing: true },
-  );
-}
-
-// Reuse chosen slide-search results live when the search record is the
-// BACKEND's rather than a pane's.
-//
-// The pane's slide-insert handler resolves a selection out of the in-browser
-// search context IT minted (a numeric id); a searchId from the pane-free search
-// is server-owned and opaque, so relaying it would answer `searchId_required`.
-// The two legs `add-slide --search` + `push` already run therefore do the job in
-// the other order: extract each pick pane-free, then hand the BYTES to the
-// window's own insert route. Live insert stays pane-bound (Office.js is the only
-// thing that can type into an open deck) — only the searchId resolution moves.
-export async function insertSlidesFromSearch({
-  presId,
-  searchId,
-  selections,
-  at = null,
-  backendURL = null,
-  engineBackendURL = null,
-  fileName = null,
-  brandId = null,
-  otherPresIds = null,
-  onProgress = null,
-}) {
-  if (!presId) throw new Error("insertSlidesFromSearch: presId is required");
-  assertSearchId("insertSlidesFromSearch", searchId);
-  if (!Array.isArray(selections) || selections.length === 0) {
-    throw new Error("insertSlidesFromSearch: selections (number[]) is required");
-  }
-  const be = backendURL || (await resolveBackendForPres(presId));
-  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-reuse-"));
-  try {
-    let insertedCount = 0;
-    let livePresId = presId;
-    let liveBackendURL = be;
-    const insertedSlideIds = [];
-    for (const [i, selection] of selections.entries()) {
-      const slidePath = path.join(dir, `pick-${selection}.pptx`);
-      const extracted = await extractSlideToFile({
-        searchId,
-        selection,
-        destPath: slidePath,
-        backendURL: engineBackendURL,
-        brandId,
-        onProgress,
-      });
-      if (!extracted?.bytesWritten) {
-        throw new Error(`selection ${selection} produced no slide bytes`);
-      }
-      // One insert per pick, each with its own dedup key, so a retry inside
-      // engineOpWithPaneWait re-sends THAT pick and nothing else. `at` counts
-      // forward so the picks land in the order they were named.
-      const operationId = `insert-${randomUUID()}`;
-      const base64 = fs.readFileSync(slidePath).toString("base64");
-      const resp = await engineOpWithPaneWait(
-        livePresId,
-        liveBackendURL,
-        async (pid, b) => {
-          const ack = await insertSlides({
-            presId: pid,
-            base64,
-            insertAt: typeof at === "number" ? at + i : null,
-            sourceSlideIds: extracted.slideId ? [extracted.slideId] : null,
-            operationId,
-            backendURL: b,
-          });
-          return { ...ack, presId: pid, backendURL: b };
-        },
-        { fileName, brandId, otherPresIds, retargetOnMissing: true },
-      );
-      // A retarget moves every remaining pick to the window that answered, so
-      // a multi-pick reuse cannot end up split across two presentations.
-      livePresId = resp.presId ?? livePresId;
-      liveBackendURL = resp.backendURL ?? liveBackendURL;
-      const landed = Array.isArray(resp.insertedSlideIds)
-        ? resp.insertedSlideIds
-        : [];
-      insertedCount += landed.length || 1;
-      insertedSlideIds.push(...landed);
-      bestEffortRm(slidePath);
-    }
-    return { ok: true, insertedCount, insertedSlideIds, presId: livePresId };
-  } finally {
-    bestEffortRm(dir);
-  }
-}
-
-// Remove a temp file/dir that bytes were JUST streamed into. Windows may still
-// hold a handle on it at cleanup time (antivirus scanning the fresh write), so
-// plain rmSync races into EBUSY/ENOTEMPTY there — retry, and swallow what's
-// left: cleanup failure must never mask an operation that succeeded.
-function bestEffortRm(p) {
-  try {
-    fs.rmSync(p, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 });
-  } catch {}
-}
-
-// Fetch a chosen slide-search result's thumbnail/preview as a data URI for
-// on-demand viewing (the agent doesn't have to extract the whole .pptx just to
-// look at a slide). Relayed through the pane.
-//
-// With NO presId and a resolved `backendURL`/`brandId` this reads the pane-free
-// `GET …/results/:selection/thumbnail`, which STREAMS: a thumbnail is small, so
-// it is buffered back into the same `{ dataUri }` contract rather than forcing
-// every caller to grow a file path.
-export async function viewSlide({
-  presId = null,
-  searchId,
-  selection,
-  backendURL = null,
-  brandId = null,
-}) {
-  const direct = !presId && Boolean(backendURL || brandId);
-  if (!presId && !direct) throw new Error("viewSlide: presId is required");
-  assertSearchId("viewSlide", searchId);
-  if (typeof selection !== "number") {
-    throw new Error("viewSlide: selection (number) is required");
-  }
-  if (direct) {
-    const b = await directEngineBackend("viewSlide", { backendURL, brandId });
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "slidemind-thumb-"));
-    const tmp = path.join(dir, "thumbnail.bin");
-    try {
-      const res = await bridgeStreamToFile(
-        resultRoute(searchId, selection, "thumbnail"),
-        {
-          method: "GET",
-          headers: await graphHeaders(b),
-          timeoutMs: engineTimeoutMs(),
-        },
-        tmp,
-        b,
-      );
-      if (!res.streamed) {
-        // An add-in that answers with an inline preview passes straight through.
-        return res.body ? JSON.parse(res.body) : { ok: false };
-      }
-      const mimeType =
-        String(res.headers?.["content-type"] ?? "").split(";")[0].trim() ||
-        "image/png";
-      return {
-        ok: true,
-        mimeType,
-        dataUri: `data:${mimeType};base64,${fs.readFileSync(tmp).toString("base64")}`,
-      };
-    } finally {
-      bestEffortRm(dir);
-    }
-  }
-  const be = backendURL || (await resolveBackendForPres(presId));
-  return engineOpWithPaneWait(presId, be, async (pid, b) => {
-    const res = await bridgeFetch(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/engine/slide-view`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ searchId, selection }),
-        timeoutMs:
-          parseInt(process.env.SLIDEMIND_BRIDGE_ENGINE_TIMEOUT_MS || "90000", 10) ||
-          90000,
-      },
-      b,
-    );
-    return res.json(); // { ok, dataUri, mimeType }
-  });
-}
-
-// Read the ORIGINAL deck a chosen slide-search result came from — NOT the open
-// window (that is getPresentationContent below). Answers "what else is in the
-// presentation this slide belongs to?": the surrounding narrative, the slides
-// either side, the argument the source deck was making.
-//
-// The add-in reads it out of the slide index rather than downloading the source
-// file, so this is fast and works the same for blob- and SharePoint-backed
-// results — but the text is the last SYNCED extraction, not the live file. The
-// response is Markdown, and the pane never carries it: the relay route resolves
-// the selection through the pane and performs the backend read itself.
-//
-// searchId is presentation-scoped on the pane path, so that path relays through
-// the window the search ran on, like viewSlide. Idempotent, so the
-// pane_suspended retry is safe. With NO presId and a resolved
-// `backendURL`/`brandId` it reads the pane-free
-// `GET …/results/:selection/source-presentation` instead (the searchId is
-// server-owned there, so no window is involved at all).
-export async function readSourcePresentation({
-  presId = null,
-  searchId,
-  selection,
-  fromSlide = null,
-  toSlide = null,
-  backendURL = null,
-  brandId = null,
-}) {
-  const direct = !presId && Boolean(backendURL || brandId);
-  if (!presId && !direct) {
-    throw new Error("readSourcePresentation: presId is required");
-  }
-  assertSearchId("readSourcePresentation", searchId);
-  if (typeof selection !== "number") {
-    throw new Error("readSourcePresentation: selection (number) is required");
-  }
-  // Both paths answer with Markdown plus the counts/truncation in headers.
-  const shape = async (res) => ({
-    ok: true,
-    markdown: await res.text(),
-    truncated: res.headers?.["x-slidemind-truncated"] === "1",
-    slideCount: Number(res.headers?.["x-slidemind-slide-count"] ?? 0) || 0,
-    totalSlideCount:
-      Number(res.headers?.["x-slidemind-total-slide-count"] ?? 0) || 0,
-    presentationTitle: res.headers?.["x-slidemind-presentation-title"]
-      ? decodeURIComponent(String(res.headers["x-slidemind-presentation-title"]))
-      : undefined,
-  });
-  if (direct) {
-    // The direct route table carries source-presentation, so engineRoutes is the
-    // capability that gates it here (sourcePresentation gates the pane route).
-    const b = await directEngineBackend("readSourcePresentation", {
-      backendURL,
-      brandId,
-    });
-    const params = new URLSearchParams();
-    if (typeof fromSlide === "number") params.set("fromSlide", String(fromSlide));
-    if (typeof toSlide === "number") params.set("toSlide", String(toSlide));
-    const res = await bridgeFetch(
-      resultRoute(searchId, selection, "source-presentation", params),
-      {
-        method: "GET",
-        headers: { accept: "text/markdown, text/plain" },
-        timeoutMs: engineTimeoutMs(),
-      },
-      b,
-    );
-    return shape(res);
-  }
-  const be = backendURL || (await resolveBackendForPres(presId));
-  if (!(await backendSupportsSourcePresentation(be))) {
-    const err = new Error(
-      "This slidemind add-in cannot read a result's source presentation yet. Update the add-in, then try again.",
-    );
-    err.code = "source_presentation_unsupported";
-    throw err;
-  }
-  const body = { searchId, selection };
-  if (typeof fromSlide === "number") body.fromSlide = fromSlide;
-  if (typeof toSlide === "number") body.toSlide = toSlide;
-  return engineOpWithPaneWait(presId, be, async (pid, b) => {
-    const res = await bridgeFetch(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/source-presentation`,
-      {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          accept: "text/markdown, text/plain",
-        },
-        body: JSON.stringify(body),
-        timeoutMs: engineTimeoutMs(),
-      },
-      b,
-    );
-    return shape(res);
-  });
-}
-
-// Read the CURRENT content of an open presentation (the "pull content" path
-// 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,
-// so we resolve the origin backend from the presId and relay through that
-// window's pane. It's an idempotent read, so engineOpWithPaneWait's single
-// pane_suspended client-wait + retry against the live entry is safe (like viewSlide).
-export async function getPresentationContent({
-  presId,
-  mode = "raw",
-  backendURL = null,
-}) {
-  if (!presId) throw new Error("getPresentationContent: presId is required");
-  const be = backendURL || (await resolveBackendForPres(presId));
-  const body = { mode: mode === "summary" ? "summary" : "raw" };
-  return engineOpWithPaneWait(presId, be, async (pid, b) => {
-    const res = await bridgeFetch(
-      `/api/cli/presentations/${encodeURIComponent(pid)}/content`,
-      {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify(body),
-        timeoutMs: engineTimeoutMs(),
-      },
-      b,
-    );
-    return res.json(); // { ok, mode, slideCount, slides }
-  });
-}
-
-// Ask the pane whether its host document is actually still alive (the
-// `ping-document` op — one PowerPoint.run in the webview). This exists for
-// `ready`'s zombie check: a webview whose document was closed keeps its socket
-// (and thus its registry lease) alive, so only a host round-trip tells the
-// truth. Deliberately NOT engineOpWithPaneWait — a probe must fail fast, never
-// park in the 120s pane wait. Callers decide what a failure means; this just
-// returns the ack or throws the transport error.
-export async function pingPresentation({ presId, backendURL, timeoutMs = 12000 }) {
-  if (!presId) throw new Error("pingPresentation: presId is required");
-  const res = await bridgeFetch(
-    `/api/cli/presentations/${encodeURIComponent(presId)}/ping`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({}),
-      timeoutMs,
-    },
-    backendURL,
-  );
-  return res.json(); // { ok, presId?, fileName? } | { ok: false, code, error }
-}
-
-function ensurePaneAckOk(data, operation) {
-  if (!data || data.ok !== false) return data ?? {};
-  const detail = data.error || `${operation} failed`;
-  const err = new Error(detail);
-  err.code = data.code || `${operation}_failed`;
-  err.body = data;
-  throw err;
-}
-
-export async function insertSlides({
-  presId,
-  base64,
-  insertAt = null,
-  sourceSlideIds = null,
-  operationId = null,
-  sourceTagsBySlide = null,
-  backendURL = null,
-}) {
-  if (!presId) throw new Error("insertSlides: presId is required");
-  if (!base64) throw new Error("insertSlides: base64 is required");
-  const be = backendURL || (await resolveBackendForPres(presId));
-  const body = { base64, insertAt, sourceSlideIds, operationId };
-  // Deck-embedded source payloads for the pane's post-insert tag write,
-  // aligned with the inserted slides in document order.
-  if (Array.isArray(sourceTagsBySlide) && sourceTagsBySlide.some(Boolean)) {
-    body.sourceTagsBySlide = sourceTagsBySlide;
-  }
-  const res = await bridgeFetch(
-    `/api/cli/presentations/${encodeURIComponent(presId)}/insert`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
-      timeoutMs:
-        parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
-        1805000,
-    },
-    be,
-  );
-  return ensurePaneAckOk(await res.json().catch(() => ({})), "insert");
-}
-
-// Read-only sibling of the mutation ops: export the LIVE slides carrying the
-// given GUIDs, so a `--replace` push can see what the user changed on screen
-// BEFORE it wipes it (plan Phase C1). `guids` omitted ⇒ the whole deck.
-//
-// The ack's `tags` come from the Office.js tag API, NOT from the exported
-// bytes: exportAsBase64 strips custom tags (office-js #6104), so a slide's
-// drift BASELINE is recoverable only from `tags` — never from `base64`, which
-// carries the CURRENT state and nothing else. `deck.unmatched` lists the live
-// slides that are not in the requested set (what a whole-deck replace would
-// delete); `truncated` names GUIDs that matched but did not fit the relay
-// frame, to be re-requested.
-export async function exportSlides({
-  presId,
-  guids = null,
-  presentationId = null,
-  backendURL = null,
-}) {
-  if (!presId) throw new Error("exportSlides: presId is required");
-  const be = backendURL || (await resolveBackendForPres(presId));
-  const body = {};
-  if (Array.isArray(guids) && guids.length > 0) body.guids = guids;
-  if (presentationId) body.presentationId = presentationId;
-  const res = await bridgeFetch(
-    `/api/cli/presentations/${encodeURIComponent(presId)}/export-slides`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(body),
-      // Same pane round trip as the mutations (a suspended pane has to wake),
-      // and the payload is slide bytes.
-      timeoutMs:
-        parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
-        1805000,
-    },
-    be,
-  );
-  return ensurePaneAckOk(await res.json().catch(() => ({})), "export-slides");
-}
-
-export async function replaceSlides({
-  presId,
-  base64,
-  operationId = null,
-  sourceTagsBySlide = null,
-  backendURL = null,
-}) {
-  if (!presId) throw new Error("replaceSlides: presId is required");
-  if (!base64) throw new Error("replaceSlides: base64 is required");
-  const be = backendURL || (await resolveBackendForPres(presId));
-  const replaceBody = { base64, operationId };
-  if (Array.isArray(sourceTagsBySlide) && sourceTagsBySlide.some(Boolean)) {
-    replaceBody.sourceTagsBySlide = sourceTagsBySlide;
-  }
-  const res = await bridgeFetch(
-    `/api/cli/presentations/${encodeURIComponent(presId)}/replace`,
-    {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify(replaceBody),
-      timeoutMs:
-        parseInt(process.env.SLIDEMIND_BRIDGE_MUTATION_TIMEOUT_MS || "1805000", 10) ||
-        1805000,
-    },
-    be,
-  );
-  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) };
-  }
-
-  // A live pane outranks a suspended one for the DESIGN decision: a
-  // backgrounded — or closed and not yet purged — window must not turn the one
-  // design the user actually has in front of them into a question. Only when
-  // nothing is live do the suspended windows decide.
-  const live = all.filter(isPaneReadyPresentation);
-  const pool = live.length > 0 ? live : all;
-  const distinctDesigns = new Set(pool.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(pool, deckPresFP) ??
-      pool.find(isPaneReadyPresentation) ??
-      pool[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(pool) };
-}
-
-// 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
-// the choice is ambiguous. Callers that already hold the entry can pass its
-// `backendURL` straight to the targeted ops, skipping a second fan-out.
-// `preferBrandId` (the deck's bundle-ref presFP) tie-breaks a presId open on
-// several backends — see tieBreakMatches.
-export function pickPresentationEntry(
-  registry,
-  explicitPresId,
-  { preferBrandId = null } = {},
-) {
-  if (explicitPresId) {
-    const matches = registry.filter((p) => p.presId === explicitPresId);
-    if (matches.length === 0) {
-      const ids = registry.map((p) => p.presId).join(", ") || "(none registered)";
-      throw new Error(
-        `No open PowerPoint window registered with presId='${explicitPresId}'. Live: ${ids}`,
-      );
-    }
-    if (matches.length > 1) {
-      const winner = tieBreakMatches(matches, preferBrandId);
-      if (winner) return winner;
-      const envs = matches.map((m) => m.env || "?").join(", ");
-      throw new Error(
-        `Presentation '${explicitPresId}' is open on multiple environments: ${envs}, ` +
-          "and no single connected one has the deck's corporate design active. " +
-          "Disambiguate with --backend <env|label> (or SLIDEMIND_BACKEND).",
-      );
-    }
-    return matches[0];
-  }
-  if (registry.length === 0) {
-    throw new Error(
-      "No PowerPoint windows registered with the slidemind add-in. " +
-        "Open a presentation, ensure the add-in is loaded, and try again.",
-    );
-  }
-  if (registry.length === 1) return registry[0];
-  // ONE window mirrored across several paired backends is not a user choice —
-  // apply the same tie-break as the explicit-presId path. Several DIFFERENT
-  // windows stay a user decision.
-  if (new Set(registry.map((p) => p.presId)).size === 1) {
-    const winner = tieBreakMatches(registry, preferBrandId);
-    if (winner) return winner;
-  }
-  const list = registry
-    .map(
-      (p) =>
-        `  ${p.presId}\t${p.env && isMultiEnv() ? `[${p.env}]\t` : ""}${p.title || p.fileName || "(untitled)"}` +
-        (p.connected === false || p.suspendedAt ? "\t(suspended — PowerPoint in background)" : ""),
-    )
-    .join("\n");
-  throw new Error(
-    `Multiple PowerPoint windows are open. Pick one with --to <presId>:\n${list}\n${READY_HINT_PICK}`,
-  );
-}
-
-// Window-AGNOSTIC picker for engine ops (discovery / search / result view). The
-// engine catalog is per-user and NOT bound to any window, so any connected pane
-// can run the search — there is nothing for the caller to disambiguate. When no
-// explicit presId is given we attach to one automatically (preferring a live,
-// non-suspended pane so we don't have to wake a backgrounded one) instead of
-// throwing the "multiple windows, pick --to" error pickPresentationEntry raises.
-// An explicit presId still resolves exactly as pickPresentationEntry.
-//
-// CAVEAT: the searchId the add-in returns is bound to the pane that ran the
-// search (each window keeps its own search-context store). So follow-up
-// view/extract/insert must target the SAME entry this returns — surface its
-// presId to the caller so it can thread it back.
-export function pickAnyPresentationEntry(registry, explicitPresId, opts = {}) {
-  if (explicitPresId) return pickPresentationEntry(registry, explicitPresId, opts);
-  if (!Array.isArray(registry) || registry.length === 0) {
-    throw new Error(
-      "No PowerPoint windows registered with the slidemind add-in. " +
-        "Open a presentation, ensure the add-in is loaded, and try again.",
-    );
-  }
-  return (
-    registry.find(isPaneReadyPresentation) ??
-    registry.find((p) => p.connected !== false && !p.suspendedAt) ??
-    registry[0]
-  );
-}
-
-// Back-compat shim: returns just the presId string. Prefer
-// pickPresentationEntry when you need the origin backend.
-export function pickPresentation(registry, explicitPresId) {
-  return pickPresentationEntry(registry, explicitPresId).presId;
-}
+// This file is the public surface; the implementation lives in ./client/*.mjs
+// (split by job). Import from here — the submodules are an internal layout.
+
+export {
+  getDesignBundle,
+  getDesignBundleForBrand,
+  getDesignBundleForBrandAnyBackend,
+  listBrands,
+  generateConceptImagesForBrand,
+  resolveConceptBackend,
+  generateImageForBrand,
+  backendSupportsConvertPptx,
+  convertPptxForBrand,
+  listEngines,
+} from "./client/brands.mjs";
+export {
+  isOpaqueSearchId,
+  resolveSearchBackend,
+  resolveEngineBackend,
+  engineReachability,
+  loginRequiredBlocker,
+} from "./client/engine-routing.mjs";
+export {
+  engineSearch,
+  engineSearchAnyPane,
+  engineDownload,
+  engineDownloadToFile,
+} from "./client/engine-search.mjs";
+export {
+  extractSlideToFile,
+  extractSlide,
+  insertSlideLive,
+  insertSlidesFromSearch,
+  viewSlide,
+  readSourcePresentation,
+} from "./client/engine-slides.mjs";
+export {
+  pingPresentation,
+  insertSlides,
+  exportSlides,
+  replaceSlides,
+  resolveDesignSource,
+  pickPresentationEntry,
+  pickAnyPresentationEntry,
+  pickPresentation,
+} from "./client/pane-ops.mjs";
+export {
+  connectionStatus,
+  listOpenPresentations,
+  toPublicPresentation,
+  listOpenPresentationsDetailed,
+  requireHost,
+  isRenderReadyPresentation,
+  isPaneReadyPresentation,
+  listReadyPresentationsWithWait,
+  requireRenderHost,
+  requirePaneHost,
+  paneReadyPresentations,
+  resolveBackendForPres,
+  waitForPaneReady,
+  getPresentationContent,
+} from "./client/presentations.mjs";
+export {
+  renderPptx,
+  translateDeck,
+} from "./client/render.mjs";
+export {
+  cliVersion,
+  compareCliVersions,
+  setDiagnosticMode,
+  isSessionInvalidError,
+  backendSupportsBrandRoutes,
+  backendSupportsConceptImages,
+  backendSupportsImageGeneration,
+  backendSupportsBrandsList,
+  backendSupportsSourcePresentation,
+  backendSupportsEngineRoutes,
+  backendSupportsGraphDelegated,
+  assertCliVersionSupported,
+} from "./client/transport.mjs";