slidemind 0.3.13 → 0.3.14

package/src/cli/ready.mjs

@@ -0,0 +1,805 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { envTag } from "../bridge/config.mjs";
+import { fail, resolveDeckArg, loadBridgeModule, SRC_DIR } from "./common.mjs";
+import { publicConnectionStatus, backendBlocker, connectionBlocker } from "./connection.mjs";
+import { readDesignName, cachedDesigns, designRows, designsHumanLines, windowsHumanLine } from "./designs.mjs";
+import { runDiagnose } from "./diagnose.mjs";
+import { deckStage, stageHumanLines } from "./status.mjs";
+
+// The one-command agent preflight. Collapses the old 4-call session start
+// (list windows → pick → download-bundle → download-bundle-to-bind) into a
+// single verb: check pairing/reachability/CLI-version/windows, resolve the OPEN
+// design (the add-in is the source of truth), materialize its bundle, bind the
+// deck, and print exactly one actionable blocker when it can't. Exit 0 iff
+// ready; every blocker → exit 1 with a machine-copeable code. Never prints a
+// backendURL (env label only).
+export async function cmdReady(rest) {
+  // --- Local arg parse: unknown flags fail BEFORE any network (cli-dispatch
+  // convention). ---
+  let to = null;
+  let asJson = false;
+  let force = false;
+  let connectOnly = false;
+  let diagnose = false;
+  let brand = null;
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--to") {
+      to = rest[++i];
+      if (!to) fail("--to expects a presId");
+    } else if (a === "--json") {
+      asJson = true;
+    } else if (a === "--force") {
+      force = true;
+    } else if (a === "--connect-only") {
+      connectOnly = true;
+    } else if (a === "--diagnose") {
+      diagnose = true;
+    } else if (a === "--brand") {
+      brand = rest[++i];
+      if (!brand) fail("--brand expects a design id (presFP)");
+    } else if (a.startsWith("-")) {
+      fail(`unknown flag: ${a}`);
+    } else {
+      positional.push(a);
+    }
+  }
+  if (brand && to) {
+    fail("--brand and --to are mutually exclusive (a design id or a window, not both)");
+  }
+
+  // --diagnose: the read-only report — both ladders, every paired backend, the
+  // Microsoft 365 state and every registered window with its pane state. It
+  // resolves no design, materializes nothing and binds nothing, which is why it
+  // is a mode of `ready` rather than the separate `doctor` + `presentations`
+  // commands it replaced.
+  if (diagnose) {
+    await runDiagnose(rest);
+    return;
+  }
+
+  // --- Local: resolve the deck dir (never create it) and read its existing
+  // bundle ref. deckPresFP feeds ONLY the mirror tie-break + `suggested`; it
+  // never auto-picks a design. ---
+  const deckArg = positional[0] ?? null;
+  const bundle = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
+  );
+  let deckDir = null;
+  let deckSlug = null;
+  let deckPresFP = null;
+  if (deckArg) {
+    deckDir = resolveDeckArg(deckArg);
+    if (!fs.existsSync(deckDir)) {
+      fail(
+        `deck '${deckArg}' not found — run \`slidemind ready\` (no deck) to set up, then \`slidemind new ${deckArg}\``,
+      );
+    }
+    deckSlug = path.basename(deckDir);
+    deckPresFP = bundle.readDeckBundleRef(deckDir)?.presFP ?? null;
+  }
+
+  // Emit a structured blocker (JSON to stdout / human to stderr) and exit 1.
+  // `humanLines` overrides the default `slidemind: <message>` for the richer
+  // ambiguous / unknown-window shapes. Mirrors the diagnostic's stream conventions:
+  // machine JSON on stdout, human prose on stderr.
+  const finishBlocker = ({ blocker, extras = {}, humanLines = null }) => {
+    if (asJson) {
+      process.stdout.write(
+        JSON.stringify(
+          { ready: false, blocker, nextAction: blocker.message, ...extras },
+          null,
+          2,
+        ) + "\n",
+      );
+      process.exit(1);
+    }
+    if (humanLines) {
+      process.stderr.write(
+        humanLines.endsWith("\n") ? humanLines : `${humanLines}\n`,
+      );
+      process.exit(1);
+    }
+    fail(blocker.message);
+  };
+
+  // --- First use: there is nothing this process can do on its own. Connecting
+  // starts in the add-in because the claim it mints carries the deployment's
+  // address, and an unconnected CLI has no way to learn which backend its user
+  // belongs to. So name the one action that works and stop. ---
+  const cfg = await loadBridgeModule("config");
+  if (cfg.readSessions().length === 0) {
+    finishBlocker({
+      blocker: {
+        code: "not_connected",
+        actor: "user",
+        message:
+          "Connect this CLI first: in PowerPoint open slidemind → Settings → General → Connect CLI, press the link button, copy the command it shows, and run it here.",
+      },
+    });
+    return;
+  }
+
+  const client = await import(
+    pathToFileURL(path.join(SRC_DIR, "bridge", "client.mjs")).href
+  );
+  // Same opt-out as `--diagnose`: `ready` OWNS the cli_update_required blocker (it is
+  // terminal, `actor: "agent"`, with the update command as its nextAction), so
+  // the raw header throw would only replace a structured answer with a worse one.
+  client.setDiagnosticMode(true);
+
+  // --- Network (one parallel round): readiness ladder + the merged registry. ---
+  const [statusRaw, detailed] = await Promise.all([
+    client.connectionStatus(),
+    client.listOpenPresentationsDetailed(),
+  ]);
+  const pub = publicConnectionStatus(statusRaw, client);
+  let registry = detailed.presentations;
+
+  // Terminal blockers: waiting can't fix an unreachable backend or a stale CLI.
+  const terminal = connectionBlocker(pub);
+  if (
+    terminal &&
+    (terminal.code === "all_unreachable" || terminal.code === "cli_update_required")
+  ) {
+    finishBlocker({ blocker: terminal });
+    return;
+  }
+
+  // --- Backend authoring readiness beyond the connection itself: which
+  // environments serve the pane-free engine routes. Probed at most once (and
+  // only when a payload actually reports it), and never fatal — an add-in
+  // without them still authors, it just relays search through a window. ---
+  let engineInfo = null;
+  const engines = async () => {
+    if (!engineInfo) {
+      try {
+        engineInfo = await client.engineReachability({
+          backends: statusRaw.backends,
+        });
+      } catch {
+        engineInfo = { available: false, envs: [] };
+      }
+    }
+    return engineInfo;
+  };
+
+  // Microsoft 365 sign-in, surfaced HERE because ready is the agent's
+  // session-start preflight and browser SSO is the one step an agent cannot do
+  // itself — it has to ask its human, and this is where it learns to. Reported
+  // only when a backend advertises graphDelegated (older backends have no
+  // window-free SharePoint path, so there is nothing to sign in FOR).
+  // On a cliLoginV1 backend the sign-in is REQUIRED for the whole pane-free
+  // engine surface (catalog, search, downloads, extraction answer 401
+  // login_required without it) — so the degradation says that plainly and up
+  // front, before the agent's first search meets the 401. Render and bundle
+  // still never need it. null = no backend advertises it.
+  let m365Info;
+  const m365 = async () => {
+    if (m365Info !== undefined) return m365Info;
+    const advertising = (statusRaw.backends ?? []).filter(
+      (b) => b.ok && b.capabilities?.graphDelegated === true && b.backendURL,
+    );
+    if (advertising.length === 0) {
+      m365Info = null;
+      return m365Info;
+    }
+    const graph = await loadBridgeModule("graph-auth");
+    const signedOut = advertising.filter(
+      (b) => !graph.hasGraphSession(b.backendURL),
+    );
+    const signedOutEnvs = signedOut.map((b) => cfg.deriveEnvLabel(b.backendURL));
+    m365Info =
+      signedOut.length === 0
+        ? { signedIn: true, degradation: null, line: "Microsoft 365: signed in" }
+        : {
+            signedIn: false,
+            degradation: {
+              code: "login_required",
+              actor: "user",
+              envs: signedOutEnvs,
+              message:
+                "Microsoft 365: not signed in — engine search, downloads and slide " +
+                "extraction run as the USER. The first engine command opens a browser " +
+                "sign-in AUTOMATICALLY and waits; tell the user to complete it there " +
+                "(you cannot). Render, build and bundle work without it.",
+            },
+            line:
+              `Microsoft 365: not signed in${envTag(signedOutEnvs.join(", "))} — the next engine ` +
+              "command opens a browser sign-in for the user to complete (automatic; " +
+              "`slidemind login` also works any time).",
+          };
+    return m365Info;
+  };
+
+  const isRR = client.isRenderReadyPresentation;
+
+  // The render-ready windows as the payloads report them — after the zombie
+  // prune below, so a listed window is one PowerPoint actually has. One row
+  // per window: a presId mirrored across backends is still one window.
+  const publicWindows = () => {
+    const seen = new Set();
+    return registry.filter(isRR).filter((p) => !seen.has(p.presId) && seen.add(p.presId)).map((p) => {
+      const q = client.toPublicPresentation(p);
+      return {
+        presId: q.presId,
+        env: q.env ?? null,
+        title: q.title ?? null,
+        fileName: q.fileName ?? null,
+        presFP: p.brandId ?? null,
+        paneReady: client.isPaneReadyPresentation(p),
+      };
+    });
+  };
+
+  // The design menu: every design at hand — cached here, open in a verified
+  // window, or (when asked) listed by the backend — one row per presFP with
+  // name, theme colours and the windows on it. Success payloads and the
+  // ambiguous blocker report the same shape, so the agent always has the
+  // menu to put to the user.
+  const designMenu = async ({ current = null, withBackend = false } = {}) => {
+    const blank = (presFP) => ({
+      presFP,
+      name: null,
+      colors: null,
+      current: presFP === current,
+      cached: false,
+      windows: [],
+    });
+    const rows = new Map(
+      cachedDesigns(bundle, current).map((d) => [
+        d.presFP,
+        { ...d, cached: true, windows: [] },
+      ]),
+    );
+    for (const w of publicWindows()) {
+      if (!w.presFP) continue;
+      if (!rows.has(w.presFP)) rows.set(w.presFP, blank(w.presFP));
+      rows.get(w.presFP).windows.push(w);
+    }
+    if (withBackend) {
+      try {
+        for (const b of await client.listBrands()) {
+          if (!rows.has(b.presFP)) rows.set(b.presFP, blank(b.presFP));
+          rows.get(b.presFP).name ??= b.name ?? null;
+        }
+      } catch {
+        /* no brand list — the menu is what this machine knows */
+      }
+    }
+    return [...rows.values()];
+  };
+
+  // The one question ready cannot answer: several designs at hand and neither
+  // a deck binding, a --brand, nor a single verified window says which.
+  const finishAmbiguous = async () => {
+    const designs = await designMenu({ withBackend: true });
+    const suggested =
+      deckPresFP && designs.some((d) => d.presFP === deckPresFP) ? deckPresFP : null;
+    const rerun = `slidemind ready${deckSlug ? ` ${deckSlug}` : ""} --brand <presFP>`;
+    const blocker = {
+      code: "ambiguous_design",
+      actor: "user",
+      message: `Several corporate designs are at hand and nothing says which — ask the user which to build against (by name and colours), then re-run: ${rerun}.`,
+    };
+    let human =
+      "slidemind: several corporate designs are at hand — ask the user which to build against:\n" +
+      `${designRows(designs).join("\n")}\n`;
+    if (suggested) {
+      const s = designs.find((d) => d.presFP === suggested);
+      human += `  (this deck was last built against ${s?.name ?? suggested} (${suggested}))\n`;
+    }
+    human += `Then re-run: ${rerun}`;
+    finishBlocker({
+      blocker,
+      extras: { designs, suggested, windows: publicWindows() },
+      humanLines: human,
+    });
+  };
+
+  // --- A design resolved WITHOUT a window — the deck's own binding, an
+  // explicit --brand, or the backend's brand list. Same payload either way:
+  // ready, `windowless: true`, and a pane status that is INFORMATIONAL. What
+  // the missing window actually costs depends on the engine routes: with them
+  // only push/insert-slide and reading an open presentation need PowerPoint.
+  //
+  // "Windowless" is about how the DESIGN was resolved, not about the registry:
+  // --brand runs before the registry is consulted at all, and the later rungs
+  // fire on "nothing render-ready", which a connected-but-still-matching window
+  // satisfies. So the pane status is DERIVED from the registry as it stands at
+  // call time (the hydration wait reassigns it), and the prose only claims
+  // "no PowerPoint window" when there genuinely is none. ---
+  const finishWindowless = async (result) => {
+    if (deckDir) {
+      bundle.writeDeckBundleRef(deckDir, {
+        presFP: result.presFP,
+        etag: result.etag,
+      });
+    }
+    const designName = readDesignName(result.dir);
+    const env = result.backendURL ? cfg.deriveEnvLabel(result.backendURL) : null;
+    const eng = await engines();
+    const m = await m365();
+    const paneReady = registry.some(client.isPaneReadyPresentation);
+    const noWindow = registry.length === 0;
+    const stage = deckDir ? await deckStage(deckDir) : null;
+    const nextAction = noWindow
+      ? eng.available
+        ? "Ready (no PowerPoint window — authoring, engine search and build-pptx all work; only push/insert-slide and reading an open presentation need one)."
+        : "Ready (no PowerPoint window — build-pptx/build/review/view-draft work; push/search/read need a pane)."
+      : paneReady
+        ? "Ready (design resolved without targeting a window; a registered PowerPoint window is available for push/insert-slide)."
+        : eng.available
+          ? "Ready (design resolved without targeting a window; pane operations — push/insert-slide/read of a window — will wait for a pane click; engine search does not)."
+          : "Ready (design resolved without targeting a window; pane operations — push/search/read — will wait for a pane click).";
+    if (asJson) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            ready: true,
+            windowless: true,
+            deck: deckSlug,
+            bound: Boolean(deckDir),
+            env,
+            presId: null,
+            presFP: result.presFP,
+            designName,
+            designs: await designMenu({ current: result.presFP }),
+            windows: publicWindows(),
+            bundleDir: result.dir,
+            bundleEtag: result.etag ?? null,
+            paneSuspended: !paneReady,
+            engines: eng,
+            ...(m ? { m365: { signedIn: m.signedIn, degradation: m.degradation } } : {}),
+            warnings: result.warnings ?? [],
+            ...(stage ? { stage } : {}),
+            nextAction,
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+      return;
+    }
+    const designLabel = designName
+      ? `${designName} (${result.presFP})`
+      : result.presFP;
+    process.stdout.write(
+      `Ready — design ${designLabel}${envTag(env)}${noWindow ? " (no PowerPoint window)" : ""}\n`,
+    );
+    process.stdout.write(`  bundle: ${result.dir} (etag ${result.etag ?? "?"})\n`);
+    if (deckDir) process.stdout.write(`  deck ${deckSlug} bound\n`);
+    if (stage) process.stdout.write(stageHumanLines(stage));
+    process.stdout.write(windowsHumanLine(publicWindows()));
+    process.stdout.write(designsHumanLines(await designMenu({ current: result.presFP })));
+    process.stdout.write(
+      noWindow
+        ? eng.available
+          ? "  Note: authoring, engine search and build-pptx need no window; push/insert-slide and reading an open presentation do.\n"
+          : "  Note: build-pptx/build/review/view-draft work without a window; push/search/read need a pane.\n"
+        : paneReady
+          ? "  Note: the design was resolved without targeting a window; a registered PowerPoint window is available for push/insert-slide.\n"
+          : eng.available
+            ? "  Note: pane operations (push/insert-slide/read of a window) will wait for a pane click; engine search does not.\n"
+            : "  Note: pane operations (push/search/read) will wait for a pane click.\n",
+    );
+    if (m) process.stdout.write(`  ${m.line}\n`);
+    for (const w of result.warnings ?? []) {
+      process.stderr.write(`  warning: ${w}\n`);
+    }
+  };
+
+  // Materialize a design by id over the pane-free brand route. Returns null on
+  // any miss (old add-in, unknown/revoked design) so the caller can fall
+  // through to the window ladder instead of dead-ending.
+  const materializeBrand = async (brandId) => {
+    try {
+      return await bundle.materializeBundle(null, { force, brandId });
+    } catch {
+      return null;
+    }
+  };
+
+  // --- --brand <presFP>: the user (or the agent, after an ambiguous brand
+  // list) named the design outright. It resolves with or without a window, so
+  // it runs before the registry is consulted at all. ---
+  if (brand) {
+    const result = await materializeBrand(brand);
+    if (!result) {
+      finishBlocker({
+        blocker: {
+          code: "unknown_brand",
+          actor: "user",
+          message: `No connected slidemind add-in serves design '${brand}'. Run 'slidemind ready' with no --brand to see which designs are available.`,
+        },
+      });
+      return;
+    }
+    await finishWindowless(result);
+    return;
+  }
+
+  // --- Bound-deck ladder: session → bundle freshness, no pane precondition.
+  // The design identity (presFP == brandId) lives in the deck's
+  // .bundle-ref.json and the bundle syncs over the pane-free brand route, so
+  // with PowerPoint CLOSED (an empty registry) a bound deck readies straight
+  // away instead of sitting out the hydration wait for a window that isn't
+  // coming. A registry that holds windows still hydrates first — the open
+  // add-in stays the source of truth whenever there IS one. Skipped for
+  // --connect-only (which resolves no design at all) and for --to (an explicit
+  // window must resolve through the registry); a miss (old add-in, legacy ref,
+  // revoked grant) falls through to the window ladder. ---
+  const boundDeckLadder = deckDir && deckPresFP && !to && !connectOnly;
+  let boundRungTried = false;
+  if (boundDeckLadder && registry.length === 0) {
+    boundRungTried = true;
+    const result = await materializeBrand(deckPresFP);
+    if (result) {
+      await finishWindowless(result);
+      return;
+    }
+  }
+
+  // --- Bounded hydration wait when nothing is render-ready yet: covers the
+  // just-clicked / just-woke pane still hydrating brand metadata. Polls even on
+  // an empty registry (that's the flaky window this papers over). ---
+  if (!registry.some(isRR)) {
+    const waitMs =
+      parseInt(process.env.SLIDEMIND_BRIDGE_PRESENTATIONS_WAIT_MS || "6000", 10) ||
+      6000;
+    const pollMs =
+      parseInt(process.env.SLIDEMIND_BRIDGE_READY_POLL_MS || "1500", 10) || 1500;
+    const deadline = Date.now() + waitMs;
+    while (!registry.some(isRR) && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, pollMs));
+      registry = (await client.listOpenPresentationsDetailed()).presentations;
+    }
+  }
+  // Everything below terminates the command: it is the whole "no render-ready
+  // window" resolution (connect-only engine answer → bound-deck rung → brand
+  // list → late blocker). A named closure because TWO paths land here: the
+  // registry genuinely holding no render-ready window, and the ping check
+  // below pruning the last one as a zombie.
+  const finishNoRenderReady = async () => {
+    // --connect-only asks one question — "can I work?" — and since the engine
+    // routes answer off the session, a backend that serves them IS the answer:
+    // discovery, search and every per-result fetch run with PowerPoint closed.
+    // Without them search is still relayed through a pane, so the window rung
+    // below stands.
+    if (connectOnly && (await engines()).available) {
+      const eng = await engines();
+      const m = await m365();
+      if (asJson) {
+        process.stdout.write(
+          JSON.stringify(
+            {
+              ready: true,
+              connectOnly: true,
+              windowless: true,
+              engines: eng,
+              ...(m ? { m365: { signedIn: m.signedIn, degradation: m.degradation } } : {}),
+              nextAction:
+                "Ready (no PowerPoint window — engine search runs off the connection; only insert-slide needs one).",
+              backends: (pub.backends ?? []).map((b) => ({ env: b.env, ok: b.ok })),
+            },
+            null,
+            2,
+          ) + "\n",
+        );
+      } else {
+        process.stdout.write(
+          `Connected. ${pub.backendCount} backend(s), 0 window(s) registered — ` +
+            `engine search runs without one${envTag(eng.envs.join(", "))}.\n`,
+        );
+        if (m) process.stdout.write(`  ${m.line}\n`);
+      }
+      return;
+    }
+    // The bound-deck ladder again, for the windows-registered-but-never-ready
+    // case the pre-poll rung deliberately left to the hydration wait.
+    if (boundDeckLadder && !boundRungTried) {
+      boundRungTried = true;
+      const result = await materializeBrand(deckPresFP);
+      if (result) {
+        await finishWindowless(result);
+        return;
+      }
+    }
+    // --- Unbound + no window: the ONE design cached here is the answer, else
+    // the ONE design the backend lists; several of either genuinely need a
+    // human choice, which --brand records. A backend without the brand route
+    // (or a deck already bound to a design it just refused) falls through
+    // unchanged — as does a connection with every backend down, where a
+    // design menu would only hide the real blocker. ---
+    if (!connectOnly && !to && !deckPresFP && !boundRungTried && !backendBlocker(pub)) {
+      const cached = bundle.listCachedBundles();
+      if (cached.length === 1) {
+        const result = await materializeBrand(cached[0].presFP);
+        if (result) {
+          await finishWindowless(result);
+          return;
+        }
+      }
+      let brands = [];
+      try {
+        brands = await client.listBrands();
+      } catch {
+        /* no brand list — the window ladder below is the answer */
+      }
+      if (cached.length === 0 && brands.length === 1) {
+        const result = await materializeBrand(brands[0].presFP);
+        if (result) {
+          await finishWindowless(result);
+          return;
+        }
+      } else if (cached.length > 1 || brands.length > 1) {
+        await finishAmbiguous();
+        return;
+      }
+    }
+    // Only the no-window / not-render-ready rungs are reachable here (terminal
+    // blockers already returned; a render-ready window would have exited the
+    // poll). Reuse the ladder's exact strings over the freshly-polled registry.
+    const latePub = {
+      paired: true,
+      backendCount: pub.backendCount,
+      backends: pub.backends,
+      presentations: registry.map(client.toPublicPresentation),
+    };
+    const b =
+      connectionBlocker(latePub) ?? {
+        code: "not_render_ready",
+        actor: "user",
+        message:
+          "PowerPoint is connected, but no window is render-ready. Wait for corporate design matching or activate/create a corporate design.",
+      };
+    finishBlocker({ blocker: b });
+    return;
+  };
+  // --- Zombie prune, BEFORE any resolution: a webview whose document was
+  // closed keeps its socket — and thus a "connected" registry lease — alive
+  // indefinitely, and only a host round-trip inside the pane can tell. Every
+  // window claiming a LIVE pane gets one truth ping (in parallel); a dead one
+  // leaves the registry, so it can neither win silently nor fake a second
+  // design. Narrow on purpose: an explicit --to is the user's call, a
+  // suspended window keeps its silent-adopt semantics (backgrounded
+  // PowerPoint must not start asking questions), and a backend without
+  // paneLivenessV1 fails open. ---
+  const backendAdvertisesPing = (entry) =>
+    (statusRaw.backends ?? []).some(
+      (b) =>
+        b.ok &&
+        b.backendURL === entry.backendURL &&
+        b.capabilities?.paneLivenessV1 === true,
+    );
+  const entryIsAlive = async (entry) => {
+    try {
+      const ack = await client.pingPresentation({
+        presId: entry.presId,
+        backendURL: entry.backendURL ?? null,
+      });
+      return ack?.ok !== false;
+    } catch (err) {
+      // Dead only on the typed pane verdicts; anything else (404 route on an
+      // older backend, a transport blip) fails open — adopt as before.
+      return ![
+        "pane_suspended",
+        "pane_timeout",
+        "pane_disconnected",
+        "bridge_timeout",
+      ].includes(err?.code);
+    }
+  };
+  if (!to) {
+    const suspects = registry.filter(
+      (p) => isRR(p) && client.isPaneReadyPresentation(p) && backendAdvertisesPing(p),
+    );
+    const alive = await Promise.all(suspects.map(entryIsAlive));
+    const dead = new Set(suspects.filter((_, i) => !alive[i]));
+    if (dead.size > 0) registry = registry.filter((p) => !dead.has(p));
+  }
+
+  if (!registry.some(isRR)) {
+    await finishNoRenderReady();
+    return;
+  }
+
+  // --- --connect-only: the connection is up with ≥1 render-ready window; the
+  // search skill needs nothing more (no design resolution, no bundle). ---
+  if (connectOnly) {
+    const m = await m365();
+    if (asJson) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            ready: true,
+            connectOnly: true,
+            engines: await engines(),
+            ...(m ? { m365: { signedIn: m.signedIn, degradation: m.degradation } } : {}),
+            nextAction: "Ready.",
+            backends: (pub.backends ?? []).map((b) => ({ env: b.env, ok: b.ok })),
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+    } else {
+      const windows = registry.filter(isRR).length;
+      process.stdout.write(
+        `Connected. ${pub.backendCount} backend(s), ${windows} window(s) registered.\n`,
+      );
+      if (m) process.stdout.write(`  ${m.line}\n`);
+    }
+    return;
+  }
+
+  // --- Local: pick WHICH design. The order is the user's, not the window's:
+  // an explicit --to, else the deck's own binding (a window on that design is
+  // targeted, none at all readies windowless over the brand route), else the
+  // ONE design the verified windows agree on. Anything else is a choice only
+  // the user can make — the ambiguous blocker puts the menu in front of them. ---
+  let resolution;
+  if (to) {
+    resolution = client.resolveDesignSource(registry, {
+      explicitPresId: to,
+      deckPresFP,
+    });
+  } else {
+    const onDeckDesign = deckPresFP
+      ? registry.filter((p) => isRR(p) && p.brandId === deckPresFP)
+      : [];
+    if (boundDeckLadder && onDeckDesign.length === 0) {
+      boundRungTried = true;
+      const result = await materializeBrand(deckPresFP);
+      if (result) {
+        await finishWindowless(result);
+        return;
+      }
+    }
+    resolution = client.resolveDesignSource(
+      onDeckDesign.length > 0 ? onDeckDesign : registry,
+      { deckPresFP },
+    );
+  }
+
+  if (resolution.status === "none") {
+    // Defensive: a render-ready window exists (poll passed) so this is rare.
+    finishBlocker({
+      blocker: {
+        code: "not_render_ready",
+        actor: "user",
+        message:
+          "PowerPoint is connected, but no window is render-ready. Wait for corporate design matching or activate/create a corporate design.",
+      },
+    });
+    return;
+  }
+
+  if (resolution.status === "unknown_presid") {
+    const windows = registry.filter(isRR).map(client.toPublicPresentation);
+    const candidates = windows.map((p) => ({
+      presId: p.presId,
+      env: p.env ?? null,
+      title: p.title ?? null,
+      fileName: p.fileName ?? null,
+    }));
+    const blocker = {
+      code: "unknown_presid",
+      actor: "user",
+      message: `No render-ready PowerPoint window has presId='${to}'. Re-run 'slidemind ready --to <presId>' with one of the open windows.`,
+    };
+    const rows = windows.map(
+      (p) =>
+        `  ${p.presId} ${envTag(p.env)}  ${p.title || p.fileName || "(untitled)"}`,
+    );
+    finishBlocker({
+      blocker,
+      extras: { candidates },
+      humanLines:
+        `slidemind: ${blocker.message}\n` +
+        `${rows.join("\n")}`,
+    });
+    return;
+  }
+
+  if (resolution.status === "ambiguous") {
+    await finishAmbiguous();
+    return;
+  }
+
+  // --- Network: materialize the resolved design's bundle. Always called —
+  // incremental etag-gated download makes an unchanged bundle near-free and a
+  // changed one refreshes. ---
+  const entry = resolution.entry;
+  const result = await bundle.materializeBundle(entry.presId, {
+    force,
+    backendURL: entry.backendURL ?? null,
+    preferBrandId: entry.brandId ?? null,
+  });
+
+  // --- Local: bind the deck (kills the second download-bundle). ---
+  let bound = false;
+  if (deckDir) {
+    bundle.writeDeckBundleRef(deckDir, {
+      presFP: result.presFP,
+      etag: result.etag,
+    });
+    bound = true;
+  }
+
+  const designName = readDesignName(result.dir);
+  const paneSuspended = !client.isPaneReadyPresentation(entry);
+  const engineInfoForWindow = await engines();
+  const m365ForWindow = await m365();
+  const stageForWindow = deckDir ? await deckStage(deckDir) : null;
+
+  if (asJson) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          ready: true,
+          deck: deckSlug,
+          bound,
+          env: entry.env ?? null,
+          presId: entry.presId,
+          presFP: result.presFP,
+          designName,
+          designs: await designMenu({ current: result.presFP }),
+          windows: publicWindows(),
+          bundleDir: result.dir,
+          bundleEtag: result.etag ?? null,
+          presentation: {
+            title: entry.title ?? null,
+            fileName: entry.fileName ?? null,
+          },
+          paneSuspended,
+          engines: engineInfoForWindow,
+          ...(m365ForWindow
+            ? {
+                m365: {
+                  signedIn: m365ForWindow.signedIn,
+                  degradation: m365ForWindow.degradation,
+                },
+              }
+            : {}),
+          warnings: result.warnings ?? [],
+          ...(stageForWindow ? { stage: stageForWindow } : {}),
+          nextAction: "Ready.",
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  // --- Human success: compact multi-line summary on stdout. ---
+  const entryEnv = envTag(entry.env);
+  const presLabel = entry.title || entry.fileName || "(untitled)";
+  const designLabel = designName
+    ? `${designName} (${result.presFP})`
+    : result.presFP;
+  process.stdout.write(`Ready — design ${designLabel}\n`);
+  process.stdout.write(`  presentation: ${presLabel}${entryEnv}\n`);
+  process.stdout.write(
+    `  bundle: ${result.dir} (etag ${result.etag ?? "?"})\n`,
+  );
+  if (bound) process.stdout.write(`  deck ${deckSlug} bound\n`);
+  if (stageForWindow) process.stdout.write(stageHumanLines(stageForWindow));
+  process.stdout.write(windowsHumanLine(publicWindows()));
+  process.stdout.write(designsHumanLines(await designMenu({ current: result.presFP })));
+  if (paneSuspended) {
+    process.stdout.write(
+      engineInfoForWindow.available
+        ? "  Note: pane operations (push/insert-slide/read of this window) will wait for a pane click; engine search does not.\n"
+        : "  Note: pane operations (push/search/read) will wait for a pane click.\n",
+    );
+  }
+  if (m365ForWindow) process.stdout.write(`  ${m365ForWindow.line}\n`);
+  for (const w of result.warnings ?? []) {
+    process.stderr.write(`  warning: ${w}\n`);
+  }
+}