create-pmos 0.196.0 → 0.198.0

package/workspace/lib/report-draft.js

@@ -5,7 +5,8 @@
  *
  *   draftOf(root, { cadence, slot, now, health })  → the fixtures/report-api/draft.json shape | { ok: false, status, error }
  *   render(draft, { notes })                       → markdown; each block carries its note markers (below)
- *   writeDraft(root, draft, { actor, notes })      → { ok: true, path, sha } | { ok: false, status, error }
+ *   writeDraft(root, draft, { actor, notes, fresh, quiet }) → { ok: true, path, sha } | { ok: false, status, error }
+ *   onDraftWritten(fn)                             → unsubscribe; fn({ root, cadence, slot, path }) after each write that is not `quiet` (a note save)
  *   readNotes(markdown)                            → { [initiativeId]: text }   (frozen here, not a stub)
  *   noteBlock(id, text)                            → the marker pair with the text between (frozen here)
  *
@@ -583,7 +584,10 @@ function render(draft, { notes } = {}) {
  * passes none still keeps them. `fresh: true` (`pmos report draft` without --redraft) refuses a slot that has a draft
  * already (409), from local state only (X18). An issued slot is frozen: 409.
  */
-function writeDraft(root, draft, { actor, notes, fresh } = {}) {
+const written = new Set();   // report-design-studio: listeners told after a draft is written (the cycle render hook)
+/** Call fn({ root, cadence, slot, path }) after each draft this process writes (not a note save, which passes `quiet`). → an unsubscribe function */
+function onDraftWritten(fn) { if (typeof fn === 'function') written.add(fn); return () => written.delete(fn); }
+function writeDraft(root, draft, { actor, notes, fresh, quiet } = {}) {
   if (!draft || draft.ok === false) return draft && draft.status ? draft : refuse(400, 'there is no draft to write');
   if (!actorLib.valid(actor)) return refuse(403, 'a draft is written by an actor from the call path; nothing was written');
   if (!isStr(draft.cadence) || !CADENCE_RE.test(draft.cadence) || !isDate(draft.slot)) return refuse(400, 'the draft has no valid cadence and slot');
@@ -617,10 +621,11 @@ function writeDraft(root, draft, { actor, notes, fresh } = {}) {
     try { fs.unlinkSync(tmp); } catch { /* not made */ }
     return refuse(500, 'could not write the draft; nothing was written: ' + String((e && e.message) || e).slice(0, 160));
   }
+  if (!quiet) for (const fn of written) { try { fn({ root: abs, cadence: draft.cadence, slot: draft.slot, path: rel }); } catch { /* a listener never fails the write */ } }
   return { ok: true, path: rel, sha: issues.blobSha(Buffer.from(md, 'utf8')) };
 }
 
 module.exports = {
-  draftOf, render, writeDraft, readNotes, noteBlock, NOTE_OPEN, NOTE_CLOSE, NOTE_RE, NOTE_ID_RE,
+  draftOf, render, writeDraft, onDraftWritten, readNotes, noteBlock, NOTE_OPEN, NOTE_CLOSE, NOTE_RE, NOTE_ID_RE,
   readDefinition, stateRel, draftPath, definitionPath, FRAME, HEADLINE_NOTE, ASKS_NOTE, CHANGELOG_NOTE, SLIDES_OPEN,
 };

package/workspace/lib/report-setups.js

@@ -339,7 +339,7 @@ const SECTION_NOTES = Object.freeze({
   needs: 'Needs your call. Asks to the readers in `report.asks`: what, who, by when. Write "None this cycle" when there are none; never drop the section.',
   sources: 'Sources reached and not reached.',
 });
-const OUTPUT_WORDS = Object.freeze({ 'google-slides': 'a Google Slides deck', 'google-doc': 'a Google Doc', 'google-sheets': 'a Google Sheets spreadsheet', confluence: 'a Confluence page', pdf: 'a PDF' });
+const OUTPUT_WORDS = Object.freeze({ 'google-slides': 'a slide deck in PMOS', 'google-doc': 'a Google Doc', 'google-sheets': 'a Google Sheets spreadsheet', confluence: 'a Confluence page', pdf: 'a PDF' });
 
 function scheduleSentence(s, now) {
   const first = firstSlot(s, now);

package/workspace/lib/route-modules.js

@@ -72,6 +72,7 @@ const MODULES = Object.freeze([
   'routes-scan',          // horizon-scan-portfolio: one scan for the workspace: the watch list and setting, Scan now and Stop, report documents and their proposals (approve, change, dismiss, undo), plus the first scan's per-board and Briefing reads (scan.jsonl)
   'routes-report-setups', // report-workspace: recurring reports, the Ask box, the finder, the report documents and their export (report-setups.jsonl)
   'routes-core-docs',     // core-documents: the core documents of each level, Draft it (a core-doc run), Issue it and Drop (core-docs.jsonl)
+  'routes-report-design', // report-design-studio: the design studio (describe, samples, turns, versions, This is it), cycle renders and decisions, speaker notes and pins
 ]);
 const PM_DIR = path.join(__dirname, '..', 'public', 'pm');
 const MODULE_NAME = /^[a-z0-9][a-z0-9-]*\.js$/;

package/workspace/lib/routes-doc-sheet.js

@@ -13,7 +13,8 @@
  *   POST /api/doc-sheet/change-note { path, downstream? }   a draft body only; nothing is sent
  *   GET  /api/doc-sheet/proposals?path=          → { ok, proposals: [{ id, state, prompt, at, hash, after, sections: [{ name, kind, stale }] }] }
  *   GET  /api/doc-sheet/log?path=                → { ok, revisions, events }   the edit log: revisions (with a reason added later) and
- *                                                  the other entries (proposed, rejected, asked, marked current)
+ *                                                  the other entries (proposed, rejected, asked, marked current; a report's pins and design
+ *                                                  decisions from report-notes.jsonl, report-design-studio)
  *   POST /api/doc-sheet/reject { path, id, why }            page press; a why is required; the proposal is closed, the file untouched
  *   POST /api/doc-sheet/why { path, rev, why }              page press; a reason for a revision that has none (an outside change);
  *                                                            appended to annotations.jsonl, the revision itself is not rewritten
@@ -246,6 +247,12 @@ function logRoute(root, q, runtimeDir) {
     else if (a.event === 'failed') events.push({ kind: 'ask-failed', at: a.at, id: a.id, why: a.error, by: 'agent' });
   }
   for (const m of readLines(path.join(dirOf(runtimeDir), 'marks.jsonl'))) if (m && m.path === r.rel) events.push({ kind: 'marked', at: m.at, why: m.why, by: 'pm' });
+  // report-design-studio: pins on a designed report's slides and the decisions on a cycle that differs from its design (lib/routes-report-design.js appends them)
+  for (const n of readLines(path.join(dirOf(runtimeDir), 'report-notes.jsonl'))) {
+    if (!n || n.path !== r.rel) continue;
+    if (n.event === 'pin') events.push({ kind: 'pin', at: n.at, by: n.by === 'agent' ? 'agent' : 'pm', op: n.op, id: n.id, slide: n.slide, text: n.text || '', ...(n.section ? { section: n.section } : {}) });
+    else if (n.event === 'design') events.push({ kind: 'design', at: n.at, by: 'pm', choice: n.choice, diff: n.diff, what: n.what || null });
+  }
   return { status: 200, body: { ok: true, path: r.rel, revisions: revsOut(runtimeDir, r.rel), events } };
 }
 

package/workspace/lib/routes-report-design.js

@@ -0,0 +1,481 @@
+'use strict';
+/* routes-report-design.js — the report design studio's routes, its report-design jobs and the cycle hook (initiative report-design-studio).
+ *
+ *   GET  /api/report-design?ws&id                 → { ok, setup: { id, name, source, output }, design }   (lib/report-design.js designAnswer)
+ *   GET  /api/report-design/version?ws&id&n       → text/html, the sanitized render of D<n>
+ *   POST /api/report-design/describe { ws, id, text, format? }
+ *   POST /api/report-design/sample   { ws, id, name, kind, data } | { ws, id, link, name? } | { ws, id, doc, name? }   → { ok, sample }
+ *   POST /api/report-design/turn     { ws, id, text, points: [{ n, slide, x, y, text }] }   → { ok, running }   ONE job per report; 409 while one runs
+ *   POST /api/report-design/accept   { ws, id, n }   → { ok, design, brief }   "This is it": writes brief.md
+ *   POST /api/report-design/revert   { ws, id, n }   → { ok, design }
+ *   GET  /api/report-design/cycle?ws&path         → { ok, designed, design_version, format, outline, differences, decisions, matches, rendering, previous }
+ *   GET  /api/report-design/cycle-html?ws&path    → text/html, the sanitized cycle render
+ *   POST /api/report-design/cycle-decision { ws, path, diff, choice: keep | adopt | match }   → { ok, cycle }
+ *   GET  /api/report-notes?ws&path                → { ok, speaker, suggestions, pins }
+ *   POST /api/report-notes/speaker { ws, path, slide, text } | { ws, path, slide, keep: true }
+ *   POST /api/report-notes/pin     { ws, path, op, id?, slide, x, y, text, section? }
+ *
+ * WHO WRITES. Every POST passes pm-guard requirePagePress, and a request with an agent session header is refused first (403), as
+ * routes-report-setups.js does. A job's render is data: the server sanitizes it (lib/report-design.js sanitize) before it is written or served.
+ *
+ * THE JOB. A turn, a cycle render and a re-render to match each start ONE headless run (lib/headless.js kind 'report-design', origin
+ * `report-design:<cadence>`), in the report's folder, with the skill skills/report-design.skill and a block that names the files. The run may
+ * write one file, design/pending/<job>.html (argsFor writePaths), and prints a JSON result: { answer, took[], rules, html? }. When it ends the
+ * server reads the pending file (or `html`), sanitizes it and writes D<n> (a turn) or <slot>.design.html/.json (a cycle). A failed, stopped or
+ * timed-out run, or a render with no section, appends an 'error' line with the reason. One job per report at a time; a cycle that is drafted
+ * while a job runs waits in a queue and starts when the job ends.
+ *
+ * THE CYCLE HOOK. attach(ctxFactory) listens to report-draft.js writeDraft: a draft written in this process for a report whose design is saved
+ * starts a `cycle` job (not a note save, and never an issued slot). sweep(ctx), on the server tick, catches a draft another process wrote (the
+ * schedule's `pmos report draft`): a slot written after the design was saved that has no render yet. A slot whose render failed for the same
+ * document text is not tried again until the document changes.
+ *
+ * THE EDIT LOG. Each pin operation and each cycle decision appends a line to <runtime>/doc-sheet/report-notes.jsonl, which the document sheet's
+ * Edit log reads (routes-doc-sheet.js logRoute): { event: 'pin', path, at, by, op, id, slide, text, section? } and
+ * { event: 'design', path, at, by, choice, diff, what }.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const guard = require('./pm-guard.js');
+const D = require('./report-design.js');
+const RS = require('./report-setups.js');
+const RC = require('./report-checks.js');
+const RDraft = require('./report-draft.js');
+const headless = require('./headless.js');
+
+const text = (v) => (typeof v === 'string' ? v : '');
+const bad = (status, error) => ({ status, body: { ok: false, error } });
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const DESIGN_POSTS = ['describe', 'sample', 'turn', 'accept', 'revert', 'cycle-decision'];
+const NOTES_POSTS = ['speaker', 'pin'];
+const HTML_CSP = "default-src 'none'; img-src data:; style-src 'unsafe-inline'; font-src data:";
+
+const jobs = new Map();    // `${root}\0${cadence}` → { id, mode, since, turn, slotPath, sessionId }
+const queue = new Map();   // `${root}\0${cadence}` → [rel, …] cycles waiting for the job to end
+let ctxFactory = null;
+let lastCtx = null;
+const keyOf = (root, cadence) => `${path.resolve(String(root))}\u0000${cadence}`;
+
+function wsOf(ctx, id) {
+  const w = ctx.getWs(id || null);
+  return w && (!id || w.id === id) ? w : null;
+}
+function setupOf(root, id) {
+  let st = null;
+  try { st = RS.stateOf(root); } catch { st = null; }
+  const s = st && st.setups.get(id);
+  if (s && s.status !== 'removed') return { id: s.id, name: s.name, source: s.source, output: s.output };
+  // A report with no setup (the hand-written cadences) can still be designed when its folder has a cycle.
+  try { if (D.currentCycle(root, id)) return { id, name: id, source: 'work', output: null }; } catch { /* not a report id */ }
+  return null;
+}
+function runningOf(root, cadence) {
+  const j = jobs.get(keyOf(root, cadence));
+  return j ? { since: j.since, turn: j.turn } : null;
+}
+
+// ── the job ─────────────────────────────────────────────────────────────────────────────────────────────────
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+function promptFor(skill, { mode, root, cadence, setup, st, turnText, points, cycleRel, pending }) {
+  const p = D.paths(root, cadence);
+  const abs = path.resolve(String(root));
+  const lines = [`- Mode: ${mode}`, `- Report: ${setup.name} (${cadence})`, `- Today: ${new Date().toISOString().slice(0, 10)}`];
+  const cur = st.current != null ? D.versionMeta(root, cadence, st.current) : null;
+  const format = (mode === 'turn' ? st.format : null) || (cur && cur.format) || st.format || 'deck';
+  lines.push(`- Format: ${format === 'doc' ? 'doc (a document of pmos-sec sections)' : 'deck (pmos-slide slides on 1280 x 720)'}`);
+  lines.push(`- Description: ${st.description ? st.description.replace(/\s+/g, ' ') : 'none'}`);
+  const samples = [...st.samples.values()];
+  if (mode === 'turn') {
+    lines.push(samples.length ? '- Samples:' : '- Samples: none');
+    for (const s of samples) {
+      const f = D.sampleReadPath(root, cadence, s);
+      const where = s.kind === 'link' ? `a link: ${s.source} (you have no web tool)` : f ? `read ${f}` : 'its file could not be read';
+      lines.push(`  - ${s.id}${s.took ? '' : ' (NEW)'} "${s.name}", ${s.kind}: ${where}`);
+    }
+    lines.push(`- Turn: ${turnText ? turnText.replace(/\s+/g, ' ') : 'none (make the first version from the description and the samples)'}`);
+    if (points && points.length) {
+      lines.push('- Point markers:');
+      for (const pt of points) lines.push(`  - ${pt.n}. slide ${pt.slide} at x ${pt.x}%, y ${pt.y}%: ${pt.text.replace(/\s+/g, ' ')}`);
+    } else lines.push('- Point markers: none');
+    lines.push(`- Previous version: ${cur ? path.join(p.versions, `D${cur.n}.html`) : 'none (this is the first version)'}`);
+  } else {
+    lines.push(`- Reference version: ${path.join(p.versions, `D${st.saved.version}.html`)}`);
+    lines.push(`- Brief: ${fs.existsSync(p.brief) ? p.brief : 'none'}`);
+  }
+  const doc = cycleRel ? path.join(abs, cycleRel) : null;
+  lines.push(`- Current cycle document: ${doc || 'none'}`);
+  lines.push(`- Output path: ${pending}`);
+  return `${skill}\n\nThis job:\n${lines.join('\n')}\n\nWrite the render to the output path, then print the JSON result. Send nothing.\r`;
+}
+
+/** The JSON object in a run's final message: the message itself, a fenced block, or the outermost braces. */
+function resultJson(t) {
+  const s = String(t || '').trim();
+  const tries = [s];
+  const fence = /```(?:json)?\s*([\s\S]*?)```/i.exec(s);
+  if (fence) tries.push(fence[1].trim());
+  const a = s.indexOf('{'); const b = s.lastIndexOf('}');
+  if (a >= 0 && b > a) tries.push(s.slice(a, b + 1));
+  for (const x of tries) { try { const o = JSON.parse(x); if (isObj(o)) return o; } catch { /* next */ } }
+  return null;
+}
+
+/** Start a job. spec: { mode: turn | cycle | match, turnText, points, cycleRel }. → { ok, running } | { ok: false, status, error } */
+function startJob(ctx, w, cadence, spec) {
+  const root = w.root;
+  const key = keyOf(root, cadence);
+  if (jobs.has(key)) return { ok: false, status: 409, error: 'PMOS is already working on this report. Wait for the answer, then try again.' };
+  if (typeof ctx.spawnSession !== 'function') return { ok: false, status: 409, error: 'this workspace cannot start background runs' };
+  const origin = `report-design:${cadence}`;
+  if (headless.kindFor({ agent: 'claude', origin }) !== 'report-design') return { ok: false, status: 409, error: 'Background runs are switched off here (PMOS_HEADLESS=off), so PMOS cannot make the design.' };
+  const skill = typeof ctx.skillPrompt === 'function' ? ctx.skillPrompt('report-design', w) : null;
+  if (!skill) return { ok: false, status: 500, error: 'the report-design skill is not installed' };
+  const setup = setupOf(root, cadence) || { id: cadence, name: cadence };
+  const st = D.stateOf(root, cadence);
+  if (spec.mode !== 'turn' && !st.saved) return { ok: false, status: 409, error: 'this report has no saved design' };
+  const p = D.paths(root, cadence);
+  const id = crypto.randomBytes(5).toString('hex');
+  const pending = path.join(p.pending, `${id}.html`);
+  try { fs.mkdirSync(p.pending, { recursive: true }); } catch (e) { return { ok: false, status: 500, error: 'could not make the pending folder: ' + String((e && e.code) || e) }; }
+  const cycleRel = spec.cycleRel || (D.currentCycle(root, cadence) || {}).path || null;
+  const slot = spec.cycleRel ? (D.cyclePaths(root, spec.cycleRel) || {}).slot : null;
+  const job = { id, mode: spec.mode, since: new Date().toISOString(), turn: spec.mode === 'turn' ? (spec.turnText || 'First version') : `Rendering the ${slot} cycle${spec.mode === 'match' ? ' to match the design' : ''}`,
+    slotPath: spec.mode === 'turn' ? null : spec.cycleRel, sha: spec.cycleRel ? D.docSha(path.join(path.resolve(root), spec.cycleRel)) : null, pending, sessionId: null };
+  jobs.set(key, job);
+  let s = null;
+  try {
+    s = ctx.spawnSession({ name: spec.mode === 'turn' ? 'Report design' : 'Report design · cycle', agent: 'claude', ws: w.id, origin, cwd: p.rel,
+      initialInput: promptFor(skill, { mode: spec.mode, root, cadence, setup, st, turnText: spec.turnText, points: spec.points, cycleRel, pending }),
+      writePaths: [pending], onDone: (r) => finish(ctx, w, cadence, job, r) });
+  } catch (e) { s = { state: 'exited', note: String((e && e.message) || e) }; }
+  if (!s || s.state === 'exited' || s.headless !== 'report-design') {
+    jobs.delete(key);
+    if (s && s.headless !== 'report-design' && s.state !== 'exited' && typeof ctx.stopSession === 'function') { try { ctx.stopSession(s.id); } catch { /* best effort */ } }
+    return { ok: false, status: 409, error: 'PMOS could not start the design run: ' + ((s && s.note) || 'no background run') };
+  }
+  job.sessionId = s.id;
+  return { ok: true, running: { since: job.since, turn: job.turn } };
+}
+
+function finish(ctx, w, cadence, job, r) {
+  const root = w.root;
+  const key = keyOf(root, cadence);
+  if (jobs.get(key) === job) jobs.delete(key);
+  const slot = job.slotPath ? (D.cyclePaths(root, job.slotPath) || {}).slot : undefined;
+  const fail = (why) => { try { D.append(root, cadence, { ev: 'error', text: why, mode: job.mode, ...(slot ? { slot, sha: job.sha } : {}) }); } catch { /* the folder is gone */ } };
+  try {
+    const res = (r && r.result) || {};
+    const ok = !!(r && !r.timedOut && !r.stopped && r.code === 0 && res.ok && !res.isError);
+    const out = resultJson(res.text);
+    let html = null;
+    try { html = fs.readFileSync(job.pending, 'utf8'); } catch { html = null; }
+    if (!html && out && typeof out.html === 'string') html = out.html;
+    if (!ok && !html) {
+      const why = r && r.timedOut ? `The design run took too long and was stopped (${r.note || 'timed out'}).` : r && r.stopped ? 'The design run was stopped.'
+        : `The design run failed: ${(r && r.note) || 'no result'}${res.text ? '. ' + String(res.text).replace(/\s+/g, ' ').slice(0, 300) : ''}`;
+      fail(why);
+    } else if (!html) fail('The design run ended without a render. Nothing changed.');
+    else if (job.mode === 'turn') {
+      const v = D.writeVersion(root, cadence, html, { turn: job.turn, answer: (out && typeof out.answer === 'string' && out.answer) || null, rules: out && out.rules, from: 'turn' });
+      if (!v.ok) fail(`The render could not be used: ${v.error}. Nothing changed.`);
+      if (out && Array.isArray(out.took)) for (const t of out.took.slice(0, 40)) if (isObj(t)) D.recordTook(root, cadence, text(t.id), t.took, typeof t.readable === 'boolean' ? t.readable : undefined);
+    } else {
+      const st = D.stateOf(root, cadence);
+      if (!st.saved) fail('The design was not saved any more, so the cycle was not rendered.');
+      else {
+        const c = D.writeCycle(root, job.slotPath, html, { designVersion: st.saved.version, mode: job.mode, sha: job.sha });
+        if (!c.ok) fail(`The ${slot} cycle render could not be used: ${c.error}.`);
+      }
+    }
+  } catch (e) { fail('The design run result could not be read: ' + String((e && e.message) || e).slice(0, 200)); }
+  try { fs.unlinkSync(job.pending); } catch { /* not written */ }
+  // The next cycle that waited for this job.
+  const q = queue.get(key);
+  if (q && q.length) {
+    const next = q.shift();
+    if (!q.length) queue.delete(key);
+    startCycle(ctx, w, cadence, next);
+  }
+}
+
+// ── the cycle hook ──────────────────────────────────────────────────────────────────────────────────────────
+/** Start (or queue) the cycle render of one drafted slot, when the report's design is saved and the slot is not issued. */
+function startCycle(ctx, w, cadence, rel) {
+  try {
+    const c = D.cyclePaths(w.root, rel);
+    if (!c || !fs.existsSync(c.md)) return { ok: false, error: 'no such cycle' };
+    const st = D.stateOf(w.root, cadence);
+    if (!st.saved) return { ok: false, error: 'no saved design' };
+    if (D.isIssuedSlot(w.root, cadence, c.slot)) return { ok: false, error: 'issued' };
+    const key = keyOf(w.root, cadence);
+    if (jobs.has(key)) {
+      const j = jobs.get(key);
+      if (j.slotPath === c.rel && j.sha === D.docSha(c.md)) return { ok: true, queued: false };
+      const q = queue.get(key) || [];
+      if (!q.includes(c.rel)) q.push(c.rel);
+      queue.set(key, q);
+      return { ok: true, queued: true };
+    }
+    return startJob(ctx, w, cadence, { mode: 'cycle', cycleRel: c.rel });
+  } catch (e) { return { ok: false, error: String((e && e.message) || e) }; }
+}
+function workspaceForRoot(ctx, root) {
+  const abs = path.resolve(String(root));
+  const list = typeof ctx.workspaceList === 'function' ? ctx.workspaceList() : [ctx.getWs(null)].filter(Boolean);
+  return list.find((w) => w && w.root && path.resolve(w.root) === abs) || null;
+}
+/** server.js calls this once: drafts written in this process start their cycle render at once. */
+function attach(factory) {
+  ctxFactory = typeof factory === 'function' ? factory : null;
+  RDraft.onDraftWritten(({ root, cadence, path: rel }) => {
+    setImmediate(() => {
+      try {
+        const ctx = ctxFactory ? ctxFactory() : lastCtx;
+        if (!ctx) return;
+        const w = workspaceForRoot(ctx, root);
+        if (w) startCycle(ctx, w, cadence, rel);
+      } catch { /* the sweep tries again */ }
+    });
+  });
+}
+/** On the tick: a slot drafted after the design was saved, with no render, is rendered (a draft the CLI wrote). */
+function sweep(ctx) {
+  if (!ctx) return [];
+  lastCtx = ctx;
+  const started = [];
+  const list = typeof ctx.workspaceList === 'function' ? ctx.workspaceList() : [ctx.getWs(null)].filter(Boolean);
+  for (const w of list) {
+    if (!w || !w.root) continue;
+    let base;
+    try { base = path.join(path.resolve(w.root), RDraft.stateRel(w.root), 'reports'); } catch { continue; }
+    let cadences = [];
+    try { cadences = fs.readdirSync(base); } catch { continue; }
+    for (const cadence of cadences) {
+      if (!D.CADENCE_RE.test(cadence) || cadence === 'definitions') continue;
+      let p; try { p = D.paths(w.root, cadence); } catch { continue; }
+      if (!fs.existsSync(p.events)) continue;
+      const st = D.stateOf(w.root, cadence);
+      if (!st.saved) continue;
+      const savedMs = Date.parse(st.saved.at);
+      let files = [];
+      try { files = fs.readdirSync(p.folder); } catch { continue; }
+      for (const f of files) {
+        if (!/^\d{4}-\d{2}-\d{2}\.md$/.test(f)) continue;
+        const rel = `${p.rel}/${f}`;
+        const c = D.cyclePaths(w.root, rel);
+        if (!c || fs.existsSync(c.json)) continue;
+        let mt = 0; try { mt = fs.statSync(c.md).mtimeMs; } catch { continue; }
+        if (mt < savedMs) continue;
+        const sha = D.docSha(c.md);
+        if (st.errors.some((e) => e.slot === c.slot && e.sha === sha)) continue;
+        const r = startCycle(ctx, w, cadence, rel);
+        if (r.ok) started.push(rel);
+      }
+    }
+  }
+  return started;
+}
+
+// ── the Edit log line ───────────────────────────────────────────────────────────────────────────────────────
+function editLog(ctx, row) {
+  if (!ctx.runtimeDir) return false;
+  try {
+    const dir = path.join(ctx.runtimeDir, 'doc-sheet');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, 'report-notes.jsonl'), JSON.stringify({ ...row, at: new Date().toISOString() }) + '\n');
+    return true;
+  } catch { return false; }
+}
+
+/** A turn that has no answer and no job in this server (the workspace restarted mid-run) gets an error line. */
+function settleStale(root, cadence) {
+  if (jobs.has(keyOf(root, cadence))) return;
+  const ev = D.readEvents(root, cadence);
+  let lastTurn = -1; let lastEnd = -1;
+  ev.forEach((l, i) => { if (l.ev === 'turn') lastTurn = i; if (l.ev === 'version' || l.ev === 'error') lastEnd = i; });
+  if (lastTurn > lastEnd && Date.now() - Date.parse(ev[lastTurn].at) > 90000) D.append(root, cadence, { ev: 'error', text: 'The design run stopped when the workspace restarted. Send the turn again.', mode: 'turn' });
+}
+
+// ── the handler ─────────────────────────────────────────────────────────────────────────────────────────────
+function sendHtml(res, html) {
+  const buf = Buffer.from(String(html), 'utf8');
+  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Content-Length': buf.length, 'Cache-Control': 'no-store', 'Content-Security-Policy': HTML_CSP, 'X-Content-Type-Options': 'nosniff' });
+  res.end(buf);
+  return true;
+}
+function reportDoc(w, rel) {
+  if (!RC.isReportPath(rel)) return { error: bad(400, 'path must be a report document: <state>/reports/<cadence>/<slot>.md') };
+  const c = D.cyclePaths(w.root, rel);
+  if (!c) return { error: bad(400, 'path must be a report document') };
+  try {
+    const real = fs.realpathSync(c.md);
+    if (!real.startsWith(fs.realpathSync(path.resolve(w.root)) + path.sep)) return { error: bad(404, 'outside workspace') };
+  } catch { return { error: bad(404, 'no such report document') }; }
+  return { c };
+}
+function cycleAnswer(w, c) {
+  const st = D.stateOf(w.root, c.cadence);
+  const rec = D.readCycle(w.root, c.rel);
+  const j = jobs.get(keyOf(w.root, c.cadence));
+  const prev = D.previousCycle(w.root, c.rel);
+  const differences = rec && Array.isArray(rec.differences) ? rec.differences : [];
+  // designed: THIS cycle has a render drawn to a saved design (the contract's answer is per document). A cycle drafted before the design,
+  // or one whose first render is still running, is not designed yet: the page reads it in its format view and fetches no cycle-html.
+  return { ok: true, designed: !!st.saved && !!rec, design_version: rec ? rec.design_version : null,
+    format: (rec && rec.format) || (st.saved && (D.versionMeta(w.root, c.cadence, st.saved.version) || {}).format) || st.format || 'deck',
+    outline: rec && Array.isArray(rec.outline) ? rec.outline : [], differences, decisions: rec && Array.isArray(rec.decisions) ? rec.decisions : [],
+    matches: !!rec && differences.length === 0, rendering: !!(j && j.slotPath === c.rel), previous: prev ? { path: prev.path, slot: prev.slot } : null };
+}
+
+async function handle(req, res, url, ctx) {
+  lastCtx = ctx;
+  const p = url.pathname;
+  const send = (r) => { ctx.json(res, r.body, r.status); return true; };
+  const isNotes = p === '/api/report-notes' || p.startsWith('/api/report-notes/');
+  const sub = isNotes ? p.replace(/^\/api\/report-notes\/?/, '') : p.replace(/^\/api\/report-design\/?/, '');
+
+  if (req.method === 'GET') {
+    const w = wsOf(ctx, url.searchParams.get('ws'));
+    if (!w) return send(bad(404, 'no such workspace'));
+    if (isNotes) {
+      if (sub !== '') return send(bad(404, 'no such route'));
+      const d = reportDoc(w, text(url.searchParams.get('path'))); if (d.error) return send(d.error);
+      const n = D.notesOf(w.root, d.c.rel);
+      return send(n.ok ? { status: 200, body: n } : bad(n.status, n.error));
+    }
+    if (sub === '' || sub === 'version') {
+      const id = text(url.searchParams.get('id'));
+      if (!D.CADENCE_RE.test(id)) return send(bad(400, 'id must be a report id'));
+      const setup = setupOf(w.root, id);
+      if (!setup) return send(bad(404, 'no such report'));
+      if (sub === 'version') {
+        const n = Number(url.searchParams.get('n'));
+        const html = Number.isInteger(n) && n > 0 ? D.versionHtml(w.root, id, n) : null;
+        if (html == null) return send(bad(404, 'no such version'));
+        return sendHtml(res, D.sanitize(html));
+      }
+      try { settleStale(w.root, id); } catch { /* a read never fails on this */ }
+      return send({ status: 200, body: { ok: true, setup, design: D.designAnswer(w.root, id, { running: runningOf(w.root, id) }) } });
+    }
+    if (sub === 'cycle' || sub === 'cycle-html') {
+      const d = reportDoc(w, text(url.searchParams.get('path'))); if (d.error) return send(d.error);
+      if (sub === 'cycle') return send({ status: 200, body: cycleAnswer(w, d.c) });
+      let html; try { html = fs.readFileSync(d.c.html, 'utf8'); } catch { return send(bad(404, 'this cycle has no render yet')); }
+      return sendHtml(res, D.sanitize(html));
+    }
+    return send(bad(404, 'no such route'));
+  }
+
+  if (!(isNotes ? NOTES_POSTS : DESIGN_POSTS).includes(sub)) return send(bad(404, 'no such route'));
+  if (req.method !== 'POST') return send(bad(405, 'POST only'));
+  const read = await ctx.readJson(req);
+  if (!read.ok) return send(bad(400, 'the body is not JSON'));
+  const body = read.body || {};
+  if (req.headers && req.headers['x-pmos-session']) return send(bad(403, 'an agent session cannot change a report design, its cycles or its notes. Only a press on the page does'));
+  const g = guard.requirePagePress(req, body);
+  if (!g.ok) return send(bad(g.status, g.error));
+  const w = wsOf(ctx, text(body.ws));
+  if (!w) return send(bad(404, 'no such workspace'));
+  const root = w.root;
+  const fail = (r) => send(bad(r.status || 400, r.error));
+
+  if (isNotes) {
+    const d = reportDoc(w, text(body.path)); if (d.error) return send(d.error);
+    if (sub === 'speaker') {
+      const r = D.setSpeaker(root, d.c.rel, { slide: body.slide, text: body.text, keep: body.keep === true });
+      if (!r.ok) return fail(r);
+    } else {
+      const r = D.pinOp(root, d.c.rel, body, { by: 'you' });
+      if (!r.ok) return fail(r);
+      editLog(ctx, { event: 'pin', path: d.c.rel, by: 'pm', op: r.op, id: r.pin.id, slide: r.pin.slide, text: r.pin.text, ...(r.pin.section ? { section: r.pin.section } : {}) });
+    }
+    return send({ status: 200, body: D.notesOf(root, d.c.rel) });
+  }
+
+  if (sub === 'cycle-decision') {
+    const d = reportDoc(w, text(body.path)); if (d.error) return send(d.error);
+    const c = d.c;
+    const choice = text(body.choice);
+    if (!D.CHOICES.includes(choice)) return send(bad(400, 'choice must be keep, adopt or match'));
+    if (D.isIssuedSlot(root, c.cadence, c.slot)) return send(bad(409, 'this cycle is issued and frozen with the design it was rendered with'));
+    const st = D.stateOf(root, c.cadence);
+    if (!st.saved) return send(bad(409, 'this report has no saved design'));
+    const rec = D.readCycle(root, c.rel);
+    if (!rec) return send(bad(404, 'this cycle has no render yet'));
+    const diffs = Array.isArray(rec.differences) ? rec.differences : [];
+    const diff = diffs.find((x) => x.id === text(body.diff));
+    if (!diff) return send(bad(404, 'no such difference on this cycle'));
+    let newVersion = null;
+    if (choice === 'match') {
+      const s = startJob(ctx, w, c.cadence, { mode: 'match', cycleRel: c.rel });
+      if (!s.ok) return fail(s);
+    } else if (choice === 'adopt') {
+      let html; try { html = fs.readFileSync(c.html, 'utf8'); } catch { return send(bad(404, 'this cycle has no render to adopt')); }
+      const v = D.writeVersion(root, c.cadence, html, { turn: `Made part of the design from the ${c.slot} cycle: ${diff.what}`, answer: `D${D.stateOf(root, c.cadence).versions.size + 1} is the design now, from the ${c.slot} cycle.`,
+        rules: D.rulesFor(root, c.cadence, st.saved.version), from: 'adopt', actor: g.actor });
+      if (!v.ok) return fail(v);
+      newVersion = v.n;
+      D.append(root, c.cadence, { ev: 'accept', n: v.n, rules: D.rulesFor(root, c.cadence, v.n) }, { actor: g.actor });
+      D.writeBrief(root, c.cadence, setupOf(root, c.cadence));
+    }
+    const r = D.decideCycle(root, c.rel, { diff: diff.id, choice, newVersion });
+    if (!r.ok) return fail(r);
+    D.append(root, c.cadence, { ev: 'cycle-decision', path: c.rel, slot: c.slot, diff: diff.id, choice }, { actor: g.actor });
+    editLog(ctx, { event: 'design', path: c.rel, by: 'pm', choice, diff: diff.id, what: diff.what });
+    return send({ status: 200, body: { ...cycleAnswer(w, c), cycle: r.cycle } });
+  }
+
+  const id = text(body.id);
+  if (!D.CADENCE_RE.test(id)) return send(bad(400, 'id must be a report id'));
+  const setup = setupOf(root, id);
+  if (!setup) return send(bad(404, 'no such report'));
+  const answer = () => send({ status: 200, body: { ok: true, setup, design: D.designAnswer(root, id, { running: runningOf(root, id) }) } });
+
+  if (sub === 'describe') {
+    const t = text(body.text).trim();
+    if (!t || t.length > 4000) return send(bad(400, 'text is required, at most 4000 characters'));
+    if (body.format !== undefined && !D.FORMATS.includes(body.format)) return send(bad(400, 'format must be deck or doc'));
+    D.append(root, id, { ev: 'describe', text: t, ...(body.format ? { format: body.format } : {}) }, { actor: g.actor });
+    return answer();
+  }
+  if (sub === 'sample') {
+    const r = D.addSample(root, id, body, { actor: g.actor });
+    if (!r.ok) return fail(r);
+    return send({ status: 200, body: { ok: true, sample: r.sample } });
+  }
+  if (sub === 'turn') {
+    if (jobs.has(keyOf(root, id))) return send(bad(409, 'PMOS is already working on this report. Wait for the answer, then try again.'));
+    const t = text(body.text).trim();
+    if (t.length > 4000) return send(bad(400, 'text is at most 4000 characters'));
+    if (body.points !== undefined && !Array.isArray(body.points)) return send(bad(400, 'points must be a list'));
+    const raw = Array.isArray(body.points) ? body.points : [];
+    if (raw.length > 20) return send(bad(400, 'at most 20 point markers in one turn'));
+    const points = [];
+    for (const [i, pt] of raw.entries()) {
+      if (!isObj(pt) || !D.SLIDE_ID_RE.test(text(pt.slide)) || typeof pt.x !== 'number' || typeof pt.y !== 'number' || !Number.isFinite(pt.x) || !Number.isFinite(pt.y) || !text(pt.text).trim() || text(pt.text).length > 1000) {
+        return send(bad(400, `point ${i + 1} needs slide (a slide id), x and y (numbers) and text`));
+      }
+      points.push({ n: Number.isInteger(pt.n) ? pt.n : i + 1, slide: pt.slide, x: Math.round(pt.x * 10) / 10, y: Math.round(pt.y * 10) / 10, text: text(pt.text).trim() });
+    }
+    const st = D.stateOf(root, id);
+    if (!t && !points.length && (st.versions.size || !st.description)) return send(bad(400, 'say what to change, or point at the preview'));
+    if (!D.currentCycle(root, id)) return send(bad(409, 'this report has no cycle yet. Draft it first, then design how it looks'));
+    D.append(root, id, { ev: 'turn', text: t, points, base: st.current }, { actor: g.actor });
+    const s = startJob(ctx, w, id, { mode: 'turn', turnText: t, points });
+    if (!s.ok) { D.append(root, id, { ev: 'error', text: s.error, mode: 'turn' }); return fail(s); }
+    return send({ status: 200, body: { ok: true, running: s.running } });
+  }
+  if (sub === 'accept' || sub === 'revert') {
+    const n = body.n;
+    if (!Number.isInteger(n) || !D.stateOf(root, id).versions.has(n)) return send(bad(404, 'no such version'));
+    if (sub === 'revert') { D.append(root, id, { ev: 'revert', n }, { actor: g.actor }); return answer(); }
+    D.append(root, id, { ev: 'accept', n, rules: D.rulesFor(root, id, n) }, { actor: g.actor });
+    const b = D.writeBrief(root, id, setup);
+    if (!b.ok) return fail(b);
+    return send({ status: 200, body: { ok: true, setup, brief: b.path, design: D.designAnswer(root, id, { running: runningOf(root, id) }) } });
+  }
+  return send(bad(404, 'no such route'));
+}
+
+module.exports = { prefixes: ['/api/report-design', '/api/report-notes'], handle, attach, sweep, startCycle, resultJson, _jobs: jobs };

package/workspace/lib/routes-reports.js

@@ -145,7 +145,8 @@ async function handle(req, res, url, ctx) {
     const notes = { ...RD.readNotes(file.text), [id]: body.text };
     const draft = RD.draftOf(root, { cadence: cs.cadence, slot: cs.slot, now: foldedAt(file.text) || undefined });
     if (!draft || draft.ok === false) return failed(draft || { status: 500, error: 'the drafter answered nothing' });
-    const r = RD.writeDraft(root, draft, { actor: g.actor, notes });
+    // quiet: a note save is not a new draft, so it does not re-render the cycle's design (report-design-studio)
+    const r = RD.writeDraft(root, draft, { actor: g.actor, notes, quiet: true });
     if (!r || r.ok === false) return failed(r || { status: 500, error: 'the writer answered nothing' });
     return done({ slot: cs.slot, path: r.path, sha: r.sha, id });
   }

package/workspace/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pmos-workspace",
-  "version": "0.196.0",
+  "version": "0.198.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pmos-workspace",
-      "version": "0.196.0",
+      "version": "0.198.0",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.196.0",
+  "version": "0.198.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",