slidemind 0.3.20 → 0.4.1

package/src/workspace/edit.mjs

@@ -0,0 +1,167 @@
+// Edit generations for the persistent workspace: one local save, under the
+// deck's operation, that knows what the editor started from.
+//
+// Every editor submits `base` — the hash and value it loaded — and what it
+// wants now. Under the lock the CURRENT plan is re-read (through the installed
+// adapter, or plan.md for a generic deck), so a write another tool made in the
+// meantime is noticed rather than overwritten: if it differs from the last
+// accepted snapshot (`state/workspace-edit.json`) the raw value is backed up
+// in the operation record before anything is accepted. A stale base is merged
+// three ways with the shared policy (merge-json.mjs); a same-field clash
+// returns `local_conflict` with every input and writes nothing.
+//
+// The commit itself is the adapter's `save-local` (the pack applies its own
+// amendment/validation rules) or a plain plan.md write. What the adapter
+// refuses is refused here — the snapshot is not advanced and nothing is left
+// for the sync queue to pick up. Network is not this module's business.
+
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { Merge3Error, merge3 } from "../lib/merge-json.mjs";
+import { dispatchAdapter } from "./adapters.mjs";
+import { runDeckOperation } from "./operations.mjs";
+
+export const EDIT_FILE = "workspace-edit.json";
+export const SCHEMA_VERSION = 1;
+export const GENERIC_ADAPTER = "core";
+
+export function editPath(workspaceDir) {
+  return path.join(workspaceDir, "state", EDIT_FILE);
+}
+
+/** The last accepted editor snapshot: `{ adapterId, hash, value, updatedAt }`, `{ malformed, raw }` (kept on disk), or null. */
+export function readAcceptedEdit(workspaceDir) {
+  let raw;
+  try {
+    raw = fs.readFileSync(editPath(workspaceDir), "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return null;
+    throw err;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed?.schemaVersion === SCHEMA_VERSION && typeof parsed.hash === "string") return parsed;
+  } catch {
+    /* fall through */
+  }
+  return { malformed: true, raw };
+}
+
+function writeAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+  fs.renameSync(tmp, file);
+}
+
+/** A generic plan is the whole plan.md string, hashed as UTF-8 bytes (contracts §7). */
+export const markdownHash = (text) => `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`;
+
+const refusal = (code, message, extra = {}) => ({ ok: false, code, message, ...extra });
+const deckRootOf = (workspaceDir) => (path.basename(workspaceDir) === ".slidemind" ? path.dirname(workspaceDir) : workspaceDir);
+
+// The two ways to read and commit a plan. `adapter` is `{ id, entry }` from
+// resolveWorkspaceAdapter, or null for a generic plan.md deck.
+function editor(workspaceDir, adapter, operationId) {
+  if (adapter?.entry) {
+    const deckRoot = deckRootOf(workspaceDir);
+    const call = (method, payload, ownerToken) => dispatchAdapter(adapter.entry, { method, deckRoot, payload, operationId, ownerToken });
+    return {
+      id: adapter.id,
+      async read(token) {
+        const answer = await call("read", {}, token);
+        if (answer.status !== "ok") return { refused: refusal(answer.error.code, answer.error.message, { details: answer.data ?? undefined }) };
+        return { value: answer.data.value, hash: answer.data.hash };
+      },
+      async commit(current, value, token) {
+        const answer = await call("save-local", { base: current, value }, token);
+        if (answer.status !== "ok") return { refused: refusal(answer.error.code, answer.error.message, { details: answer.data ?? undefined }) };
+        return { value: answer.data.value, hash: answer.data.hash };
+      },
+    };
+  }
+  const file = path.join(workspaceDir, "plan.md");
+  return {
+    id: GENERIC_ADAPTER,
+    async read() {
+      let text;
+      try {
+        text = fs.readFileSync(file, "utf8");
+      } catch (err) {
+        if (err?.code !== "ENOENT") throw err;
+        return { refused: refusal("no_plan", `no plan.md in ${workspaceDir}`) };
+      }
+      return { value: text, hash: markdownHash(text) };
+    },
+    async commit(_current, value) {
+      if (typeof value !== "string") return { refused: refusal("validation_failed", "a generic plan is the plan.md text") };
+      const tmp = `${file}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+      fs.writeFileSync(tmp, value, "utf8");
+      fs.renameSync(tmp, file);
+      return { value, hash: markdownHash(value) };
+    },
+  };
+}
+
+/**
+ * Save an editor's value locally.
+ *
+ * `{ ok: true, value, hash, savedLocally: true, rawBackup? }` on commit —
+ * `rawBackup` is the plan as found on disk when it was not the last accepted
+ * snapshot (an agent's direct edit), also noted in the operation record.
+ * `{ ok: false, code: "local_conflict", current, base, mine, merged, conflicts,
+ * hash }` when the stale base cannot be merged; nothing written. Any other
+ * `{ ok: false, code }` is the adapter's refusal (`validation_failed`, …) or a
+ * bad request — the snapshot is not advanced. Lock and recovery failures throw
+ * as runDeckOperation does (`deck_busy`, `recovery_required`).
+ *
+ * `owner` is runDeckOperation's: the daemon passes `false`.
+ */
+export function savePlanLocal({ workspaceDir, adapter = null, operationId = randomUUID(), base, value, owner }) {
+  if (!base || typeof base.hash !== "string") return Promise.resolve(refusal("validation_failed", "base.hash is required: the version the editor loaded"));
+  const ed = editor(workspaceDir, adapter, operationId);
+  return runDeckOperation(workspaceDir, { operationId, kind: "save-local", expected: { base: base.hash }, owner }, async (op) => {
+    const current = await ed.read(op.token);
+    if (current.refused) return current.refused;
+
+    const accepted = readAcceptedEdit(workspaceDir);
+    let rawBackup;
+    if (accepted && !accepted.malformed && accepted.hash !== current.hash) {
+      rawBackup = { hash: current.hash, value: current.value };
+      op.note({ rawBackup });
+    }
+
+    let mine = value;
+    if (base.hash !== current.hash) {
+      if (base.value === undefined) return refusal("validation_failed", "base.value is required when the record moved since it was loaded");
+      let out;
+      try {
+        out = merge3(base.value, current.value, value);
+      } catch (err) {
+        if (err instanceof Merge3Error) return refusal("validation_failed", err.message, { path: err.path });
+        throw err;
+      }
+      if (out.conflicts.length) {
+        return { ok: false, code: "local_conflict", current: current.value, base: base.value, mine: value, merged: out.merged, conflicts: out.conflicts, hash: current.hash };
+      }
+      mine = out.merged;
+    }
+
+    op.note({ before: current.hash });
+    const committed = await ed.commit({ hash: current.hash, value: current.value }, mine, op.token);
+    if (committed.refused) return committed.refused;
+    op.note({ after: committed.hash });
+    writeAtomic(editPath(workspaceDir), {
+      schemaVersion: SCHEMA_VERSION,
+      adapterId: ed.id,
+      hash: committed.hash,
+      value: committed.value,
+      updatedAt: new Date().toISOString(),
+    });
+    // Accepted and adapter-owned: the sync queue picks it up (generic plan.md is never sent — contracts §7).
+    if (adapter?.entry || adapter?.read) (await import("./sync.mjs")).scheduleSync(workspaceDir, { hash: committed.hash });
+    return { ok: true, value: committed.value, hash: committed.hash, previous: current.hash, savedLocally: true, ...(rawBackup ? { rawBackup } : {}) };
+  });
+}

package/src/workspace/events.mjs

@@ -0,0 +1,52 @@
+// Advisory invalidations over SSE. `{ type, deckId?, taskId?, generation }`
+// says "re-GET this"; it never carries state, and nothing is replayed on
+// reconnect — a client that reconnects fetches fresh state, so a lost event
+// costs one refresh, never correctness. Heartbeat comment every 25s keeps
+// proxies and browsers from closing an idle stream.
+
+export const HEARTBEAT_MS = 25_000;
+
+export function createEvents() {
+  const clients = new Set();
+  let generation = 0;
+  return {
+    get generation() {
+      return generation;
+    },
+    get clientCount() {
+      return clients.size;
+    },
+    invalidate(event) {
+      generation += 1;
+      const line = `data: ${JSON.stringify({ ...event, generation })}\n\n`;
+      for (const res of clients) res.write(line);
+      return generation;
+    },
+    subscribe(req, res) {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-store",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no",
+      });
+      res.write(`: connected ${generation}\n\n`);
+      clients.add(res);
+      const beat = setInterval(() => res.write(": ping\n\n"), HEARTBEAT_MS);
+      beat.unref();
+      const drop = () => {
+        clearInterval(beat);
+        clients.delete(res);
+      };
+      req.on("close", drop);
+      res.on("close", drop);
+    },
+    close() {
+      for (const res of clients) res.end();
+      clients.clear();
+    },
+  };
+}
+
+/** The daemon's one bus; modules that commit something call `invalidate`. */
+export const events = createEvents();
+export const invalidate = (event) => events.invalidate(event);

package/src/workspace/gate-client.mjs

@@ -0,0 +1,290 @@
+// The agent's side of a gate when the human answers in the workspace.
+//
+// `slidemind plan <deck>` and `slidemind review <deck>` are the ONLY gate
+// commands an agent runs. They ask through the workspace and keep the
+// standalone contract's `DECISION: approved | comments | pending` stdout, from
+// the same formatters. One run:
+//
+//   1. hands over an answer the human already gave and the agent has not
+//      received (`pickedUpAt` is the receipt) — this is the receive command the
+//      user's pasted message names;
+//   2. else answers "approved" at once when the content is already approved;
+//   3. else asks (a deduped task bound to the exact content), tells an open
+//      page, prints ASK + SAY and returns `DECISION: pending` AT ONCE. It never
+//      waits: nothing can reach an agent whose turn has ended, so the agent ends
+//      its turn with the SAY line and the user's pasted message brings it back
+//      (doc 21 → *Tasks and agent continuation*, handback.mjs).
+//
+// A workspace that cannot be used is a blocker the agent reports, never a
+// standalone page on another port: that second page was the second link this
+// protocol removed. Nothing here opens a browser.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { deckRoot as rootOf, deckSlug, planPageOwner, resolveWorkspace } from "../lib/deck-paths.mjs";
+import { daemonRequest, ensureRunning, readDescriptor, registerDeck } from "./lifecycle.mjs";
+import { markdownHash, readAcceptedEdit } from "./edit.mjs";
+import { askLines, viewOf } from "./handback.mjs";
+import { deriveTaskSubject } from "./task-actions.mjs";
+import { getTask, listTasks, markPickedUp, requestTask } from "./tasks.mjs";
+
+const NOUN = { "plan-approval": "plan", "preview-review": "preview" };
+
+/**
+ * Does this gate ask through the workspace? Always — `slidemind setup` keeps one
+ * running — except where nobody is there to answer (auto-approving headless
+ * runs) or the user rolled back to the standalone gates (SLIDEMIND_WORKSPACE=0).
+ * A plan an extension owns keeps its own review flow (`tasks request`).
+ */
+export function gateUsesWorkspace(deckDir, kind) {
+  if (process.env.SLIDEMIND_GATE_AUTOAPPROVE === "1") return false;
+  if (process.env.SLIDEMIND_WORKSPACE === "0") return false;
+  if (kind === "plan-approval" && planPageOwner(resolveWorkspace(deckDir)).owner !== "core") return false;
+  return true;
+}
+
+const SANDBOX_CODES = new Set(["EPERM", "EACCES", "EROFS"]);
+
+/**
+ * Why a question could not be asked, in the words the agent passes on or acts
+ * on. Every one is a blocker (exit 2), never a fallback page.
+ */
+export function askBlocker(err, deckRoot) {
+  if (err?.code === "workspace_sandboxed") {
+    return {
+      code: "workspace_sandboxed",
+      message:
+        "this sandboxed session cannot reach or start the slidemind workspace. " +
+        "Run this same command again outside the sandbox (in Codex: with escalated permissions) — it starts the workspace if needed and asks.",
+    };
+  }
+  if (SANDBOX_CODES.has(err?.code)) {
+    return {
+      code: "deck_not_writable",
+      message:
+        `this session may not write into ${deckRoot} (${err.code}). Decks belong in ./decks of your working folder; ` +
+        "if the user chose this folder on purpose, run this same command again outside the sandbox.",
+    };
+  }
+  return { code: err?.code ?? "workspace_unavailable", message: `the slidemind workspace could not be used: ${err?.message ?? err}` };
+}
+
+/**
+ * A re-run of the review gate while its question about THIS build is still
+ * open — the agent waiting in a loop — needs no rebuild: the preview the user
+ * is looking at was built from exactly these slides (the task's subject is
+ * their hash) and nothing under slides/ or assets/ is newer than it.
+ */
+export async function openPreviewQuestionIsCurrent(deckDir) {
+  const ws = resolveWorkspace(deckDir);
+  let tasks;
+  try {
+    tasks = listTasks(rootOf(ws)).filter((t) => t.kind === "preview-review" && t.status === "pending");
+  } catch {
+    return false;
+  }
+  if (!tasks.length) return false;
+  const { previewHash } = await import("../builders/review.mjs");
+  const { previewPath } = await import("../lib/deck-paths.mjs");
+  let hash;
+  let builtAt;
+  try {
+    hash = previewHash(ws);
+    builtAt = fs.statSync(previewPath(ws, "presentation.html")).mtimeMs;
+  } catch {
+    return false;
+  }
+  if (!tasks.some((t) => t.subject?.hash === hash)) return false;
+  // the build's own stamp says what it was built from (renames and deletes included)
+  const { previewBuiltFrom } = await import("../builders/build.mjs");
+  const builtFrom = previewBuiltFrom(ws);
+  if (builtFrom) return builtFrom === hash;
+  const newer = (dir) => {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return false;
+    }
+    return entries.some((e) => (e.isDirectory() ? newer(path.join(dir, e.name)) : e.isFile() && fs.statSync(path.join(dir, e.name)).mtimeMs > builtAt));
+  };
+  return !newer(path.join(ws, "slides")) && !newer(path.join(ws, "assets"));
+}
+
+/**
+ * Is plan.md, as it stands, the version the user last saved in the workspace's
+ * editor? Then the plan the agent gets back is the user's edit, not its own
+ * draft — even when no question was open while they edited — and it must be
+ * re-read before authoring.
+ */
+export function planLastSavedInPage(deckDir) {
+  const ws = resolveWorkspace(deckDir);
+  try {
+    const accepted = readAcceptedEdit(ws);
+    if (!accepted || accepted.malformed) return false;
+    return accepted.hash === markdownHash(fs.readFileSync(path.join(ws, "plan.md"), "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * An answer on the preview the agent has not received, which this run will hand
+ * over as it is (comments, or an approval of these very slides): nothing needs
+ * rebuilding first — a build that fails now must not keep the user's answer from
+ * the agent. An approval of slides that changed since is not handed over (the
+ * run asks about the new ones), so it still builds.
+ */
+export async function previewAnswerWaiting(deckDir) {
+  const ws = resolveWorkspace(deckDir);
+  let answer;
+  try {
+    answer = unreceived(listTasks(rootOf(ws)).filter((t) => t.kind === "preview-review"));
+  } catch {
+    return false;
+  }
+  if (!answer) return false;
+  if (answer.response?.action !== "approve") return true;
+  try {
+    const { previewHash } = await import("../builders/review.mjs");
+    const now = previewHash(ws);
+    return answer.subject?.hash === now || answer.evidence?.hash === now;
+  } catch {
+    return false;
+  }
+}
+
+const ago = (iso) => {
+  const s = Math.max(0, Math.round((Date.now() - Date.parse(iso)) / 1000));
+  return s < 90 ? `${s}s` : `${Math.round(s / 60)} min`;
+};
+
+/** A workspace route through the one CLI→daemon helper; an HTTP error throws with its code and status. */
+async function daemonFetch(p, opts = {}) {
+  const { status, body } = await daemonRequest(p, opts);
+  if (status < 200 || status >= 300 || !body?.ok) {
+    throw Object.assign(new Error(body?.error?.message ?? `workspace answered HTTP ${status}`), { code: body?.error?.code ?? "workspace_error", status });
+  }
+  return body;
+}
+
+/**
+ * The signed-in link to the view a question is answered in (valid every time it
+ * is clicked, in any browser — Codex's own pane included), or the plain page
+ * when the workspace does not hand out its key.
+ */
+async function askLink(deckId, kind) {
+  const d = readDescriptor();
+  const plain = `${d.url}/deck/${deckId}/${viewOf(kind)}`;
+  try {
+    const { token } = await daemonFetch("/bootstrap", { method: "POST" });
+    return { link: `${plain}#bootstrap=${token}`, plain };
+  } catch {
+    return { link: plain, plain };
+  }
+}
+
+/** The newest answer of this kind the agent has not received yet (older unreceived ones are history). */
+function unreceived(tasks) {
+  const answered = tasks.filter((t) => t.status === "completed");
+  return answered[0] && !answered[0].pickedUpAt ? answered[0] : null;
+}
+
+/**
+ * Run one gate through the workspace. Resolves
+ *   { blocked: { code, message } }               the question could not be asked — report it
+ *   { refused }                                  `refuseOpen` turned a new question down (already printed)
+ *   { decision: "approve"|"comments"|"pending", task }
+ *
+ * `format(task, { note })` prints the decision exactly as the standalone gate
+ * would (the caller owns the wording: plan.mjs / review.mjs); `approvedNow()`
+ * says whether the current content is already approved; `refuseOpen()`, when
+ * given, returns a refusal for asking about the content as it stands, or null.
+ */
+export async function runWorkspaceGate({ deckDir, kind, format, approvedNow, refuseOpen = null, out = process.stdout }) {
+  const ws = resolveWorkspace(deckDir);
+  const root = rootOf(ws);
+  const ofKind = () => listTasks(root).filter((t) => t.kind === kind);
+
+  // 1. The answer the user's pasted message came for (or one given while no agent ran).
+  const handOver = async (task, note = null) => {
+    // Print FIRST, then record the receipt: a run killed in between shows the
+    // answer again next time (harmless), never loses it.
+    const done = getTask(root, task.id) ?? task;
+    format(done, { note });
+    // The receipt tells the page "your agent picked it up" and keeps a seen
+    // comments round from coming back. Older unreceived answers are history: received too.
+    let failed = null;
+    for (const t of ofKind().filter((x) => x.status === "completed" && !x.pickedUpAt)) {
+      for (let attempt = 0; ; attempt++) {
+        try {
+          await markPickedUp(root, t.id);
+          break;
+        } catch (e) {
+          if (e?.code === "deck_busy" && attempt < 5) {
+            await new Promise((r) => setTimeout(r, 300));
+            continue;
+          }
+          failed = e;
+          break;
+        }
+      }
+    }
+    if (failed) {
+      out.write(
+        failed.code === "deck_busy" && !process.env.SLIDEMIND_OWNER
+          ? "NOTE: the deck is held by your edit session, so this answer could not be marked as received and the next run will show it again. Run slidemind commands with SLIDEMIND_OWNER exported (the token `revision begin` printed).\n"
+          : `NOTE: this answer could not be marked as received (${failed.message}); the next run may show it again — act on it once.\n`,
+      );
+    }
+    return { decision: done.response?.action === "approve" ? "approve" : "comments", task: done };
+  };
+
+  const { subject, adapterId } = await deriveTaskSubject({ deckRoot: root, adapter: null, kind });
+  const waiting = unreceived(ofKind());
+  if (waiting) {
+    const sameContent = waiting.subject?.hash === subject.hash || waiting.evidence?.hash === subject.hash;
+    if (sameContent || waiting.response?.action !== "approve") {
+      return handOver(waiting, sameContent ? null : `The user answered on an earlier version of the ${NOUN[kind]} (${ago(waiting.response.at)} ago); you changed it since.`);
+    }
+    // an approval of a version that no longer exists covers nothing: note it and ask about what is there now
+    try {
+      await markPickedUp(root, waiting.id);
+    } catch {
+      // the note below still stands
+    }
+    out.write(`NOTE: the user approved an earlier version of the ${NOUN[kind]}; you changed it since, so this asks about the current one.\n`);
+  }
+
+  // 2. Already approved, unchanged since: nothing to ask.
+  if (approvedNow()) {
+    format({ kind, status: "completed", response: { action: "approve" }, subject }, { note: "Already approved — this exact version was signed off earlier; nothing was asked again." });
+    return { decision: "approve", task: null };
+  }
+
+  // 3. Ask, and return. Steps 1 and 2 read the deck's own task store and need no
+  // workspace — an answer the user already gave reaches the agent even where the
+  // workspace cannot run. Asking needs the one the user answers in. Only a NEW
+  // question is checked (`refuseOpen`): an answer above is handed over as given.
+  const refused = refuseOpen?.() ?? null;
+  if (refused) {
+    out.write(refused);
+    return { refused };
+  }
+  let entry;
+  let task;
+  try {
+    await ensureRunning();
+    entry = await registerDeck(root);
+    // deduped: the same content asked twice is one question
+    task = (await requestTask(root, { kind, adapterId, subject })).task;
+  } catch (err) {
+    return { blocked: askBlocker(err, root) };
+  }
+  const { link } = await askLink(entry.id, kind);
+  // an open page shows the question at once; nothing opens a browser
+  await daemonFetch(`/decks/${entry.id}/attention`, { method: "POST", body: { kind, taskId: task.id } }).catch(() => {});
+  out.write(askLines(kind, link));
+  return { decision: "pending", task };
+}

package/src/workspace/handback.mjs

@@ -0,0 +1,73 @@
+// The words of the hand-back (doc 21 → *Tasks and agent continuation*). Nothing
+// reaches an agent whose turn has ended, so every question has one shape:
+//
+//   the agent's command prints ASK + SAY and returns  →  the agent ends its turn
+//   with the SAY line  →  the user decides in the workspace, and the click copies
+//   the message below  →  the user pastes it  →  the agent runs the receive
+//   command the message names.
+//
+// One module owns every one of those words, so the CLI (gate-client, `tasks
+// request`, `ready`) and the page (the ack the routes return) never drift.
+
+/** The deck view a question is answered in — what its link opens. */
+export const VIEW_OF_KIND = {
+  "plan-approval": "plan",
+  "plan-edit": "plan",
+  "sync-conflict": "plan",
+  "preview-review": "preview",
+};
+export const viewOf = (kind) => VIEW_OF_KIND[kind] ?? "plan";
+
+const CORE_GATE = { "plan-approval": "plan", "preview-review": "review" };
+
+/** Is this task answered through the CLI's own gate (a core deck), not a pack's task flow? */
+export const isCoreGate = (task) => Boolean(CORE_GATE[task?.kind]) && (!task?.adapterId || task.adapterId === "core");
+
+/**
+ * The one command that receives an answer: the gate for a core deck (it prints
+ * the decision and writes the receipt), `tasks get` for everything else.
+ */
+export function receiveCommand({ kind, adapterId = null, deckPath, taskId = null }) {
+  if (isCoreGate({ kind, adapterId })) return `slidemind ${CORE_GATE[kind]} ${JSON.stringify(deckPath)}`;
+  return `slidemind tasks get ${JSON.stringify(deckPath)} ${taskId}`;
+}
+
+const SUBJECT = {
+  "plan-approval": "Your plan is ready for review",
+  "plan-edit": "Your plan is ready for your edits",
+  "preview-review": "Your slides are ready for review",
+  "sync-conflict": "Your shared plan needs a decision",
+};
+
+/** The agent's closing line, word for word: the link and what happens after the user is done. */
+export function sayLine(kind, link) {
+  return `${SUBJECT[kind] ?? "A question is waiting for you"} in the slidemind workspace: ${link} — when you're done there, the page gives you a message to paste back here.`;
+}
+
+/** What the asking command prints after the question is recorded. */
+export function askLines(kind, link) {
+  return (
+    `ASK: ${link}\n` +
+    `SAY: ${sayLine(kind, link)}\n` +
+    "DECISION: pending\n" +
+    "Asked. End your turn now with the SAY line, word for word. Do not wait, poll or run this again: " +
+    "the user answers in the workspace and pastes back a message that tells you how to receive the answer.\n"
+  );
+}
+
+const NOUN = { "plan-approval": "Plan", "plan-edit": "Plan", "sync-conflict": "Shared plan", "preview-review": "Slides" };
+
+/**
+ * The message the page copies after the user decided — one line, complete on
+ * its own (what was decided + the command that receives it), so it works in the
+ * same chat, after a summarization and in a new chat. `action` is the task
+ * action the user took (approve / request-changes / comment / done / resolve).
+ */
+export function pasteMessage({ kind, action, receive }) {
+  const noun = NOUN[kind] ?? "Deck";
+  const run = `\`${receive}\``;
+  if (action === "approve") return `${noun} approved. Continue: ${run}`;
+  if (action === "done") return `${noun} edits done. Continue: ${run}`;
+  if (action === "resolve") return `${noun} conflict resolved. Continue: ${run}`;
+  return `Changes requested on the ${noun.toLowerCase()}. Read them: ${run}`;
+}