slidemind 0.3.20 → 0.4.0

package/src/cli/search.mjs

@@ -5,6 +5,24 @@ import { fail, resolveDeckArg, SRC_DIR } from "./common.mjs";
 import { readDesignName, readThemeColors, designRows } from "./designs.mjs";
 import { searchFailureHint, writeEmptySearchDiagnostic, writeSearchGrid, resolveEngineRouting, deckBrandId, failOnEngineBlocker, paneRelayForLoginRequired } from "./engine-helpers.mjs";
 
+// The live engine catalog, or null when the caller falls back to the bundle:
+// this add-in has no catalog route (a 404). A catalog that wants a Microsoft
+// 365 sign-in while a pane is open falls back too, naming that pane — it
+// refuses a token-less CLI even then, and the search itself relays through the
+// pane (paneRelayForLoginRequired). Anything else — a 429, a timeout, an
+// outage — is not "no engines": it surfaces as itself (x71/x72: a rate-limited
+// read printed "no image engines" and the agent fabricated icons).
+async function liveCatalog(client, opts, to) {
+  try {
+    return await client.listEngines(opts);
+  } catch (err) {
+    if (err?.status === 404) return null;
+    const relay = await paneRelayForLoginRequired(client, err, { to });
+    if (relay) return { engines: [], pane: relay.entry };
+    return failOnEngineBlocker(client, err, { to });
+  }
+}
+
 export async function cmdSearch(rest) {
   let asJson = false;
   let to = null;
@@ -111,7 +129,7 @@ export async function cmdSearch(rest) {
     !bundle.isSearchScopeId(engineId) &&
     !/^[0-9a-f-]{8,}$/i.test(engineId)
   ) {
-    const live = await client.listEngines({ backendURL }).catch(() => null);
+    const live = await liveCatalog(client, { backendURL }, to);
     const wanted = engineId.toLowerCase();
     const ids = new Set(
       (live?.engines ?? [])
@@ -140,26 +158,27 @@ export async function cmdSearch(rest) {
       // Imagery: resolve a real image engine (a scope is not a brand image
       // source). Ask the LIVE catalog first — the same one the add-in's own
       // design agent reads — and fall back to the materialized bundle only when
-      // the host can't answer. Bundle-first would be stale: engine ids can be
-      // retired server-side, and a dead id surfaces as "Engine not found".
-      const live = await client
-        .listEngines({ subtype: "image", backendURL })
-        .catch(() => ({ engines: [] }));
+      // the add-in has no catalog route. Bundle-first would be stale: engine
+      // ids can be retired server-side, and a dead id surfaces as "Engine not
+      // found".
+      const live = (await liveCatalog(client, { subtype: "image", backendURL }, to)) ?? { engines: [] };
       let pick = bundle.pickImageEngine(live.engines);
       if (!pick) {
         // Best-effort: a bundle that can't be materialized (e.g. an incomplete
         // one) must not replace the actionable "wire an image engine" message
         // below with a bundle error — the live catalog is the real answer here.
-        // Pane path: fetch by the window's presId. Direct path: there is no
-        // window, so only a bound deck (--deck) can name the design; without one
-        // there is nothing to fall back to and the live catalog's answer stands.
+        // Pane path: fetch by the window's presId. Direct path: a bound deck
+        // (--deck) names the design, else the open pane a sign-in-less search
+        // relays through; without either there is nothing to fall back to and
+        // the live catalog's answer stands.
         const brandId = presId
           ? null
           : await deckBrandId(deck ? resolveDeckArg(deck) : null);
+        const windowId = presId ?? (brandId ? null : (live.pane?.presId ?? null));
         const mat =
-          presId || brandId
+          windowId || brandId
             ? await bundle
-                .materializeBundle(presId, { backendURL, brandId })
+                .materializeBundle(windowId, { backendURL, brandId })
                 .catch(() => null)
             : null;
         if (mat) pick = bundle.pickImageEngine(bundle.readEnginesFromDir(mat.dir));

package/src/cli/session.mjs

@@ -65,7 +65,11 @@ export async function cmdLogin(rest) {
     `Signed in to Microsoft 365 as ${res.username ?? "your account"}${envPhrase(target.label, "for")}.\n` +
       "SharePoint-backed slides and images now download with no PowerPoint window open.\n",
   );
-  const others = sessions.filter((s) => s.backendURL !== target.backendURL);
+  // Only the environments that actually still lack a Graph session — listing a
+  // backend the user signed in to earlier reads as "your sign-in was lost".
+  const others = sessions.filter(
+    (s) => s.backendURL !== target.backendURL && !graph.hasGraphSession(s.backendURL),
+  );
   if (others.length > 0) {
     process.stdout.write(
       `Still signed out: ${others.map((s) => s.label).join(", ")} ` +
@@ -74,19 +78,29 @@ export async function cmdLogin(rest) {
   }
 }
 
-export async function cmdWhoami() {
+export async function cmdWhoami(rest = []) {
+  const asJson = rest.includes("--json");
+  const stray = rest.find((a) => a.startsWith("-") && a !== "--json");
+  if (stray) fail(`unexpected argument: ${stray}\nusage: slidemind whoami [--json]`);
   const cfg = await loadBridgeModule("config");
   const sessions = cfg.readSessions();
   if (sessions.length === 0) {
+    // An agent asked a question and must get an answer it can parse — "no
+    // environments" is one, a bare stderr line is not.
+    if (asJson) {
+      process.stdout.write(`${JSON.stringify({ environments: [] }, null, 2)}\n`);
+      return;
+    }
     process.stderr.write(`${NOT_CONNECTED_LINE}\n`);
     return;
   }
   const { httpJson } = await loadBridgeModule("http-json");
   const graph = await loadBridgeModule("graph-auth");
   const def = cfg.getDefaultBackend();
-  const lines = await Promise.all(
+  const envs = await Promise.all(
     sessions.map(async (s) => {
-      const marker = s.backendURL === def ? "*" : " ";
+      let oid = null;
+      let tid = null;
       let detail;
       try {
         const res = await httpJson(
@@ -94,21 +108,50 @@ export async function cmdWhoami() {
           `${s.backendURL}/api/cli/whoami`,
           { token: s.sessionToken },
         );
-        detail =
-          res.status === 200 && res.json
-            ? `user ${res.json.oid} · tenant ${res.json.tid ?? "(n/a)"}`
-            : `session invalid (${res.status}) — authorize again`;
+        if (res.status === 200 && res.json) {
+          oid = res.json.oid ?? null;
+          tid = res.json.tid ?? null;
+          detail = `user ${oid} · tenant ${tid ?? "(n/a)"}`;
+        } else {
+          detail = `session invalid (${res.status}) — authorize again`;
+        }
       } catch {
         detail = "unreachable — check your connection or authorize again";
       }
       // Storage-only — no probe. The Graph sign-in is a SECOND identity, so it
-      // is reported next to the session rather than folded into it.
-      const graphLine = graph.hasGraphSession(s.backendURL)
-        ? "Microsoft 365: signed in"
-        : "Microsoft 365: not signed in — needed only for window-free SharePoint downloads (`slidemind login`)";
-      return `${marker} ${s.label}\n    ${detail}\n    ${graphLine}`;
+      // is reported next to the session rather than folded into it, and the
+      // account name is whatever `login` wrote down at sign-in (records written
+      // before that field existed are signed in with no name to show).
+      return {
+        label: s.label,
+        default: s.backendURL === def,
+        oid,
+        tid,
+        microsoft365: {
+          signedIn: graph.hasGraphSession(s.backendURL),
+          username: s.msGraphUsername ?? null,
+        },
+        detail,
+      };
     }),
   );
+  if (asJson) {
+    process.stdout.write(
+      `${JSON.stringify(
+        { environments: envs.map(({ detail, ...env }) => env) },
+        null,
+        2,
+      )}\n`,
+    );
+    return;
+  }
+  const lines = envs.map((env) => {
+    const marker = env.default ? "*" : " ";
+    const graphLine = env.microsoft365.signedIn
+      ? `Microsoft 365: signed in${env.microsoft365.username ? ` as ${env.microsoft365.username}` : ""}`
+      : "Microsoft 365: not signed in — needed only for window-free SharePoint downloads (`slidemind login`)";
+    return `${marker} ${env.label}\n    ${env.detail}\n    ${graphLine}`;
+  });
   process.stdout.write(
     `Connected environments (${sessions.length}):\n${lines.join("\n")}\n`,
   );

package/src/cli/setup.mjs

@@ -174,7 +174,16 @@ export async function cmdSetup(rest) {
     bundleMod.clearBundleCache();
   }
 
-  // --- 4. Microsoft 365 sign-in (best-effort) -----------------------------
+  // --- 4. the workspace: running now, and at every login -------------------
+  // Where the user answers the agent's questions (doc 21). It must be running
+  // BEFORE an agent asks: inside Codex's sandbox an agent can neither start it
+  // nor keep a detached process, so this unsandboxed moment — the user pasting
+  // the setup line — is when it starts, and the login item keeps it there.
+  // Best-effort: a failure here never fails setup (any unsandboxed CLI run
+  // starts it again). SLIDEMIND_NO_AUTOSTART=1 leaves it alone (tests, CI).
+  const workspace = await setUpWorkspace({ ui, globalScript: installed });
+
+  // --- 5. Microsoft 365 sign-in (best-effort) -----------------------------
   // The pasted-claim moment is the one time the user is reliably at the
   // keyboard in consent headspace, so offer the browser sign-in NOW and no
   // later command has to interrupt a task for it. Strictly best-effort and
@@ -238,6 +247,7 @@ export async function cmdSetup(rest) {
           // Present-but-plugin-served harnesses, so an agent can tell "nothing
           // deployed because nothing is installed" from "nothing needed".
           skippedPlugins,
+          workspace,
           nextAction: "slidemind ready",
           // Only on the unhappy path: the session IS saved, so `ok` stays true,
           // but an agent needs to know the binary did not land.
@@ -271,7 +281,7 @@ export async function cmdSetup(rest) {
     return;
   }
 
-  // --- 5. finish the session the user actually came for -------------------
+  // --- 6. finish the session the user actually came for -------------------
   // `ready` exits non-zero for every legitimate not-yet blocker (PowerPoint
   // closed, no design activated). Setup already succeeded at that point, so its
   // blocker is information, not a failure — run it for the message and the
@@ -280,3 +290,37 @@ export async function cmdSetup(rest) {
     await spawnStatus(process.execPath, [BIN_PATH, "ready"]);
   }
 }
+
+/**
+ * Start the workspace and register its login item. Resolves `{ running, url,
+ * atLogin }` for the --json payload; never throws.
+ */
+async function setUpWorkspace({ ui, globalScript }) {
+  if (process.env.SLIDEMIND_NO_AUTOSTART === "1") return { running: null, url: null, atLogin: "skipped" };
+  await ui.section("workspace", "where you answer your agent");
+  const { ensureRunning } = await import("../workspace/lifecycle.mjs");
+  const auto = await import("../workspace/autostart.mjs");
+  const out = { running: false, url: null, atLogin: "unsupported" };
+  // the login item needs paths that outlive npx's cache and a node upgrade
+  const scriptPath = auto.stableScriptPath({ running: globalScript ? null : BIN_PATH });
+  if (auto.autostartPath()) {
+    if (!scriptPath) {
+      out.atLogin = "skipped";
+      ui.step({ status: "warn", label: "at login", value: "skipped", note: "no permanent slidemind install to start it from" });
+    } else {
+      const env = { PATH: process.env.PATH, SLIDEMIND_NO_UPDATE_CHECK: "1", ...(process.env.XDG_CONFIG_HOME ? { XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME } : {}) };
+      const r = auto.installAutostart({ nodePath: auto.stableNodePath(), scriptPath, env });
+      out.atLogin = r.installed ? "registered" : "failed";
+      ui.step(r.installed ? { label: "at login", value: "starts by itself" } : { status: "warn", label: "at login", value: "not registered", note: r.reason ?? "" });
+    }
+  }
+  try {
+    const run = await ensureRunning({ note: () => {} });
+    out.running = true;
+    out.url = run.url;
+    ui.step({ label: "workspace", value: "running" });
+  } catch (err) {
+    ui.step({ status: "warn", label: "workspace", value: "not started", note: err?.message ?? String(err) });
+  }
+  return out;
+}

package/src/cli/status.mjs

@@ -3,21 +3,51 @@
 // stand and what is the next command. `ready <deck>` prints it (the skill
 // already names `ready` as the first command after any continuation), so the
 // stage → re-read table that used to live in the skill's prose is a line of
-// output instead. Pure disk: no bridge call, no bundle read.
+// output instead. Pure disk: no bridge call (the materialized bundle's layout
+// jobs are read only to tell frame slides from body slides).
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { BUILDERS_DIR } from "./common.mjs";
+import { deckRoot, deckSlug } from "../lib/deck-paths.mjs";
+import { revisionStatus } from "../lib/revision.mjs";
+import { remoteHumanLine, remoteReadiness, savedDestination } from "../lib/remote.mjs";
+import { listTasks } from "../workspace/tasks.mjs";
+import { receiveCommand } from "../workspace/handback.mjs";
+
+const GATE_COMMAND = { "plan-approval": "plan", "preview-review": "review" };
+
+/**
+ * The workspace's side of the two gates, read from the deck's task store: an
+ * answer the human gave that no agent has received yet (it wins — the gate
+ * command hands it over), else a question still waiting for the human. Null
+ * when the deck has neither, or no readable store.
+ */
+export function workspaceGate(deckDir) {
+  let tasks;
+  try {
+    tasks = listTasks(deckRoot(deckDir));
+  } catch {
+    return null;
+  }
+  const gates = tasks.filter((t) => GATE_COMMAND[t.kind]);
+  const unreceived = gates
+    .filter((t) => t.status === "completed" && !t.pickedUpAt)
+    .sort((a, b) => String(b.response?.at ?? "").localeCompare(String(a.response?.at ?? "")))[0];
+  if (unreceived) return { kind: unreceived.kind, state: "answered", action: unreceived.response?.action ?? null, at: unreceived.response?.at ?? null, taskId: unreceived.id, adapterId: unreceived.adapterId ?? null };
+  const pending = gates.find((t) => t.status === "pending");
+  return pending ? { kind: pending.kind, state: "asked", action: null, at: pending.createdAt, taskId: pending.id, adapterId: pending.adapterId ?? null } : null;
+}
 
 const load = (name) => import(pathToFileURL(path.join(BUILDERS_DIR, name)).href);
 
 export async function deckStage(deckDir) {
-  const slug = path.basename(deckDir);
-  const [plan, review, check, families] = await Promise.all([
+  const slug = deckSlug(deckDir);
+  const [plan, review, check, conceptWaves] = await Promise.all([
     load("plan.mjs"),
     load("review.mjs"),
     load("draft-check.mjs"),
-    load("visual-families.mjs"),
+    load("concept-waves.mjs"),
   ]);
   const slidesDir = path.join(deckDir, "slides");
   const files = fs.existsSync(slidesDir) ? fs.readdirSync(slidesDir).sort() : [];
@@ -29,7 +59,7 @@ export async function deckStage(deckDir) {
   const planPath = path.join(deckDir, "plan.md");
   const planExists = fs.existsSync(planPath);
   const planMarkdown = planExists ? fs.readFileSync(planPath, "utf8") : "";
-  const planned = planExists ? [...families.plannedSlideNumbers(planMarkdown)].sort((a, b) => a - b) : [];
+  const planned = planExists ? [...conceptWaves.plannedSlideNumbers(planMarkdown)].sort((a, b) => a - b) : [];
   const planState = plan.loadPlanState(deckDir);
   const planApproved = planExists && plan.requirePlanApproved(deckDir) === null;
 
@@ -37,82 +67,161 @@ export async function deckStage(deckDir) {
   const concepts = fs.existsSync(conceptsDir)
     ? fs.readdirSync(conceptsDir).filter((f) => /^concept-slide-\d+\.png$/.test(f)).length
     : 0;
-  const assets = check.assetPlanSummary(deckDir);
 
   const record = check.loadDraftCheck(deckDir);
   const draftFresh =
     Boolean(record?.slides) &&
     jsx.every((f) => record.slides[f] && record.slides[f].hash === check.hashFile(path.join(slidesDir, f)));
   const standing = check.draftCheckBlocker(deckDir) ? Object.values(record?.slides ?? {}).reduce((n, e) => n + (e.defects?.length ?? 0), 0) : 0;
-  const selfCheck = check.verdictBlocker(deckDir) ? "incomplete" : "ok";
 
   const reviewState = review.loadReviewState(deckDir);
+  // Passed once is passed: a deck edited after its approval goes to deliver,
+  // never back to the review gate.
   const reviewCurrent = review.requireReviewApproved(deckDir) === null;
 
-  const missing = planned.filter((n) => !authored.has(n));
+  // An ADOPTED deck already exists. It has no storyboard to approve, no preview
+  // to approve, nothing to concept and nothing missing to author — its route is
+  // edit → draft check → deliver, and its own state is the accepted base, not plan.md.
+  const revision = revisionStatus(deckDir);
+  const remote = remoteReadiness(deckDir, revisionStatus);
+  // A folder the user connected in the workspace before any publish: the next
+  // build creates the file there (build-pptx publishes a connected deck itself).
+  const folder = remote ? null : savedDestination(deckDir);
+  const intoFolder = folder ? `creates ${folder.name} in the SharePoint folder the user connected` : null;
+  const editRoute = plan.isEditRouteDeck(deckDir);
+
+  const missing = editRoute ? [] : planned.filter((n) => !authored.has(n));
+  // Body slides owing their content draft, before any concept or slide exists.
+  const owed = !editRoute && planApproved && concepts === 0 && authored.size === 0 ? plan.slidesWithoutContent(deckDir, planMarkdown) : [];
   let name;
   let next;
   // No plan.md and no slides: nothing exists yet. No plan.md but slides: an
   // adopted or hand-made deck on the edit route — no plan, no concepts.
-  if (authored.size === 0 && (!planExists || planned.length === 0)) {
+  if (editRoute && revision.conflicts > 0) {
+    name = "reconcile";
+    next = `\`slidemind rebase ${slug} --dry-run\` to see the ${revision.conflicts} open conflict(s), then resolve them`;
+  } else if (editRoute && (!draftFresh || standing > 0)) {
+    name = "draft check";
+    next = revision.localDirty
+      ? `\`slidemind view-draft ${slug}\` (${revision.dirtySlides.length} slide(s) changed since the accepted base)`
+      : `\`slidemind view-draft ${slug}\``;
+  } else if (editRoute) {
+    name = "deliver";
+    // On a remote-bound deck `revision accept` REFUSES (only a confirmed publish
+    // receipt may move that base), so naming it here would send the agent into a
+    // guaranteed error. Publishing is the acceptance door there, and a build
+    // walks through it itself; a candidate still standing is one whose publish
+    // did not save (or a `--no-publish` build).
+    next = remote
+      ? revision.candidate && !revision.candidate.stale
+        ? `\`slidemind publish ${slug}\` — it reconciles first and replaces ${remote.name ?? "the bound file"} only if nobody saved meanwhile`
+        : `\`slidemind build-pptx ${slug}\` — it publishes to ${remote.name ?? "the bound file"} too`
+      : folder
+        ? revision.candidate && !revision.candidate.stale
+          ? `\`slidemind publish ${slug}\` — it ${intoFolder}`
+          : `\`slidemind build-pptx ${slug}\` — it publishes too: ${intoFolder}`
+      : revision.candidate && !revision.candidate.stale
+        ? `\`slidemind revision accept ${slug} --candidate ${revision.candidate.candidateId}\` to make that build the deck's base, or \`slidemind push ${slug}\``
+        : `\`slidemind build-pptx ${slug}\` (writes a candidate; accepting it is a separate, deliberate step)`;
+  } else if (authored.size === 0 && (!planExists || planned.length === 0)) {
     name = "intake";
     next = `write ${slug}/plan.md (## Red thread + ## Per-slide storyboards), then \`slidemind plan ${slug}\``;
   } else if (planExists && !planApproved) {
     name = "plan gate";
     next = planState.decision === "comments"
-      ? `apply the comments in ${slug}/plan-review.json to plan.md, then \`slidemind plan ${slug}\``
+      ? `apply the comments in ${slug}/.slidemind/state/plan-review.json to plan.md, then \`slidemind plan ${slug}\``
       : `\`slidemind plan ${slug}\` (wait for DECISION: approved)`;
+  } else if (owed.length > 0) {
+    // A deck continued from an approved plan never saw the approval's "Next:"
+    // line; without this stage it was sent straight into the concepts refusal.
+    name = "content draft";
+    next = `write ${plan.CONTENT_DRAFT} in plan.md (slide${owed.length === 1 ? "" : "s"} ${owed.join(", ")}; no new sign-off needed), then \`slidemind concepts ${slug}\``;
   } else if (planExists && concepts === 0 && authored.size === 0) {
     name = "concepts";
-    next = `\`slidemind concepts ${slug}\`, then Read every concepts/concept-slide-NN.png and fill asset-plan.md`;
-  } else if (assets && (assets.unfilled > 0 || assets.iconsResolved < assets.icons) && missing.length > 0) {
-    name = "sourcing";
-    next = assets.unfilled > 0
-      ? `fill the regions/organisms/connectors/icons rows in ${slug}/asset-plan.md from the concept PNGs (${assets.unfilled} slide section${assets.unfilled === 1 ? "" : "s"} still empty)`
-      : `search + download the ${assets.icons - assets.iconsResolved} unresolved icon row${assets.icons - assets.iconsResolved === 1 ? "" : "s"} in ${slug}/asset-plan.md (\`slidemind search\` → \`download-result\`), append each file to its row`;
+    next = `\`slidemind concepts ${slug}\`, then \`slidemind transcribe ${slug}\` and compare concept/draft pairs`;
   } else if (missing.length > 0) {
     name = "authoring";
-    next = `Read concepts/concept-slide-${String(missing[0]).padStart(2, "0")}.png (batches of ≤3), then write slides/${missing.map((n) => `${String(n).padStart(2, "0")}-*.jsx`).join(", ")}; then \`slidemind view-draft ${slug}\``;
-  } else if (!draftFresh || standing > 0 || selfCheck !== "ok") {
+    next = `\`slidemind transcribe ${slug}\`, complete frame or missing-spec slides from the plan, then \`slidemind view-draft ${slug}\` and compare concept/draft pairs`;
+  } else if (!draftFresh || standing > 0) {
     name = "draft check";
     next = !draftFresh
       ? `\`slidemind view-draft ${slug}\` (slides changed since the last check${record ? "" : ", or never checked"})`
-      : standing > 0
-        ? `fix the ${standing} measured defect${standing === 1 ? "" : "s"} in the JSX, then \`slidemind view-draft ${slug}\``
-        : `tick every organism under \`draft-check:\` in ${slug}/asset-plan.md (concept vs .draft-preview pair), then \`slidemind review ${slug}\``;
+      : `fix the ${standing} measured defect${standing === 1 ? "" : "s"} in the JSX, then \`slidemind view-draft ${slug}\``;
   } else if (!reviewCurrent) {
     name = "review";
     next = reviewState.decision === "comments"
-      ? `edit the files cited in ${slug}/review.json, \`slidemind view-draft ${slug}\`, then \`slidemind review ${slug}\``
+      ? `edit the files cited in ${slug}/.slidemind/state/review.json, \`slidemind view-draft ${slug}\`, then \`slidemind review ${slug}\``
       : `\`slidemind review ${slug}\` (wait for DECISION: approved)`;
   } else {
     name = "deliver";
-    next = `\`slidemind push ${slug}\` (into PowerPoint) or \`slidemind build-pptx ${slug}\` (to a file) — whichever target was agreed at intake; then stop`;
+    // A deck bound to a SharePoint item has ONE delivery: the file it came from.
+    // Naming push/build-pptx there would send the agent to produce a local .pptx
+    // nobody is waiting for while the colleague's copy stays untouched.
+    next = remote
+      ? `\`slidemind build-pptx ${slug}\` — it publishes too: pulls, reconciles and replaces ${remote.name ?? "the bound file"} only if nobody saved meanwhile; then stop`
+      : folder
+        ? `\`slidemind build-pptx ${slug}\` — it publishes too: ${intoFolder}; then stop`
+        : `\`slidemind push ${slug}\` (into PowerPoint) or \`slidemind build-pptx ${slug}\` (to a file) — whichever target was agreed at intake; then stop`;
+  }
+
+  // The human answered in the workspace: whatever the stage, the next step is the
+  // command that receives their answer (the one their pasted message names). A
+  // question still open keeps its stage: the agent's turn ends with its SAY line.
+  const gate = workspaceGate(deckDir);
+  if (gate?.state === "answered") {
+    const what = gate.action === "approve" ? "approved" : "sent comments";
+    const receive = receiveCommand({ kind: gate.kind, adapterId: gate.adapterId, deckPath: deckRoot(deckDir), taskId: gate.taskId });
+    next = `\`${receive}\` — the user ${what} on the ${gate.kind === "plan-approval" ? "plan" : "preview"} in the workspace; it prints their answer`;
+  } else if (gate?.state === "asked" && ((gate.kind === "plan-approval" && name === "plan gate") || (gate.kind === "preview-review" && name === "review"))) {
+    next = `your question is waiting for the user in the workspace — \`slidemind ${GATE_COMMAND[gate.kind]} ${slug}\` prints its link and SAY line again; end your turn with that line, do not wait`;
   }
 
   return {
     name,
     next,
+    ...(gate ? { gate } : {}),
     plan: { exists: planExists, approved: planApproved, decision: planState.decision ?? null, planned: planned.length },
     concepts,
-    assets,
     slides: { jsx: jsx.length, native: native.length, missing },
-    draftCheck: { ran: Boolean(record), fresh: draftFresh, standingDefects: standing, selfCheck },
-    review: { decision: reviewState.decision ?? null, current: reviewCurrent },
+    draftCheck: { ran: Boolean(record), fresh: draftFresh, standingDefects: standing },
+    // current: delivery may proceed; approved: a human actually approved (an
+    // adopted deck is current without ever being approved — it needs no review)
+    review: { decision: reviewState.decision ?? null, current: reviewCurrent, approved: Boolean(reviewState.approval) },
+    route: editRoute ? "edit" : "author",
+    // The accepted base, what has changed against it, the candidate a build
+    // proposed and anything staged or conflicted — the whole local revision
+    // picture, in the one payload an agent already reads after a summarization.
+    revision,
+    // The remote half, read from disk. Null for a deck that publishes nowhere.
+    // No network call: `ready` must not become a SharePoint round trip, so this
+    // reports the last SUCCESSFUL observation and when it happened rather than
+    // claiming the deck is current.
+    ...(remote ? { remote } : {}),
   };
 }
 
 export function stageHumanLines(stage) {
-  const a = stage.assets;
   const parts = [
     `plan: ${!stage.plan.exists ? "none" : stage.plan.approved ? "approved" : stage.plan.decision ?? "not gated"}`,
     `concepts: ${stage.concepts}/${stage.plan.planned}`,
-    a
-      ? `asset plan: ${a.unfilled > 0 ? `${a.unfilled} section${a.unfilled === 1 ? "" : "s"} empty` : `${a.iconsResolved}/${a.icons} icon rows resolved`}`
-      : "asset plan: none",
     `slides: ${stage.slides.jsx + stage.slides.native}/${stage.plan.planned}${stage.slides.native ? ` (${stage.slides.native} native)` : ""}`,
-    `draft check: ${!stage.draftCheck.ran ? "not run" : !stage.draftCheck.fresh ? "stale" : stage.draftCheck.standingDefects > 0 ? `${stage.draftCheck.standingDefects} defect${stage.draftCheck.standingDefects === 1 ? "" : "s"} standing` : stage.draftCheck.selfCheck === "ok" ? "clean" : "self-check incomplete"}`,
-    `review: ${stage.review.decision ? `${stage.review.decision}${stage.review.current ? "" : " (stale)"}` : "none"}`,
+    `draft check: ${!stage.draftCheck.ran ? "not run" : !stage.draftCheck.fresh ? "stale" : stage.draftCheck.standingDefects > 0 ? `${stage.draftCheck.standingDefects} defect${stage.draftCheck.standingDefects === 1 ? "" : "s"} standing` : "clean"}`,
+    `review: ${stage.review.approved ? "approved" : stage.review.current ? "not needed" : stage.review.decision ?? "none"}`,
   ];
-  return `  stage: ${stage.name} — ${parts.join(" · ")}\n  next: ${stage.next}\n`;
+  // An adopted deck's plan/concepts lines say nothing — it has none.
+  // What matters there is what changed since the file it was adopted from.
+  const r = stage.revision;
+  const lines = stage.route === "edit"
+    ? [
+        `base: ${r.base ? `${r.base.sha256.slice(0, 8)} (${r.base.slideCount} slides, gen ${r.generation})` : "none"}`,
+        `local: ${r.localDirty ? `${r.dirtySlides.length} slide(s) changed` : "clean"}${r.designMoved ? " · design moved (build-pptx --refresh-design)" : ""}`,
+        `slides: ${stage.slides.jsx} jsx${stage.slides.native ? ` + ${stage.slides.native} native` : ""}`,
+        `candidate: ${r.candidate ? `${r.candidate.candidateId}${r.candidate.stale ? " (stale)" : ""}` : "none"}`,
+        `review: ${stage.review.approved ? "approved" : stage.review.current ? "not needed" : stage.review.decision ?? "none"}`,
+        ...(r.staged.length ? [`staged: ${r.staged.length}`] : []),
+        ...(r.conflicts ? [`conflicts: ${r.conflicts}`] : []),
+      ]
+    : parts;
+  const remote = stage.remote ? `  ${remoteHumanLine(stage.remote).trimStart()}` : "";
+  return `  stage: ${stage.name} — ${lines.join(" · ")}\n${remote}  next: ${stage.next}\n`;
 }