create-pmos 0.52.0 → 0.53.1

package/workspace/lib/routes-initiatives.js

@@ -0,0 +1,371 @@
+'use strict';
+/* routes-initiatives.js — the Initiatives API: the Roadmap, the List, the initiative sheet, the export, and the three
+ * writes behind them (pm-os-absorb Run 2, slice 2C; PRD R13, R16, R17, R20 A, R23, R25, R26; D86 point 4).
+ *
+ *   GET  /api/initiatives?ws=&view=roadmap|list    → fixtures/initiatives-api/roadmap.json | list.json
+ *   GET  /api/initiatives/<id>?ws=                  → fixtures/initiatives-api/sheet.json
+ *   GET  /api/initiatives/<id>/export?ws=           → { ok, id, markdown }   (lib/breakdown-export.js; nothing is written)
+ *   POST /api/initiatives    { ws, title, lane, anchor, intent?, id?, from?, specimen_test?, surface_check? }
+ *                                                    → { ok, id, path, written, sig }   New initiative (requirePagePress)
+ *   POST /api/placements     { ws, events: [placed | created | adopted | dropped] }
+ *                                                    → { ok, written, sig }   fixtures/initiatives-api/post-ok.json
+ *   POST /api/measurements   { ws, events: [measured] } → { ok, written, sig }
+ *
+ * GUARDS (seams §3, §5.1). A placement into Now and `adopted` are PM-only acts: requirePmPress with act `now` or
+ * `adopt`, and one initiative per body (a bulk Move to Now is refused with 400, R17). Every other write — Next and Later
+ * placements, a new initiative, a measurement — passes requirePagePress. The actor goes from the guard to the writer;
+ * a body never names it. Refusals answer { ok: false, status, error } with that status (post-403.json).
+ *
+ * READS. The signature is taken BEFORE any ledger or record is read (the F2 rule of lib/plan-items.js), so a write that
+ * lands during a read changes the next poll's answer. `sig` = { placements, items, measurements, records }: the
+ * ledgerSig of each ledger read, and the records signature of lib/initiative-rows.js answerSig (the derivation the rows
+ * came from; a stale one is marked, so the poll after a re-derivation sees a new sig). The page watches it with
+ * public/pm/sig-watch.js. The rows come from lib/initiative-rows.js rowsFor(): until the first derivation of a
+ * repository lands, a GET answers 202 { ok: false, pending: true, error } and the page asks again.
+ * Work lanes only (D86 point 4): a document-lane initiative is in no answer; its sheet and its export are 404.
+ * Every `by` in an answer goes through actor.pageName, so no session token reaches the page (F5).
+ */
+const fs = require('fs');
+const path = require('path');
+const guard = require('./pm-guard.js');
+const actorLib = require('./actor.js');
+const ledgers = require('./plan-ledgers.js');
+const placements = require('./placements.js');
+const measurements = require('./measurements.js');
+const planItems = require('./plan-items.js');
+const planTree = require('./plan-tree.js');
+const planRules = require('./plan-rules.js');
+const health = require('./health.js');
+const factoryJoin = require('./factory-join.js');
+const display = require('./initiative-display.js');
+const rowsLib = require('./initiative-rows.js');
+const writer = require('./initiative-writer.js');
+const breakdownExport = require('./breakdown-export.js');
+const consoleState = require('./console-state');
+
+const HORIZON_RANK = { now: 0, next: 1, later: 2 };
+const FILE_KEYS = [['brief_path', 'brief', 'Brief'], ['prd_path', 'prd', 'PRD'], ['rubric_path', 'rubric', 'Rubric'], ['doc_path', 'doc', 'Document']];
+const cap = (s) => (s ? s[0].toUpperCase() + s.slice(1) : s);
+
+/** The signature of everything a read answers from, taken before the read. */
+function sigOf(root) {
+  return {
+    placements: ledgers.ledgerSig(root, 'placements'),
+    items: ledgers.ledgerSig(root, 'plan-items'),
+    measurements: ledgers.ledgerSig(root, 'measurements'),
+    records: rowsLib.recordsSig(root),
+  };
+}
+
+/** The lifecycle sub-shape of initiative-display.js: { state: active|held|closed|cancelled, reason, at } | null. */
+function lifecycleOf(rec) {
+  if (!rec.stopped) return null;
+  const state = rec.stopped.state === 'on-hold' ? 'held' : rec.stopped.state;
+  return { state, reason: rec.stopped.reason || '', at: rec.stopped.at || null };
+}
+
+/** The newest acceptance line of each initiative in the repository's runs directory: { [id]: { at, by } }. */
+function acceptancesOf(root) {
+  const out = {};
+  let text = '';
+  try { text = fs.readFileSync(path.join(ledgers.runsDir(root), 'acceptances.jsonl'), 'utf8'); } catch { return out; }
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    let r; try { r = JSON.parse(line); } catch { continue; }
+    if (!r || typeof r.initiative_id !== 'string') continue;
+    const at = r.at || r.date || null;
+    const prev = out[r.initiative_id];
+    if (prev && prev.at && (!at || at < prev.at)) continue;
+    const by = typeof r.by === 'string' ? r.by : (r.pm ? `pm:${r.pm}` : null);
+    out[r.initiative_id] = { at, by: actorLib.pageName(by) };
+  }
+  return out;
+}
+
+/** Everything one GET reads, once: the frame each row is built from. */
+function frameOf(w, rows, { now, sessions = [] } = {}) {
+  const root = w.root;
+  const rules = planRules.readRules(root);
+  const placed = placements.readPlacements(root, { now, rules, records: rows });
+  const fold = planItems.readFold(root, { now });
+  const meas = measurements.readMeasurements(root);
+  const join = factoryJoin.joinFactory(root);
+  const anchors = rowsLib.anchorsOf(root);
+  const accepted = acceptancesOf(root);
+  const byId = new Map(rows.filter((r) => r.ok !== false).map((r) => [r.id, r]));
+  return { root, rules, placed, fold, meas, join, anchors, accepted, byId, now, sessions };
+}
+
+/** The stage of a workflow row as the R4 stage group it falls in: { id, label }. */
+function stageOf(root, rec) {
+  const raw = rec.stage || null;
+  if (!raw) return { id: null, label: 'Unknown' };
+  try {
+    const st = planTree.stagesFor(root, rec.id).find((s) => s.id === raw || s.steps.includes(raw));
+    if (st) return { id: st.id, label: st.label };
+  } catch { /* fall through */ }
+  return { id: raw, label: cap(raw) };
+}
+
+/** The display ctx of initiative-display.js, with every frozen sub-shape (its header). */
+function displayCtx(F, rec, id) {
+  const items = {};
+  for (const [k, it] of Object.entries(F.fold.items)) if (it.initiative === id) items[k] = it;
+  const fold = { items, order: F.fold.order.filter((k) => items[k]), batches: (F.fold.batches || []).filter((b) => b.initiative === id), flags: (F.fold.flags || []).filter((f) => !f.initiative || f.initiative === id) };
+  const live = F.sessions.find((s) => typeof s.plan_item === 'string' && s.plan_item.startsWith(id + '.') && s.state !== 'exited');
+  return {
+    lifecycle: lifecycleOf(rec),
+    acceptance: rec.accepted ? (F.accepted[id] || { at: null, by: null }) : null,
+    handoff: live ? { item: live.plan_item, session: actorLib.pageName(`agent:${live.id}`) } : null,
+    fold,
+    placement: F.placed.byInit[id] || null,
+    rules: F.rules,
+    now: F.now,
+  };
+}
+
+function nextDue(F, id) {
+  let best = null;
+  for (const it of Object.values(F.fold.items)) {
+    if (it.initiative !== id || it.proposed || it.state === 'done' || !it.due) continue;
+    if (!best || it.due < best) best = it.due;
+  }
+  return best;
+}
+
+/** One initiative row: the key set every golden shares (d86-seams §10). */
+function rowOf(F, rec) {
+  const id = rec.id;
+  const p = F.placed.byInit[id];
+  const a = F.anchors.resolve(rec.anchor);
+  const ctx = displayCtx(F, rec, id);
+  const d = display.displayOf({ ...rec, last_activity: rec.last_activity }, ctx);
+  const measurement = measurements.latest(F.meas, a.token || '') || (rec.anchor ? measurements.latest(F.meas, String(rec.anchor).trim()) : null);
+  const h = health.healthOf({ id, row: rec, fold: ctx.fold, placement: ctx.placement, measurement, factory: factoryJoin.factoryOf(F.join, id), rules: F.rules, now: F.now });
+  const pr = planItems.progressOf(F.fold, id);
+  return {
+    id, title: rec.title || id, lane: rec.lane, anchor: a.anchor, anchor_kind: a.kind,
+    horizon: p.horizon, rank: p.rank, confirmed: p.confirmed, dormant: p.dormant, check_by: p.check_by,
+    stage: stageOf(F.root, rec),
+    display: { word: d.word, stage: d.stage, waitingOn: d.waitingOn, act: d.act, idleDays: d.idleDays, line2: d.line2 },
+    health: { level: h.level, reasons: h.reasons },
+    progress: { done: pr.done, total: pr.total, label: pr.label },
+    next_due: nextDue(F, id),
+    last_activity: rec.last_activity || null,
+  };
+}
+
+const flagsOf = (F) => F.placed.flags.map((f) => ({ kind: f.kind, init: f.init, why: actorLib.pageName(f.why) }));
+
+function roadmapOf(w, F) {
+  const rowsBy = (h) => F.placed.order[h].filter((id) => F.byId.has(id)).map((id) => rowOf(F, F.byId.get(id)));
+  const now = rowsBy('now');
+  const next = rowsBy('next');
+  const laterAll = rowsBy('later');
+  const later = laterAll.filter((r) => !r.dormant);
+  const dormant = laterAll.filter((r) => r.dormant);
+  const title = (id) => (F.byId.get(id) || {}).title || id;
+  return {
+    header: {
+      now: { count: now.length, kr: now.filter((r) => r.anchor_kind === 'kr' || r.anchor_kind === 'objective').length, health: now.filter((r) => r.anchor_kind === 'health').length, cap: F.rules.now_cap },
+      next: { count: next.length },
+      later: { count: later.length, dormant: dormant.length },
+    },
+    horizons: { now, next, later },
+    dormant,
+    proposals: F.placed.proposals.map((p) => ({ eid: p.eid, initiative: p.init, title: title(p.init), horizon: p.horizon, after: p.after, by: actorLib.pageName(p.by), at: p.at })),
+    flags: flagsOf(F),
+  };
+}
+
+function listOf(w, F) {
+  const all = Object.values(F.placed.order).flat().filter((id) => F.byId.has(id)).map((id) => rowOf(F, F.byId.get(id)));
+  const groups = new Map();      // objective key -> { objective, anchors: Map(anchorKey -> group) }
+  const objOrder = [];
+  for (const r of all) {
+    const a = F.anchors.resolve(F.byId.get(r.id).anchor);
+    const okey = a.objective ? `o:${a.objective.id}` : 'none';
+    if (!groups.has(okey)) { groups.set(okey, { objective: a.objective, anchors: new Map() }); objOrder.push(okey); }
+    const g = groups.get(okey);
+    if (!g.anchors.has(a.key)) {
+      const raw = String(F.byId.get(r.id).anchor || '').trim();
+      const m = (a.token && measurements.latest(F.meas, a.token)) || (a.anchor && measurements.latest(F.meas, a.anchor)) || (raw && measurements.latest(F.meas, raw)) || null;
+      g.anchors.set(a.key, { anchor: a.anchor, kind: a.kind, title: a.title, measurement: m ? { value: m.value, target: m.target, unit: m.unit, as_of: m.as_of, source: m.source } : null, rows: [] });
+    }
+    g.anchors.get(a.key).rows.push(r);
+  }
+  const byDue = (x, y) => (HORIZON_RANK[x.horizon] - HORIZON_RANK[y.horizon])
+    || ((x.next_due || '9999') < (y.next_due || '9999') ? -1 : (x.next_due || '9999') > (y.next_due || '9999') ? 1 : 0) || (x.rank - y.rank);
+  // Objectives first, in the order their rows first appear; the anchors with no objective (health, domain, none) last.
+  const ordered = [...objOrder.filter((k) => k !== 'none'), ...objOrder.filter((k) => k === 'none')];
+  return {
+    groups: ordered.map((k) => {
+      const g = groups.get(k);
+      return { objective: g.objective, anchors: [...g.anchors.values()].map((x) => ({ ...x, rows: x.rows.sort(byDue) })) };
+    }),
+    flags: flagsOf(F),
+  };
+}
+
+function sheetOf(w, F, rec) {
+  const root = F.root;
+  const row = rowOf(F, rec);
+  let lad = null;
+  try { lad = consoleState.ladder({ root, id: rec.id }); } catch (e) { lad = { ok: false, error: String((e && e.message) || e) }; }
+  const lay = planTree.layout({ root, initiative: rec.id, fold: F.fold, ladder: lad, now: F.now });
+  const stepper = lay.stages.map((s) => ({ id: s.id, label: s.label, state: s.state === 'current' ? 'current' : s.state === 'done' ? 'done' : 'todo' }));
+  let waiting = null;
+  if (row.display.waitingOn) {
+    waiting = { on: row.display.waitingOn, act: row.display.act, action: row.display.waitingOn === 'pm' ? { label: 'Open gate', kind: 'gate', target: null } : { label: 'Hand to agent', kind: 'handoff', target: rec.id } };
+  } else {
+    const cur = lay.stages.find((s) => s.current && s.owed);
+    if (cur) {
+      const on = cur.owed.actor === 'you' ? 'pm' : 'agent';
+      waiting = { on, act: cur.owed.noun, action: on === 'pm' ? { label: 'Open gate', kind: 'gate', target: cur.owed.key } : { label: 'Hand to agent', kind: 'handoff', target: rec.id } };
+    }
+  }
+  let fm = {};
+  try {
+    const loaded = consoleState.loadEngine();
+    const file = planTree.recordPath(root, rec.id);
+    if (loaded.ok && file) fm = loaded.engine.parseLeadingFrontmatter(fs.readFileSync(file, 'utf8')) || {};
+  } catch { fm = {}; }
+  const files = FILE_KEYS.filter(([k]) => typeof fm[k] === 'string' && fm[k].trim()).map(([k, kind, label]) => ({ kind, label, path: String(fm[k]).trim() }));
+  const verb = { now: 'Moved to Now', next: 'Moved to Next', later: 'Moved to Later' };
+  const history = F.placed.moves.filter((m) => m.init === rec.id)
+    .map((m) => ({ at: m.at, by: actorLib.pageName(m.by), text: m.from === null && m.to === 'later' ? 'Added to Later' : verb[m.to] }))
+    .reverse();
+  return { initiative: row, stepper, waiting, files, history, cli: { now: `pmos initiative now ${rec.id}`, export: `pmos initiative export ${rec.id}` } };
+}
+
+// ── HTTP ─────────────────────────────────────────────────────────────────────────────────────────
+function wsOf(ctx, url) {
+  const wsParam = url.searchParams.get('ws');
+  const w = ctx.getWs(wsParam);
+  if (!w || (wsParam && w.id !== wsParam)) return null;
+  return w;
+}
+const answer = (ctx, res, r) => ctx.json(res, { ok: false, status: r.status, error: r.error }, r.status);
+
+/** The rowsFor answer of a repository ({ rows, sig, stale, … }), or null when an answer was already sent (pending or
+ *  unreadable). */
+function rowsOrAnswer(ctx, res, w, extra) {
+  const r = rowsLib.rowsFor(w.root);
+  if (r.pending) { ctx.json(res, { ok: false, pending: true, ws: w.id, ...extra, error: 'The initiatives are being read. Ask again in a few seconds.' }, 202); return null; }
+  if (!r.ok) { ctx.json(res, { ok: false, ws: w.id, ...extra, error: r.error }, 500); return null; }
+  return r;
+}
+
+async function readBody(ctx, req, res) {
+  const r = await ctx.readJson(req);
+  if (!r.ok) { ctx.json(res, { ok: false, status: 400, error: 'invalid JSON body' }, 400); return null; }
+  return r.body;
+}
+
+/** POST /api/placements: which guard, and the one-initiative rule for the PM-only acts. */
+function placementGuard(req, body, root) {
+  const events = Array.isArray(body.events) ? body.events : null;
+  if (!events) return { ok: false, status: 400, error: 'send { ws, events: [ … ] }' };
+  const isNow = (e) => e && e.ev === 'placed' && e.horizon === 'now';
+  const isAdopt = (e) => e && e.ev === 'adopted';
+  const nowLines = events.filter(isNow);
+  const adoptLines = events.filter(isAdopt);
+  if (!nowLines.length && !adoptLines.length) return guard.requirePagePress(req, body);
+  if (nowLines.length && adoptLines.length) return { ok: false, status: 400, error: 'send Move to Now and adopt as two presses' };
+  const g = guard.requirePmPress(req, body, { act: adoptLines.length ? 'adopt' : 'now' });
+  if (!g.ok) return g;
+  // R17: Move to Now and adopt are never bulk. One initiative, and every line of the body about it.
+  const inits = new Set();
+  for (const e of events) {
+    if (isAdopt(e)) {
+      const p = placements.readPlacements(root).proposals.find((x) => x.eid === e.proposal);
+      inits.add(p ? p.init : `proposal:${e.proposal}`);
+    } else inits.add(e && e.initiative);
+  }
+  if (inits.size > 1 || adoptLines.length > 1) return { ok: false, status: 400, error: `${adoptLines.length ? 'adopt' : 'Move to Now'} takes one initiative per press; this body names ${Math.max(inits.size, adoptLines.length)}` };
+  return g;
+}
+
+async function handle(req, res, url, ctx) {
+  const p = url.pathname;
+  if (req.method === 'GET' && p.startsWith('/api/initiatives')) {
+    const w = wsOf(ctx, url);
+    if (!w) { ctx.json(res, { ok: false, error: 'no such workspace' }, 404); return true; }
+    const m = /^\/api\/initiatives(?:\/([^/]+)(\/export)?)?$/.exec(p);
+    if (!m) { ctx.json(res, { ok: false, error: 'not found' }, 404); return true; }
+    const id = m[1] ? decodeURIComponent(m[1]) : null;
+    if (id && !planTree.INIT_RE.test(id)) { ctx.json(res, { ok: false, error: 'an initiative id must be a record name' }, 400); return true; }
+    if (id && m[2]) {
+      const got = rowsOrAnswer(ctx, res, w, { id });
+      if (!got) return true;
+      const rec = got.rows.find((r) => r.id === id && r.ok !== false);
+      if (!rec || rec.group !== 'work') { ctx.json(res, { ok: false, error: `no work-lane initiative ${id} in this repository` }, 404); return true; }
+      const r = breakdownExport.exportBreakdown(w.root, id);
+      if (!r.ok) { ctx.json(res, { ok: false, error: r.error }, r.status); return true; }
+      ctx.json(res, { ok: true, ws: w.id, id, markdown: r.markdown });
+      return true;
+    }
+    const view = id ? 'sheet' : (url.searchParams.get('view') || 'roadmap');
+    if (!['roadmap', 'list', 'sheet'].includes(view)) { ctx.json(res, { ok: false, error: 'view is roadmap or list' }, 400); return true; }
+    const now = Date.now();
+    const sig = sigOf(w.root);   // BEFORE the reads (F2)
+    const got = rowsOrAnswer(ctx, res, w, id ? {} : { view });
+    if (!got) return true;
+    const rows = got.rows;
+    // The records part names the derivation the rows came from, not the records now: a stale answer must read
+    // differently from the fresh one that replaces it, or the page's watchSig never sees the derivation land.
+    sig.records = rowsLib.answerSig(got);
+    let sessions = [];
+    try { sessions = (ctx.sessionList ? ctx.sessionList() : []).filter((s) => s.ws === w.id); } catch { sessions = []; }
+    try {
+      const F = frameOf(w, rows, { now, sessions });
+      const head = { ok: true, ws: w.id };
+      if (id) {
+        const rec = F.byId.get(id);
+        if (!rec || !F.placed.byInit[id]) { ctx.json(res, { ok: false, error: `no work-lane initiative ${id} in this repository` }, 404); return true; }
+        ctx.json(res, { ...head, sig, now: new Date(now).toISOString(), ...sheetOf(w, F, rec) });
+        return true;
+      }
+      const body = view === 'list' ? listOf(w, F) : roadmapOf(w, F);
+      ctx.json(res, { ...head, view, sig, now: new Date(now).toISOString(), rules: F.rules, ...body });
+    } catch (e) {
+      ctx.json(res, { ok: false, error: 'the initiatives could not be read: ' + String((e && e.message) || e).slice(0, 160) }, 500);
+    }
+    return true;
+  }
+
+  if (req.method !== 'POST') { ctx.json(res, { ok: false, error: 'GET or POST only' }, 405); return true; }
+  const body = await readBody(ctx, req, res);
+  if (!body) return true;
+  if (typeof body !== 'object' || Array.isArray(body)) { ctx.json(res, { ok: false, status: 400, error: 'the body must be a JSON object' }, 400); return true; }
+  const wsParam = typeof body.ws === 'string' ? body.ws : null;
+  const w = ctx.getWs(wsParam);
+  if (!w || (wsParam && w.id !== wsParam)) { ctx.json(res, { ok: false, status: 404, error: 'no such workspace' }, 404); return true; }
+
+  if (p === '/api/initiatives') {
+    const g = guard.requirePagePress(req, body);
+    if (!g.ok) return answer(ctx, res, g), true;
+    const { ws: _ws, ...input } = body;
+    const r = writer.createInitiative(w.root, input, { actor: g.actor });
+    if (!r.ok) { ctx.json(res, { ok: false, status: r.status, error: r.error, field: r.field }, r.status); return true; }
+    rowsLib.invalidate(w.root);
+    if (ctx.invalidateNeedsAgg) ctx.invalidateNeedsAgg(w.id);
+    ctx.json(res, { ok: true, id: r.id, path: r.path, written: r.written, sig: sigOf(w.root) });
+    return true;
+  }
+  if (p === '/api/placements' || p === '/api/measurements') {
+    const g = p === '/api/placements' ? placementGuard(req, body, w.root) : guard.requirePagePress(req, body);
+    if (!g.ok) return answer(ctx, res, g), true;
+    if (!Array.isArray(body.events)) { ctx.json(res, { ok: false, status: 400, error: 'send { ws, events: [ … ] }' }, 400); return true; }
+    const lib = p === '/api/placements' ? placements : measurements;
+    const r = lib.appendFromUi(w.root, body.events, { actor: g.actor });
+    if (!r.ok) { ctx.json(res, { ok: false, status: r.status, error: r.error, index: r.index }, r.status); return true; }
+    if (ctx.invalidateNeedsAgg) ctx.invalidateNeedsAgg(w.id);
+    ctx.json(res, { ok: true, written: r.written, sig: sigOf(w.root) });
+    return true;
+  }
+  ctx.json(res, { ok: false, error: 'not found' }, 404);
+  return true;
+}
+
+module.exports = { prefixes: ['/api/initiatives', '/api/placements', '/api/measurements'], handle, sigOf, rowOf, frameOf, roadmapOf, listOf, sheetOf };

package/workspace/lib/routes-reports.js

@@ -0,0 +1,163 @@
+'use strict';
+/* routes-reports.js — the Reports destination's HTTP routes (pm-os-absorb Run 5, slice 5C; PRD R9, R22.5, R25).
+ *
+ *   GET  /api/report?ws=                         the report files of the repository, drafts and issued, of every cadence,
+ *                                                with the `sig` the page watches (public/pm/sig-watch.js, 10 s)
+ *   GET  /api/report/draft?ws=&cadence=&slot=    one report file as it is now: its markdown, its note texts, its blob sha
+ *   POST /api/report/draft   { ws, cadence, slot?, redraft? }   Draft now, and Redraft (the notes are kept)
+ *   POST /api/report/note    { ws, cadence, slot, id, text }    one note, by initiative id (or report.headline, report.asks)
+ *   POST /api/report/issue   { ws, cadence, slot, sha }          Issue: the PM's act (R25)
+ *
+ * WHICH GUARD. A draft and a note are page writes, not PM-only acts: both call pm-guard.js requirePagePress. Issue is a
+ * PM-only act (D86 point 2) and calls requirePmPress with act 'issue', then issues.appendFromUi with the guard's actor.
+ * Nothing here checks an Origin or a nonce by hand, and nothing reads `by` from a body: the writers take the actor from
+ * the guard. Every `by` in an answer goes through actor.pageName, so a session token never reaches the page (F5).
+ *
+ * THE FILE IS WRITTEN IN ONE PLACE. Only report-draft.js writeDraft writes a report file. A note save is a Redraft with
+ * one note changed, folded at the same `now` as the draft it edits (the draft's own `timestamp`). That pins the window and
+ * the lines bound to it. It does not freeze a value the drafter reads from the repository as it is now (a stage, a health),
+ * so a note save can move such a value, and the page says so (issues/run5-c.md, 5A).
+ * Issue freezes the bytes the PM read: the body carries the sha the page was shown, and the writer refuses a file that
+ * changed since (409).
+ *
+ * Nothing here sends a report anywhere. There is no route that emails, posts or shares one.
+ */
+const fs = require('fs');
+const path = require('path');
+const guard = require('./pm-guard.js');
+const actorLib = require('./actor.js');
+const RD = require('./report-draft.js');
+const issues = require('./issues.js');
+const RN = require('./report-needs.js');
+
+const CADENCE_RE = /^[a-z][a-z0-9-]{0,39}$/;
+const SLOT_RE = /^\d{4}-\d{2}-\d{2}$/;
+const NOTE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
+const SHA_RE = /^[0-9a-f]{40}$/;
+const MAX_NOTE = 20000;
+
+const prefixes = ['/api/report'];
+
+const refuse = (ctx, res, status, error) => { ctx.json(res, { ok: false, error }, status); return true; };
+/** The registered workspace named by `ws`. An unknown id is a 404: getWs would answer the home workspace instead. */
+const wsFrom = (ctx, id) => { const w = ctx.getWs(id || null); return w && (!id || w.id === id) ? w : null; };
+
+/** A report as the page sees it: the session token never leaves, and the sort key and file time stay here. */
+function pageReport(r) {
+  return {
+    cadence: r.cadence, slot: r.slot, path: r.path, status: r.status, bytes: r.bytes, edited: r.edited,
+    issued: r.issued ? { at: r.issued.at, by: actorLib.pageName(r.issued.by), via: r.issued.via, sha: r.issued.sha } : null,
+  };
+}
+/** A flag names the line it is about, and 5A's text carries that line's `by`: the session token is cut there too (F5). */
+const pageText = (s) => String(s == null ? '' : s).replace(/agent:sess-\d+\.[0-9a-f]{8}/g, (m) => actorLib.pageName(m));
+const pageFlags = (flags) => (flags || []).map((f) => ({ kind: f.kind, why: pageText(f.why) }));
+
+function findReport(list, cadence, slot) { return list.reports.find((x) => x.cadence === cadence && x.slot === slot) || null; }
+
+function readFile(root, rel) {
+  try { const buf = fs.readFileSync(path.join(path.resolve(String(root)), rel)); return { buf, text: buf.toString('utf8') }; } catch { return null; }
+}
+
+/** The time a draft was folded at: its frontmatter `timestamp` (report-draft.js writes the window's end there). */
+function foldedAt(text) {
+  const m = /^---\r?\n[\s\S]*?\r?\ntimestamp:\s*(\S+)[\s\S]*?\r?\n---/.exec(String(text || ''));
+  return m && Number.isFinite(Date.parse(m[1])) ? m[1] : null;
+}
+
+const cadenceSlot = (src) => {
+  const cadence = String(src.cadence || '');
+  const slot = src.slot == null ? null : String(src.slot);
+  if (!CADENCE_RE.test(cadence)) return { error: 'cadence must be a report id such as biweekly' };
+  if (slot !== null && !SLOT_RE.test(slot)) return { error: 'slot must be a date, YYYY-MM-DD' };
+  return { cadence, slot };
+};
+
+async function handle(req, res, url, ctx) {
+  const p = url.pathname;
+  if (p !== '/api/report' && p !== '/api/report/draft' && p !== '/api/report/note' && p !== '/api/report/issue') return refuse(ctx, res, 404, 'no such report route');
+
+  /* ── reads ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+  if (req.method === 'GET') {
+    if (p === '/api/report/note' || p === '/api/report/issue') return refuse(ctx, res, 405, `${p} takes POST`);
+    const w = wsFrom(ctx, url.searchParams.get('ws'));
+    if (!w) return refuse(ctx, res, 404, 'no such workspace');
+    let list;
+    try { list = RN.reportsOf(w.root); } catch (e) { return refuse(ctx, res, 500, 'the reports could not be read: ' + String((e && e.message) || e).slice(0, 160)); }
+    if (p === '/api/report') {
+      ctx.json(res, { ok: true, ws: w.id, sig: list.sig, reports: list.reports.map(pageReport), flags: pageFlags(list.flags) });
+      return true;
+    }
+    const cs = cadenceSlot({ cadence: url.searchParams.get('cadence'), slot: url.searchParams.get('slot') });
+    if (cs.error || !cs.slot) return refuse(ctx, res, 400, cs.error || 'slot must be a date, YYYY-MM-DD');
+    const hit = findReport(list, cs.cadence, cs.slot);
+    if (!hit) { ctx.json(res, { ok: true, ws: w.id, sig: list.sig, cadence: cs.cadence, slot: cs.slot, exists: false, flags: pageFlags(list.flags) }); return true; }
+    const file = readFile(w.root, hit.path);
+    if (!file) return refuse(ctx, res, 404, `${hit.path} could not be read`);
+    ctx.json(res, {
+      ok: true, ws: w.id, sig: list.sig, cadence: cs.cadence, slot: cs.slot, exists: true, path: hit.path, status: hit.status,
+      sha: RN.blobSha(file.buf), markdown: file.text, notes: RD.readNotes(file.text), issued: pageReport(hit).issued, edited: hit.edited, flags: pageFlags(list.flags),
+    });
+    return true;
+  }
+  if (req.method !== 'POST') return refuse(ctx, res, 405, `${p} takes GET or POST`);
+  if (p === '/api/report') return refuse(ctx, res, 405, '/api/report takes GET');
+
+  /* ── writes: the guard first, then the one writer ───────────────────────────────────────────────────────────── */
+  const read = await ctx.readJson(req);
+  if (!read.ok) return refuse(ctx, res, 400, 'invalid JSON body');
+  const body = read.body == null ? {} : read.body;
+  const g = p === '/api/report/issue' ? guard.requirePmPress(req, body, { act: 'issue' }) : guard.requirePagePress(req, body);
+  if (!g.ok) { ctx.json(res, g, g.status); return true; }
+  const w = body.ws ? wsFrom(ctx, String(body.ws)) : null;
+  if (!w) return refuse(ctx, res, body.ws ? 404 : 400, body.ws ? 'no such workspace' : 'ws is required');
+  const cs = cadenceSlot(body);
+  if (cs.error) return refuse(ctx, res, 400, cs.error);
+  const root = w.root;
+  const done = (extra) => { ctx.invalidateNeedsAgg(); ctx.json(res, { ok: true, ws: w.id, cadence: cs.cadence, ...extra, sig: RN.reportsOf(root).sig }); return true; };
+  const failed = (r) => { ctx.json(res, { ok: false, error: r.error || 'refused', index: r.index == null ? null : r.index }, r.status || 400); return true; };
+
+  if (p === '/api/report/draft') {
+    // Draft now, or Redraft. A Redraft keeps every note, byte for byte, by the initiative id it was written under.
+    const draft = RD.draftOf(root, { cadence: cs.cadence, slot: cs.slot || undefined });
+    if (!draft || draft.ok === false) return failed(draft || { status: 500, error: 'the drafter answered nothing' });
+    let notes;
+    if (body.redraft === true) {
+      const old = findReport(RN.reportsOf(root), cs.cadence, draft.slot);
+      const file = old ? readFile(root, old.path) : null;
+      notes = file ? RD.readNotes(file.text) : {};
+    }
+    const r = RD.writeDraft(root, draft, { actor: g.actor, notes, fresh: body.redraft !== true });
+    if (!r || r.ok === false) return failed(r || { status: 500, error: 'the writer answered nothing' });
+    return done({ slot: draft.slot, path: r.path, sha: r.sha });
+  }
+
+  if (p === '/api/report/note') {
+    if (!cs.slot) return refuse(ctx, res, 400, 'slot must be a date, YYYY-MM-DD');
+    const id = String(body.id || '');
+    if (!NOTE_ID_RE.test(id)) return refuse(ctx, res, 400, 'id must be an initiative id, report.headline or report.asks');
+    if (typeof body.text !== 'string') return refuse(ctx, res, 400, 'text must be a string');
+    if (body.text.length > MAX_NOTE) return refuse(ctx, res, 413, `a note is at most ${MAX_NOTE} characters`);
+    if (/<!--\s*\/?pmos:note/.test(body.text)) return refuse(ctx, res, 400, 'a note cannot hold a note marker');
+    const old = findReport(RN.reportsOf(root), cs.cadence, cs.slot);
+    const file = old ? readFile(root, old.path) : null;
+    if (!file) return refuse(ctx, res, 404, `there is no ${cs.cadence} draft for ${cs.slot}; press Draft now first`);
+    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 });
+    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 });
+  }
+
+  // Issue. The path comes from the listing, never from the body; the sha is the one the page showed the PM.
+  if (!cs.slot) return refuse(ctx, res, 400, 'slot must be a date, YYYY-MM-DD');
+  if (typeof body.sha !== 'string' || !SHA_RE.test(body.sha)) return refuse(ctx, res, 400, 'sha must be the 40-character sha of the report as it was read');
+  const hit = findReport(RN.reportsOf(root), cs.cadence, cs.slot);
+  if (!hit) return refuse(ctx, res, 404, `there is no ${cs.cadence} report for ${cs.slot}; nothing was issued`);
+  const r = issues.appendFromUi(root, [{ ev: 'issued', cadence: cs.cadence, slot: cs.slot, path: hit.path, sha: body.sha }], { actor: g.actor });
+  if (!r || r.ok === false) return failed(r || { status: 500, error: 'the writer answered nothing' });
+  return done({ slot: cs.slot, path: hit.path, written: (r.written || []).map((x) => ({ cadence: x.cadence, slot: x.slot, path: x.path, sha: x.sha, at: x.at })) });
+}
+
+module.exports = { prefixes, handle };