create-pmos 0.134.0 → 0.136.0

package/workspace/lib/routes-stage-tools.js

@@ -0,0 +1,220 @@
+'use strict';
+/* routes-stage-tools.js — what each workflow stage offers, server side (initiative stage-tools-records; PRD R1 to R8).
+ *
+ *   GET  /api/stage-tools/records?ws&id                 → { ok, ws, id, records: { problem, rice, launch, kill, learnings } }
+ *                                                         each record { data, at, by } or null; rice data adds `score`
+ *   POST /api/stage-tools/records  { ws, id, tool, data } → { ok, ws, id, tool, record }
+ *   GET  /api/stage-tools/rice?ws[&ids=A,B]             → { ok, ws, rows: [{ id, score, rank, reach, impact, confidence, effort, at }] }
+ *   GET  /api/stage-tools/held?ws&id[&board]            → { ok, ws, id, anchor, jira, tickets, breakdown, releases, dates, measurements }
+ *   GET  /api/stage-tools/burndown?ws[&ids=A,B][&board][&sprint=<name>]
+ *                                                       → { ok, available: true, sprint, committed, done, left, daysLeft, needPerDay,
+ *                                                           series: [{ date, remaining, ideal }], tickets, unpointed, readAt }
+ *                                                         | { ok, available: false, reason }
+ *
+ * WHERE THE RECORDS LIVE. <the repository's state folder>/initiative-tools.jsonl (ctx.stateDirFor(w)), the folder the
+ * boards ledger uses: the PM's choice of 2026-10-11, "one append-only file in each board's own state folder". A workspace
+ * with no state folder (an imported one) keeps it in its import overlay, <runtime>/imports/<ws>/initiative-tools.jsonl.
+ *
+ * THE INITIATIVE ID is checked by shape only (letters, digits, . _ -): an imported initiative has no record file, and the
+ * boards ledger may hold ids the record tree does not. A read of an id nobody saved is empty records, never a 404.
+ *
+ * BUILD AND DELIVER. With `board`, the board's own `buildDeliver` line in boards.jsonl is read (missing: on). When it is
+ * off, `tickets` is { source: 'none' } and the burndown is { available: false, reason: 'Jira not enabled on this board' }.
+ *
+ * WHO WRITES. The POST passes pm-guard requirePagePress; `by` is the guard's actor. The factory never writes the file (D65).
+ * NOTHING HERE READS OR WRITES JIRA: tickets come from the cached snapshots of lib/jira-status.js. Nothing is sent outward.
+ */
+const fs = require('fs');
+const path = require('path');
+const guard = require('./pm-guard.js');
+const S = require('./stage-tools.js');
+
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+const BOARD_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+const NO_JIRA = 'Jira not enabled on this board';
+const text = (v) => (typeof v === 'string' ? v : '');
+const bad = (status, error) => ({ status, body: { ok: false, error } });
+
+function wsOf(ctx, id) {
+  const w = ctx.getWs(id || '');
+  return w && (!id || w.id === id) ? w : null;
+}
+const stateRootOf = (ctx) => (ctx && (ctx.runtimeDir || ctx.stateRoot)) || require('./state-root.js').defaultRoot();
+function ledgerFile(ctx, w) {
+  const d = ctx.stateDirFor ? ctx.stateDirFor(w) : null;
+  if (d) return path.join(d, S.LEDGER);
+  try { return path.join(require('./import-overlay.js').overlayDir(stateRootOf(ctx), w.id), S.LEDGER); } catch { return null; }
+}
+function boardsFile(ctx, w) {
+  const d = ctx.stateDirFor ? ctx.stateDirFor(w) : null;
+  return d ? path.join(d, 'boards.jsonl') : null;
+}
+function idsOf(url) {
+  const raw = text(url.searchParams.get('ids'));
+  return raw ? raw.split(',').map((s) => s.trim()).filter((s) => ID_RE.test(s)).slice(0, 500) : null;
+}
+const err = (e) => String((e && e.message) || e || 'error').slice(0, 160);
+
+// ── what PMOS already holds ───────────────────────────────────────────────────────────────────────
+function snapshotTickets(root, id) {
+  try {
+    const snap = require('./jira-status.js').readSnapshot(root, id);
+    return snap ? { readAt: snap.fetchedAt, tickets: [...snap.tickets.values()].map((t) => ({ ...t, initiative: id })) } : null;
+  } catch { return null; }
+}
+function ticketsHeld(root, id, on) {
+  if (!on) return { source: 'none', reason: NO_JIRA, readAt: null, items: [], byCategory: { todo: 0, doing: 0, done: 0 } };
+  const snap = snapshotTickets(root, id);
+  if (!snap) return { source: 'none', reason: 'no Jira read for this initiative yet', readAt: null, items: [], byCategory: { todo: 0, doing: 0, done: 0 } };
+  const items = snap.tickets.map((t) => ({ key: t.key, summary: t.summary, status: t.status, category: t.category, sprint: t.sprint || null,
+    points: typeof t.points === 'number' ? t.points : null, resolved: t.resolved || null, flagged: !!t.flagged, reason: t.reason || null, url: t.url || null, stale: !!t.stale }));
+  const byCategory = { todo: 0, doing: 0, done: 0 };
+  for (const t of items) if (t.category in byCategory) byCategory[t.category]++;
+  return { source: 'jira', readAt: snap.readAt, items, byCategory };
+}
+function planItemsOf(root, id) {
+  try {
+    const P = require('./plan-items.js');
+    const fold = P.readFold(root);
+    const items = Object.values(fold.items).filter((it) => it.initiative === id)
+      .map((it) => ({ id: it.id, source: 'plan', title: it.title, stage: it.stage, state: it.state, owner: it.owner || null, start: it.start || null,
+        due: it.due || null, milestone: !!it.milestone, proposed: !!it.proposed, late: !!it.late }));
+    return { items, progress: P.progressOf(fold, id) };
+  } catch { return { items: [], progress: { done: 0, total: 0, proposed: 0 } }; }
+}
+function pmosTasksOf(ctx, id) {
+  try {
+    const root = require('./routes-roadmap-ops.js').rootOf(ctx);
+    const { repoScript } = require('./repo-script.js');
+    const B = require(repoScript('breakdown-ops.js'));
+    return B.list(root).filter((it) => it && it.initiative === id)
+      .map((it) => ({ id: it.rid, source: 'pmos', title: it.title || '', phase: it.phase || null, state: it.status || null, owner: it.owner || null,
+        points: typeof it.points === 'number' ? it.points : null, due: it.due || null, jira: it.jira_key || null }));
+  } catch { return []; }
+}
+function releasesOf(ctx, id) {
+  try {
+    const { repoScript } = require('./repo-script.js');
+    const R = require(repoScript('releases.js'));
+    const f = path.join(ctx.runtimeDir, 'releases', 'releases.jsonl');
+    let lines = [];
+    try { lines = fs.readFileSync(f, 'utf8').split('\n').filter(Boolean); } catch { return []; }
+    return R.foldReleases(lines).filter((r) => Array.isArray(r.initiative_ids) && r.initiative_ids.includes(id))
+      .map((r) => ({ id: r.id, type: r.type || null, fix_version: r.fix_version || null, deploy_at: r.deploy_at || null, release_at: r.release_at || null,
+        accepted: !!r.accepted_at, scope: r.initiative_ids.slice() }));
+  } catch { return []; }
+}
+function anchorOf(root, id) {
+  try {
+    const fm = require('./jira-tickets.js').recordFm(root, id);
+    const a = fm && (fm.parent_kr || fm.anchor);
+    return typeof a === 'string' && a.trim() ? a.trim().replace(/^["']|["']$/g, '') : null;
+  } catch { return null; }
+}
+function measurementsOf(root, anchor) {
+  if (!anchor) return { anchor: null, latest: null, series: [] };
+  try {
+    const M = require('./measurements.js');
+    const r = M.readMeasurements(root);
+    const series = ((r.byAnchor || {})[anchor] || []).map((m) => ({ value: m.value, target: m.target == null ? null : m.target, unit: m.unit || null, as_of: m.as_of, source: m.source }));
+    return { anchor, latest: M.latest(r, anchor), series };
+  } catch { return { anchor, latest: null, series: [] }; }
+}
+function datesOf(planItems) {
+  const live = planItems.filter((it) => !it.proposed);
+  const dated = live.filter((it) => it.start || it.due);
+  let start = null; let end = null;
+  for (const it of dated) {
+    const s = it.start || it.due; const e = it.due || it.start;
+    if (!start || s < start) start = s;
+    if (!end || e > end) end = e;
+  }
+  return { start, end, dated: dated.length, undated: live.length - dated.length };
+}
+
+function held(ctx, w, id, board) {
+  const on = S.buildDeliverOn(boardsFile(ctx, w), board);
+  const plan = planItemsOf(w.root, id);
+  const tasks = pmosTasksOf(ctx, id);
+  const anchor = anchorOf(w.root, id);
+  const items = [...plan.items, ...tasks];
+  const done = plan.items.filter((it) => !it.proposed && it.state === 'done').length + tasks.filter((t) => /^done$/i.test(String(t.state || ''))).length;
+  const total = plan.items.filter((it) => !it.proposed).length + tasks.length;
+  return {
+    ok: true, ws: w.id, id, anchor, jira: on,
+    tickets: ticketsHeld(w.root, id, on),
+    breakdown: { items, done, total, proposed: plan.progress.proposed || 0 },
+    releases: releasesOf(ctx, id),
+    dates: datesOf(plan.items),
+    measurements: measurementsOf(w.root, anchor),
+  };
+}
+
+function burndownFor(ctx, w, ids, board, sprint) {
+  if (!S.buildDeliverOn(boardsFile(ctx, w), board)) return { ok: true, available: false, reason: NO_JIRA };
+  let list = ids;
+  if (!list) {
+    try { list = require('./jira-status.js').linkedInitiatives(w.root).filter((q) => q.linked).map((q) => q.initiative); } catch { list = []; }
+  }
+  const tickets = []; let readAt = null;
+  for (const id of list) {
+    const snap = snapshotTickets(w.root, id);
+    if (!snap) continue;
+    tickets.push(...snap.tickets);
+    if (snap.readAt && (!readAt || snap.readAt < readAt)) readAt = snap.readAt;   // the oldest read is the honest age
+  }
+  if (!tickets.length) return { ok: true, available: false, reason: 'no Jira read for these initiatives yet' };
+  return { ok: true, ...S.burndown(tickets, { sprint: sprint || null }), readAt };
+}
+
+// ── the routes ────────────────────────────────────────────────────────────────────────────────────
+async function handle(req, res, url, ctx) {
+  const p = url.pathname;
+  const send = (r) => { ctx.json(res, r.body, r.status); return true; };
+  if (!['/api/stage-tools/records', '/api/stage-tools/rice', '/api/stage-tools/held', '/api/stage-tools/burndown'].includes(p)) {
+    return send(bad(404, 'no such stage-tools route'));
+  }
+  if (p === '/api/stage-tools/records' && req.method === 'POST') {
+    const read = await ctx.readJson(req);
+    if (!read.ok) return send(bad(400, 'the body is not JSON'));
+    const body = read.body;
+    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 id = text(body.id);
+    if (!ID_RE.test(id)) return send(bad(400, 'id must be an initiative id (letters, digits, . _ -)'));
+    const c = S.checkData(text(body.tool), body.data);
+    if (!c.ok) return send(bad(400, c.error));
+    const file = ledgerFile(ctx, w);
+    if (!file) return send(bad(409, 'this workspace has no folder to keep the records in'));
+    try { S.appendTool(file, { initiative: id, tool: body.tool, data: c.data }, g.actor); }
+    catch (e) { return send(bad(500, 'the record could not be saved: ' + err(e))); }
+    const rec = S.recordsOf(S.readLedger(file), id)[body.tool];
+    return send({ status: 200, body: { ok: true, ws: w.id, id, tool: body.tool, record: rec } });
+  }
+  if (req.method !== 'GET') return send(bad(405, p === '/api/stage-tools/records' ? 'GET or POST only' : 'GET only'));
+  const w = wsOf(ctx, url.searchParams.get('ws'));
+  if (!w) return send(bad(404, 'no such workspace'));
+  const board = text(url.searchParams.get('board'));
+  if (board && !BOARD_RE.test(board)) return send(bad(400, 'board must be a board id'));
+  if (p === '/api/stage-tools/rice') {
+    const file = ledgerFile(ctx, w);
+    return send({ status: 200, body: { ok: true, ws: w.id, rows: file ? S.riceRank(S.readLedger(file), idsOf(url)) : [] } });
+  }
+  if (p === '/api/stage-tools/burndown') {
+    const sprint = text(url.searchParams.get('sprint')).slice(0, 80);
+    try { return send({ status: 200, body: { ws: w.id, ...burndownFor(ctx, w, idsOf(url), board || null, sprint) } }); }
+    catch (e) { return send(bad(500, 'the burndown could not be read: ' + err(e))); }
+  }
+  const id = text(url.searchParams.get('id'));
+  if (!ID_RE.test(id)) return send(bad(400, 'id must be an initiative id (letters, digits, . _ -)'));
+  if (p === '/api/stage-tools/records') {
+    const file = ledgerFile(ctx, w);
+    return send({ status: 200, body: { ok: true, ws: w.id, id, records: S.recordsOf(file ? S.readLedger(file) : new Map(), id) } });
+  }
+  try { return send({ status: 200, body: held(ctx, w, id, board || null) }); }
+  catch (e) { return send(bad(500, 'what PMOS holds could not be read: ' + err(e))); }
+}
+
+module.exports = { prefixes: ['/api/stage-tools'], handle, held, burndownFor, NO_JIRA };

package/workspace/lib/run-answers.js

@@ -15,7 +15,8 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const actor = require('./actor.js');
-const { appendOutbox } = require('../../scripts/outbox.js');
+const { repoScript } = require('./repo-script.js');
+const { appendOutbox } = require(repoScript('outbox.js'));
 
 const BEHAVIORS = ['allow', 'deny', 'accept', 'answer'];
 const RUN_RE = /^sess-\d+$/;

package/workspace/lib/settings-store.js

@@ -0,0 +1,226 @@
+'use strict';
+/* settings-store.js — the console3 settings that have no home of their own yet (initiative console3-settings).
+ *
+ *   DEFS                                   every setting this store keeps: key → { section, scope, type, options|min|max, def }
+ *   get(stateDir, key, ws)                 the value, or its default; what other modules call to read a setting
+ *   all(stateDir, ws, { env })             every setting with value, default and scope, and the environment overrides
+ *   set(stateDir, key, value, ws)          → { ok: true, value } | { ok: false, status, error }
+ *   reset(stateDir, key, ws)               back to the default
+ *   validate(key, value)                   → null | the reason the value is refused
+ *   overrides(env)                         the environment variables that win over a setting, with their values
+ *
+ * One home per setting: a setting that already has a store (the recording language, the Online record, the TypeSafe key,
+ * validate consent, profiles) is NOT here. The Settings page reads and writes those through their own routes. This file
+ * holds only the settings the console3 features need and that had nowhere to live.
+ *
+ * Files, in the per-user state folder (outside every repository, so no commit or sync carries them):
+ *   <state>/settings.json            settings for this computer
+ *   <state>/settings-ws/<ws>.json    settings for one workspace
+ * Both are written mode 0600 through a temporary file and a rename. A file that cannot be read counts as empty. */
+const fs = require('fs');
+const path = require('path');
+
+const CATEGORIES = Object.freeze(['Discover', 'Plan', 'Do', 'Learn']);
+const TEMPLATES = Object.freeze({
+  product: { name: 'Product', stages: [{ name: 'Discover', cat: 'Discover' }, { name: 'Plan', cat: 'Plan' }, { name: 'Build & Deliver', cat: 'Do' }, { name: 'Monitor & Evaluate', cat: 'Learn' }] },
+  project: { name: 'Project', stages: [{ name: 'Plan', cat: 'Plan' }, { name: 'Execute', cat: 'Do' }, { name: 'Close', cat: 'Learn' }] },
+  simple: { name: 'Simple', stages: [{ name: 'To do', cat: 'Plan' }, { name: 'Doing', cat: 'Do' }, { name: 'Done', cat: 'Learn' }] },
+});
+const AUDIENCES = Object.freeze({ Leadership: [], Team: [] });
+
+const one = (section, scope, options, def) => ({ section, scope, type: 'choice', options, def });
+const bool = (section, scope, def) => ({ section, scope, type: 'bool', def });
+const DEFS = Object.freeze({
+  'ws.start': one('workspaces', 'computer', ['last', 'ask'], 'last'),
+  'ws.briefing': one('workspaces', 'computer', ['one', 'all'], 'one'),
+  'board.template': one('boards', 'ws', ['product', 'project', 'simple'], 'product'),
+  'board.rules': one('boards', 'ws', ['warn', 'off'], 'warn'),
+  'board.templates': { section: 'boards', scope: 'computer', type: 'templates', def: TEMPLATES },
+  'conn.cal.window': one('connectors', 'computer', ['7-14', '14-30', '30-60'], '14-30'),
+  'conn.cal.refresh': one('connectors', 'computer', ['open', 'hour', 'manual'], 'open'),
+  'conn.cal.private': one('connectors', 'computer', ['busy', 'hide', 'title'], 'busy'),
+  'conn.jira.refresh': one('connectors', 'ws', ['open', '15', 'manual'], '15'),
+  'conn.wispr.wait': one('connectors', 'computer', ['2', '5', '10'], '5'),
+  'conn.sender': one('connectors', 'ws', ['none', 'slack', 'gmail'], 'none'),
+  'rec.sources': one('recording', 'computer', ['both', 'mic', 'meeting'], 'both'),
+  'rec.guard': bool('recording', 'computer', true),
+  'rec.echo': bool('recording', 'computer', true),
+  'rec.settle': bool('recording', 'computer', false),
+  'rec.final': bool('recording', 'computer', true),
+  'rec.vocab': { section: 'recording', scope: 'ws', type: 'text', max: 400, def: '' },
+  'rec.retain': one('recording', 'computer', ['never', '90', '30', '7'], 'never'),
+  'time.zone': { section: 'time', scope: 'computer', type: 'zone', def: '' },
+  'time.weekStart': one('time', 'computer', ['mon', 'sun'], 'mon'),
+  'time.workStart': { section: 'time', scope: 'computer', type: 'hour', min: 5, max: 12, def: 9 },
+  'time.workEnd': { section: 'time', scope: 'computer', type: 'hour', min: 13, max: 23, def: 18 },
+  'time.prep': one('time', 'computer', ['15', '30', '45', '60'], '30'),
+  'time.buffer': one('time', 'computer', ['0', '5', '10', '15'], '10'),
+  'time.tint': bool('time', 'computer', true),
+  'time.strip': bool('time', 'computer', true),
+  'share.mode': one('sharing', 'ws', ['draft', 'send'], 'draft'),
+  'share.audiences': { section: 'sharing', scope: 'ws', type: 'audiences', def: AUDIENCES },
+  'sess.max': one('sessions', 'computer', ['2', '3', '4', '6', '8'], '4'),
+  'sess.idle': one('sessions', 'computer', ['15', '30', '60', 'never'], '30'),
+  'sess.share': one('sessions', 'computer', ['ws', 'job'], 'ws'),
+  'look.start': one('appearance', 'computer', ['brief', 'cal', 'work', 'init', 'rep'], 'brief'),
+  'upd.check': one('updates', 'computer', ['press', 'daily'], 'press'),
+  'upd.apply': one('updates', 'computer', ['ask', 'idle'], 'ask'),
+  'upd.kits': one('updates', 'computer', ['all', 'each'], 'all'),
+  'upd.channel': one('updates', 'computer', ['stable', 'early'], 'stable'),
+});
+
+/* The environment variables that win over a setting, here or in a setting's own store. `key` names the setting the page
+ * shows; `off` is the value that turns the thing off, or null when any value wins. */
+const ENV = Object.freeze([
+  { key: 'notes.language', env: 'PMOS_WHISPER_LANG', off: null, effect: 'Every line is transcribed in this language, whatever the picker says.' },
+  { key: 'rec.echo', env: 'PMOS_NOTES_ECHO', off: 'off', effect: 'Echo removal is off on this computer.' },
+  { key: 'rec.final', env: 'PMOS_NOTES_FINAL', off: 'off', effect: 'The pass after Stop is off on this computer.' },
+  { key: 'notes.wispr', env: 'PMOS_NOTES_WISPR', off: 'off', effect: 'Wispr Flow notes are not fetched on this computer.' },
+  { key: 'notes.engine', env: 'PMOS_NOTES_QWEN', off: 'off', effect: 'Qwen3-ASR is not used on this computer.' },
+]);
+
+const WS_ID = /^[A-Za-z0-9_-]{1,80}$/;
+const clone = (v) => (v && typeof v === 'object' ? JSON.parse(JSON.stringify(v)) : v);
+const fileOf = (stateDir, ws) => (ws ? path.join(stateDir, 'settings-ws', ws + '.json') : path.join(stateDir, 'settings.json'));
+
+function readFile(f) {
+  try {
+    const st = fs.lstatSync(f);
+    if (!st.isFile()) return {};
+    const o = JSON.parse(fs.readFileSync(f, 'utf8'));
+    return o && typeof o === 'object' && !Array.isArray(o) ? o : {};
+  } catch { return {}; }
+}
+function writeFile(f, obj) {
+  fs.mkdirSync(path.dirname(f), { recursive: true, mode: 0o700 });
+  try { if (fs.lstatSync(f).isSymbolicLink()) throw new Error('the settings file is a symbolic link; it was not written'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  const tmp = f + '.' + process.pid + '.' + Date.now() + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, f);
+}
+
+/** Which file a key lives in: the workspace's for a workspace setting (ws required), else this computer's. */
+function where(stateDir, key, ws) {
+  const d = DEFS[key];
+  if (!d) return { ok: false, status: 400, error: `no setting is called ${JSON.stringify(String(key))}` };
+  if (d.scope !== 'ws') return { ok: true, file: fileOf(stateDir, null), d };
+  if (!ws || !WS_ID.test(String(ws))) return { ok: false, status: 400, error: `${key} belongs to a workspace: say which one with ws` };
+  return { ok: true, file: fileOf(stateDir, String(ws)), d };
+}
+
+function validName(s, max) { return typeof s === 'string' && s.trim().length > 0 && s.trim().length <= max && !/[\u0000-\u001f]/.test(s); }
+
+function validate(key, value) {
+  const d = DEFS[key];
+  if (!d) return `no setting is called ${JSON.stringify(String(key))}`;
+  switch (d.type) {
+    case 'choice': return d.options.includes(value) ? null : `${key} must be one of ${d.options.join(', ')}`;
+    case 'bool': return typeof value === 'boolean' ? null : `${key} must be true or false`;
+    case 'text': return typeof value === 'string' && value.length <= d.max && !/[\u0000-\u0008\u000b-\u001f]/.test(value) ? null : `${key} must be text of at most ${d.max} characters`;
+    case 'hour': return Number.isInteger(value) && value >= d.min && value <= d.max ? null : `${key} must be a whole hour from ${d.min} to ${d.max}`;
+    case 'zone': {
+      if (value === '') return null;
+      if (typeof value !== 'string' || value.length > 64) return `${key} must be a time zone such as Asia/Jakarta, or empty for this computer's`;
+      try { new Intl.DateTimeFormat('en', { timeZone: value }); return null; } catch { return `${value} is not a time zone this computer knows`; }
+    }
+    case 'templates': {
+      if (!value || typeof value !== 'object' || Array.isArray(value)) return `${key} must name the templates`;
+      const ids = Object.keys(value);
+      if (ids.join() !== Object.keys(TEMPLATES).join()) return `${key} must keep the templates ${Object.keys(TEMPLATES).join(', ')}`;
+      for (const id of ids) {
+        const t = value[id];
+        if (!t || !validName(t.name, 40)) return `the ${id} template needs a name of at most 40 characters`;
+        if (!Array.isArray(t.stages) || t.stages.length < 1 || t.stages.length > 12) return `the ${id} template needs 1 to 12 stages`;
+        const seen = new Set();
+        for (const s of t.stages) {
+          if (!s || !validName(s.name, 40)) return `every stage of the ${id} template needs a name of at most 40 characters`;
+          if (!CATEGORIES.includes(s.cat)) return `a stage's category must be one of ${CATEGORIES.join(', ')}`;
+          const n = s.name.trim().toLowerCase();
+          if (seen.has(n)) return `the ${id} template has two stages called ${s.name.trim()}`;
+          seen.add(n);
+        }
+      }
+      return null;
+    }
+    case 'audiences': {
+      if (!value || typeof value !== 'object' || Array.isArray(value)) return `${key} must name the audiences`;
+      const names = Object.keys(value);
+      if (names.length < 1 || names.length > 8) return 'keep 1 to 8 audiences';
+      for (const a of names) {
+        if (!validName(a, 40)) return 'an audience needs a name of at most 40 characters';
+        const p = value[a];
+        if (!Array.isArray(p) || p.length > 30 || !p.every((x) => validName(x, 60))) return `the ${a} audience must list at most 30 people, each a name of at most 60 characters`;
+      }
+      return null;
+    }
+    default: return `${key} cannot be set`;
+  }
+}
+
+/** Tidy a valid value before it is stored: names trimmed. */
+function normal(key, value) {
+  const t = DEFS[key].type;
+  if (t === 'templates') return Object.fromEntries(Object.entries(value).map(([id, x]) => [id, { name: x.name.trim(), stages: x.stages.map((s) => ({ name: s.name.trim(), cat: s.cat })) }]));
+  if (t === 'audiences') return Object.fromEntries(Object.entries(value).map(([a, p]) => [a.trim(), [...new Set(p.map((x) => x.trim()))]]));
+  return value;
+}
+
+function get(stateDir, key, ws) {
+  const w = where(stateDir, key, ws);
+  if (!w.ok) return DEFS[key] ? clone(DEFS[key].def) : undefined;
+  const v = readFile(w.file)[key];
+  return v === undefined || validate(key, v) ? clone(w.d.def) : v;
+}
+
+/** A cross-setting rule: shares can go out on schedule only once a sender is chosen for the workspace. */
+function blockedBy(stateDir, key, value, ws) {
+  if (key === 'share.mode' && value === 'send' && get(stateDir, 'conn.sender', ws) === 'none') return 'choose a sender in Connectors before shares go out on schedule';
+  return null;
+}
+
+function set(stateDir, key, value, ws) {
+  const w = where(stateDir, key, ws);
+  if (!w.ok) return w;
+  const bad = validate(key, value);
+  if (bad) return { ok: false, status: 400, error: bad };
+  const blocked = blockedBy(stateDir, key, value, ws);
+  if (blocked) return { ok: false, status: 409, error: blocked };
+  const cur = readFile(w.file);
+  cur[key] = normal(key, value);
+  // a sender taken away puts shares back to drafts
+  if (key === 'conn.sender' && value === 'none' && cur['share.mode'] === 'send') delete cur['share.mode'];
+  try { writeFile(w.file, cur); } catch (e) { return { ok: false, status: 500, error: e.message }; }
+  return { ok: true, value: clone(cur[key]) };
+}
+
+function reset(stateDir, key, ws) {
+  const w = where(stateDir, key, ws);
+  if (!w.ok) return w;
+  const cur = readFile(w.file);
+  if (key in cur) { delete cur[key]; try { writeFile(w.file, cur); } catch (e) { return { ok: false, status: 500, error: e.message }; } }
+  return { ok: true, value: clone(w.d.def) };
+}
+
+function overrides(env = process.env) {
+  return ENV.filter((o) => env[o.env] !== undefined && env[o.env] !== '' && (o.off === null || String(env[o.env]) === o.off))
+    .map((o) => ({ key: o.key, env: o.env, value: String(env[o.env]).slice(0, 40), effect: o.effect }));
+}
+
+function all(stateDir, ws, { env = process.env } = {}) {
+  const okWs = ws && WS_ID.test(String(ws)) ? String(ws) : null;
+  const mine = readFile(fileOf(stateDir, null));
+  const theirs = okWs ? readFile(fileOf(stateDir, okWs)) : {};
+  const settings = Object.entries(DEFS).map(([key, d]) => {
+    const src = d.scope === 'ws' ? theirs : mine;
+    const has = src[key] !== undefined && !validate(key, src[key]);
+    const out = { key, section: d.section, scope: d.scope, type: d.type, def: clone(d.def), value: has ? clone(src[key]) : clone(d.def), changed: has && JSON.stringify(src[key]) !== JSON.stringify(d.def) };
+    if (d.options) out.options = d.options.slice();
+    if (d.type === 'hour') { out.min = d.min; out.max = d.max; }
+    if (d.type === 'text') out.max = d.max;
+    if (d.scope === 'ws' && !okWs) out.value = clone(d.def);
+    return out;
+  });
+  return { settings, overrides: overrides(env), categories: CATEGORIES.slice() };
+}
+
+module.exports = { DEFS, ENV, CATEGORIES, TEMPLATES, get, set, reset, all, validate, overrides, fileOf };