create-pmos 0.240.0 → 0.242.0

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

@@ -0,0 +1,619 @@
+'use strict';
+/* routes-report-structure.js — the report structure step's routes, its jobs, the source checks and the draft gate (initiative report-structure).
+ *
+ *   GET  /api/report-structure?ws&id              → { ok, setup: { id, name, cadence }, structure }   (lib/report-structure.js structureAnswer)
+ *   GET  /api/report-structure/version?ws&id&n    → { ok, plan }
+ *   POST /api/report-structure/turn   { ws, id, text }            → { ok, running: true }   starts ONE report-structure job; 409 while one runs
+ *   POST /api/report-structure/accept { ws, id, n }                → { ok, structure, brief, charts: [ids] }   "Use this structure": new charts to charts.jsonl, brief.md
+ *   POST /api/report-structure/revert { ws, id, n }                → { ok, structure }
+ *   POST /api/report-structure/source { ws, id, source }           → { ok, structure }   S<n+1> = the current plan + the source; a Chrome or computer source starts its check
+ *   POST /api/report-structure/remove { ws, id, kind, ref }        → { ok, structure }   S<n+1> without a chart, a source or a section; a fixed section is 400
+ *   POST /api/report-structure/check  { ws, id, source }           → { ok, check }       starts (or restarts) the check of a Chrome or computer source
+ *   GET  /api/report-structure/check?ws&id&source                  → { ok, check }
+ *   POST /api/report-structure/dry    { ws, id, n? }               → { ok, running: true }   starts ONE report-structure-dry job
+ *   GET  /api/report-structure/dry?ws&id&run                       → { ok, dry }
+ *   GET  /api/charts?ws                                            → { ok, charts: [chart + { users }] }
+ *   GET  /api/charts/one?ws&id                                     → { ok, chart }
+ *
+ * WHO WRITES. Every POST passes pm-guard requirePagePress, and a request with an agent session header is refused first (403), as
+ * routes-report-design.js does. A job's output is data: lib/report-structure.js validates a plan or a dry result before anything lands.
+ *
+ * THE JOBS. A turn and a dry run start ONE headless run each (lib/headless.js kinds report-structure and report-structure-dry; origins
+ * `report-structure:<id>` and `report-structure-dry:<id>`), in the report's folder, with the skill and a block that names the files. A run may write
+ * one file, structure/pending/<job>.json, and prints a JSON result. One job per report at a time. A failed, stopped or timed-out run, or output the
+ * validator refuses, appends an 'error' line with the reason and changes nothing.
+ *
+ * THE SOURCE CHECK. A Chrome or computer source is checked by an INTERACTIVE session (no headless kind: the browser tools need a pane) started as
+ * Work's approved steps start (server.js STEP_FLAGS: --chrome and an allow rule for the browser tools only), with the skill report-source-check. The
+ * session writes checks/pending/<run>.json; the server validates it and writes checks/<source>.json. A computer source starts a session only when
+ * the PM's own Claude Code settings allow a computer-use tool; otherwise its `session` step is Needs you and nothing starts.
+ * Env PMOS_REPORT_CHECK_STUB ('pass' | 'fail' | a path to a JSON file { default?, <sourceId>? }: 'pass' or 'fail') answers a check without a session,
+ * for tests. PMOS_REPORT_CHECK_PLATFORM names the platform for the `mac` step, for tests.
+ *
+ * THE DRAFT GATE. A scheduled draft of a report with a saved structure (server.js fireSchedule → beforeDraft) re-checks each Chrome or computer
+ * source first. When all pass the draft starts at once. When one fails the draft waits (structure/hold.json), report-structure-needs.js shows a Work
+ * row "Check <source> for <report>", and sweep() starts the draft when every check passes, or after 4 hours without the failing source
+ * (PMOS_REPORT_HOLD_MS), with a note in the draft job's block. The draft never guesses a number.
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const guard = require('./pm-guard.js');
+const S = require('./report-structure.js');
+const CS = require('./charts-store.js');
+const RS = require('./report-setups.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 POSTS = ['turn', 'accept', 'revert', 'source', 'remove', 'check', 'dry'];
+const HOLD_MS = 4 * 3600 * 1000;
+const CHECK_MS = 10 * 60 * 1000;
+const STEP_FLAGS_FALLBACK = [{ flag: '--chrome' }, { flag: '--allowedTools', value: 'mcp__claude-in-chrome' }];
+
+const jobs = new Map();       // `${root}\0${id}` → { id, kind, since, turn, pending, sessionId, base, n }
+const checkJobs = new Map();  // `${root}\0${id}\0${source}` → { run, since, pending, sessionId, kind }
+let lastCtx = null;
+const keyOf = (root, id) => `${path.resolve(String(root))}\u0000${id}`;
+const checkKey = (root, id, source) => `${keyOf(root, id)}\u0000${source}`;
+
+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, cadence: (s.schedule && s.schedule.cadence) || s.id, purpose: s.purpose, audience: s.audience, sources: s.sources, sections: s.sections };
+  // A report with no setup (a hand-written cadence) can be shaped when its folder exists.
+  try { if (fs.existsSync(S.paths(root, id).folder)) return { id, name: id, cadence: id, purpose: '', audience: '', sources: [], sections: [] }; } catch { /* not a report id */ }
+  return null;
+}
+const pub = (s) => ({ id: s.id, name: s.name, cadence: s.cadence });
+function runningOf(root, id) {
+  const j = jobs.get(keyOf(root, id));
+  return j ? { since: j.since, turn: j.turn, kind: j.kind } : null;
+}
+const answerOf = (root, id) => S.structureAnswer(root, id, { running: runningOf(root, id) });
+const storeIds = (root) => new Set(CS.stateOf(root).keys());
+
+// ── the job ─────────────────────────────────────────────────────────────────────────────────────────────────
+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;
+}
+
+function promptFor(skill, { kind, root, id, setup, st, turnText, pending, n }) {
+  const p = S.paths(root, id);
+  const lines = [`- Mode: ${kind === 'dry' ? 'dry' : 'turn'}`, `- Report: ${setup.name} (${id})`, `- Today: ${new Date().toISOString().slice(0, 10)}`,
+    `- Purpose on file: ${setup.purpose ? String(setup.purpose).replace(/\s+/g, ' ') : 'none'}`, `- Audience on file: ${setup.audience ? String(setup.audience).replace(/\s+/g, ' ') : 'none'}`,
+    `- Schedule: ${setup.cadence}`, `- Repository: ${p.abs}`, `- Chart store: ${CS.paths(root).file}`];
+  const cur = kind === 'dry' ? n : st.current;
+  if (kind === 'dry') {
+    lines.push(`- Version to try: S${n} (${path.join(p.versions, `S${n}.json`)})`);
+  } else {
+    lines.push(`- Turn: ${turnText ? turnText.replace(/\s+/g, ' ') : 'none'}`);
+    lines.push(`- Previous version: ${cur != null ? path.join(p.versions, `S${cur}.json`) : 'none (this is the first version)'}`);
+    lines.push(`- Version number to make: S${S.nextN(st)}`);
+  }
+  lines.push(`- Output path: ${pending}`);
+  return `${skill}\n\nThis job:\n${lines.join('\n')}\n\nWrite the JSON to the output path, then print the JSON result. Send nothing.\r`;
+}
+
+/** Start a job. spec: { kind: 'turn' | 'dry', turnText?, n? }. → { ok, running } | { ok: false, status, error } */
+function startJob(ctx, w, id, spec) {
+  const root = w.root;
+  const key = keyOf(root, id);
+  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 kindName = spec.kind === 'dry' ? 'report-structure-dry' : 'report-structure';
+  const origin = `${kindName}:${id}`;
+  if (headless.kindFor({ agent: 'claude', origin }) !== kindName) return { ok: false, status: 409, error: 'Background runs are switched off here (PMOS_HEADLESS=off), so PMOS cannot work on the structure.' };
+  const skill = typeof ctx.skillPrompt === 'function' ? ctx.skillPrompt(kindName, w) : null;
+  if (!skill) return { ok: false, status: 500, error: `the ${kindName} skill is not installed` };
+  const setup = setupOf(root, id) || { id, name: id, cadence: id };
+  const st = S.stateOf(root, id);
+  const p = S.paths(root, id);
+  const run = S.newRun();
+  const pending = path.join(p.pending, `${run}.json`);
+  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 job = { id: run, kind: spec.kind, since: new Date().toISOString(), turn: spec.kind === 'dry' ? `Trying S${spec.n} with real data` : (spec.turnText || 'First version'), pending, sessionId: null, base: st.current, n: spec.n || null, kindName };
+  jobs.set(key, job);
+  let s = null;
+  try {
+    s = ctx.spawnSession({ name: spec.kind === 'dry' ? 'Report structure · real data' : 'Report structure', agent: 'claude', ws: w.id, origin, cwd: p.rel,
+      initialInput: promptFor(skill, { kind: spec.kind, root, id, setup, st, turnText: spec.turnText, pending, n: spec.n }), writePaths: [pending], onDone: (r) => finish(w, id, job, r) });
+  } catch (e) { s = { state: 'exited', note: String((e && e.message) || e) }; }
+  if (!s || s.state === 'exited' || s.headless !== kindName) {
+    jobs.delete(key);
+    if (s && s.headless !== kindName && 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 run: ' + ((s && s.note) || 'no background run') };
+  }
+  job.sessionId = s.id;
+  return { ok: true, running: true };
+}
+
+function finish(w, id, job, r) {
+  const root = w.root;
+  const key = keyOf(root, id);
+  if (jobs.get(key) === job) jobs.delete(key);
+  const mode = job.kind === 'dry' ? 'dry' : 'turn';
+  const fail = (why) => {
+    try {
+      if (mode === 'dry') S.append(root, id, { ev: 'dry', run: job.id, n: job.n, ok: false });
+      S.append(root, id, { ev: 'error', text: why, mode });
+    } 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 raw = null;
+    try { raw = fs.readFileSync(job.pending, 'utf8'); } catch { raw = null; }
+    let data = null;
+    if (raw) { try { data = JSON.parse(raw); } catch { data = null; } }
+    if (!data && out && isObj(out.plan) && mode === 'turn') data = out.plan;
+    if (!data && out && isObj(out.dry) && mode === 'dry') data = out.dry;
+    const what = mode === 'dry' ? 'real-data run' : 'structure run';
+    if (!ok && !data) {
+      fail(r && r.timedOut ? `The ${what} took too long and was stopped (${r.note || 'timed out'}).` : r && r.stopped ? `The ${what} was stopped.`
+        : `The ${what} failed: ${(r && r.note) || 'no result'}${res.text ? '. ' + String(res.text).replace(/\s+/g, ' ').slice(0, 300) : ''}`);
+    } else if (!data) fail(`The ${what} ended without a result. Nothing changed.`);
+    else if (mode === 'turn') {
+      const v = S.landVersion(root, id, data, { turn: job.turn, answer: out && typeof out.answer === 'string' ? out.answer : null, questions: out && out.questions, options: out && out.options, from: 'turn', charts: storeIds(root) });
+      if (!v.ok) fail(`The plan could not be used: ${v.error}. Nothing changed.`);
+    } else {
+      const plan = S.readVersion(root, id, job.n);
+      const d = plan ? S.validateDry({ n: job.n, ...data }, plan) : { ok: false, error: 'the version is gone' };
+      if (!d.ok) fail(`The real-data result could not be used: ${d.error}. Nothing was saved.`);
+      else {
+        S.writeDry(root, id, job.id, d.dry);
+        S.append(root, id, { ev: 'dry', run: job.id, n: job.n, ok: true });
+      }
+    }
+  } catch (e) { fail('The run result could not be read: ' + String((e && e.message) || e).slice(0, 200)); }
+  try { fs.unlinkSync(job.pending); } catch { /* not written */ }
+}
+
+/** A turn that has no answer and no job in this server (the workspace restarted mid-run) gets an error line. */
+function settleStale(root, id) {
+  if (jobs.has(keyOf(root, id))) return;
+  const ev = S.readEvents(root, id);
+  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) S.append(root, id, { ev: 'error', text: 'The structure run stopped when the workspace restarted. Send the turn again.', mode: 'turn' });
+}
+
+// ── the source checks ───────────────────────────────────────────────────────────────────────────────────────
+/** The settings files Claude Code reads for this repository: the user's, the project's and the project's local file. */
+function claudeSettings(root) {
+  const files = [path.join(os.homedir(), '.claude', 'settings.json'), path.join(path.resolve(String(root)), '.claude', 'settings.json'), path.join(path.resolve(String(root)), '.claude', 'settings.local.json')];
+  const out = [];
+  for (const f of files) { try { const o = JSON.parse(fs.readFileSync(f, 'utf8')); if (isObj(o)) out.push(o); } catch { /* none */ } }
+  return out;
+}
+/** The allow rule that lets a session use computer use, from the PM's own settings, or null. Only a plain `mcp__<server>` rule is passed on. */
+function computerRule(root) {
+  for (const s of claudeSettings(root)) {
+    const allow = isObj(s.permissions) && Array.isArray(s.permissions.allow) ? s.permissions.allow : [];
+    for (const rule of allow) if (typeof rule === 'string' && /^mcp__[A-Za-z0-9_-]*(?:computer|desktop)[A-Za-z0-9_-]*(?:__[A-Za-z0-9_-]+)?$/i.test(rule)) return rule;
+  }
+  return null;
+}
+const platformOf = (ctx) => String((ctx && ctx.platform) || process.env.PMOS_REPORT_CHECK_PLATFORM || process.platform);
+
+function sourceOf(root, id, sourceId, planOverride) {
+  const st = S.stateOf(root, id);
+  const plan = planOverride || (st.current != null ? S.readVersion(root, id, st.current) : null);
+  const src = plan && plan.sources.find((s) => s.id === sourceId);
+  return src ? { src, plan } : null;
+}
+const stepsOf = (kind) => S.CHECK_STEPS[kind].map(([sid, label]) => ({ id: sid, label, state: 'waiting', reason: '' }));
+
+function stubFor(sourceId) {
+  const v = String(process.env.PMOS_REPORT_CHECK_STUB || '').trim();
+  if (!v) return null;
+  if (v === 'pass' || v === 'fail') return v;
+  try {
+    const o = JSON.parse(fs.readFileSync(v, 'utf8'));
+    const x = isObj(o) ? (o[sourceId] || o.default) : null;
+    return x === 'pass' || x === 'fail' ? x : 'pass';
+  } catch { return 'pass'; }
+}
+function stubSteps(kind, name, how) {
+  const steps = stepsOf(kind).map((s) => ({ ...s, state: 'works' }));
+  if (how === 'fail') {
+    const at = steps.findIndex((s) => s.id === 'signed-in');
+    steps[at] = { ...steps[at], state: 'needs-you', reason: `You are not signed in to ${name}. Sign in, then check again.` };
+    steps[at + 1] = { ...steps[at + 1], state: 'waiting', reason: '' };
+  }
+  return steps;
+}
+
+/** Write the result of a check (a session's answer, a stub or a failure). `fixed` steps (the server's own) win over what the session wrote. */
+function finishCheck(root, id, sourceId, kind, steps, { endSession, job } = {}) {
+  const ok = steps.every((s) => s.state === 'works');
+  const check = { source: sourceId, kind, at: new Date().toISOString(), running: false, ok, steps };
+  S.writeCheck(root, id, check);
+  S.append(root, id, { ev: 'check', source: sourceId, ok, steps });
+  const key = checkKey(root, id, sourceId);
+  const cur = checkJobs.get(key);
+  if (cur && (!job || cur === job)) {
+    checkJobs.delete(key);
+    if (cur.sessionId && typeof endSession === 'function') { try { endSession(cur.sessionId); } catch { /* best effort */ } }
+  }
+  if (cur && cur.pending) { try { fs.unlinkSync(cur.pending); } catch { /* none */ } }
+  return check;
+}
+function failSteps(kind, stepId, reason, base) {
+  const steps = (base || stepsOf(kind)).map((s) => ({ ...s }));
+  const at = steps.findIndex((s) => s.id === stepId);
+  if (at >= 0) steps[at] = { ...steps[at], state: 'needs-you', reason };
+  for (let i = at + 1; i < steps.length; i++) if (steps[i].state !== 'works') steps[i] = { ...steps[i], state: 'waiting', reason: '' };
+  return steps;
+}
+
+/** Start (or restart) the check of one Chrome or computer source. → { ok, check } | refusal. Never throws. */
+function startCheck(ctx, w, id, sourceId, { plan } = {}) {
+  try {
+    const root = w.root;
+    const f = sourceOf(root, id, sourceId, plan);
+    if (!f) return { ok: false, status: 404, error: 'no such source in this structure' };
+    const kind = f.src.kind;
+    if (kind !== 'chrome' && kind !== 'computer') return { ok: false, status: 400, error: 'only a Chrome or a computer source has a check' };
+    const key = checkKey(root, id, sourceId);
+    if (checkJobs.has(key)) return { ok: false, status: 409, error: 'this source is being checked now' };
+    const base = stepsOf(kind);
+    const writeRunning = (steps) => S.writeCheck(root, id, { source: sourceId, kind, at: new Date().toISOString(), running: true, ok: false, steps });
+    const stub = stubFor(sourceId);
+    // the server's own step: PMOS runs on this Mac (a stub stands in for the Mac and the session)
+    const mac = stub || platformOf(ctx) === 'darwin' ? { state: 'works', reason: '' } : { state: 'needs-you', reason: 'PMOS can read a Chrome page or an app only on a Mac. This computer is not one.' };
+    base[0] = { ...base[0], ...mac };
+    if (mac.state !== 'works') return { ok: true, check: finishCheck(root, id, sourceId, kind, base) };
+    // computer use is only used when the PM's own Claude Code settings allow a computer-use tool; otherwise nothing starts (a stub does not change that)
+    const rule = kind === 'computer' ? computerRule(root) : null;
+    if (kind === 'computer' && !rule) return { ok: true, check: finishCheck(root, id, sourceId, kind, failSteps(kind, 'session', 'Computer use is not available in your Claude Code settings', base)) };
+    if (stub) {
+      const run = S.newRun();
+      const job = { run, since: Date.now(), pending: null, sessionId: null, kind };
+      checkJobs.set(key, job);
+      writeRunning(base);
+      const ms = Number(process.env.PMOS_REPORT_CHECK_STUB_MS) >= 0 ? Number(process.env.PMOS_REPORT_CHECK_STUB_MS) : 150;
+      const t = setTimeout(() => { try { finishCheck(root, id, sourceId, kind, stubSteps(kind, f.src.name, stub), { job }); } catch { /* the folder is gone */ } }, ms);
+      if (t.unref) t.unref();
+      return { ok: true, check: S.readCheck(root, id, sourceId) };
+    }
+    let flags = null;
+    if (kind === 'chrome') flags = Array.isArray(ctx.stepFlags) ? ctx.stepFlags : STEP_FLAGS_FALLBACK;
+    else flags = [{ flag: '--allowedTools', value: rule }];
+    if (typeof ctx.spawnSession !== 'function') return { ok: true, check: finishCheck(root, id, sourceId, kind, failSteps(kind, 'session', 'This workspace cannot start a session', base)) };
+    const skill = typeof ctx.skillPrompt === 'function' ? ctx.skillPrompt('report-source-check', w) : null;
+    if (!skill) return { ok: true, check: finishCheck(root, id, sourceId, kind, failSteps(kind, 'session', 'The report-source-check skill is not installed', base)) };
+    const p = S.paths(root, id);
+    const run = S.newRun();
+    const pending = path.join(p.checksPending, `${run}.json`);
+    fs.mkdirSync(p.checksPending, { recursive: true });
+    const users = f.plan.charts.filter((c) => c.source === sourceId);
+    const lines = [`- Source: ${f.src.name} (${sourceId})`, `- Kind: ${kind === 'chrome' ? 'chrome (a page read in Claude in Chrome)' : 'computer (an app on this Mac, computer use)'}`,
+      `- ${kind === 'chrome' ? 'Address' : 'App'}: ${f.src.ref || 'not said'}`, `- Report: ${(setupOf(root, id) || { name: id }).name} (${id})`,
+      `- What it is used for: ${f.src.use || 'not said'}`,
+      `- Numbers to read: ${users.length ? users.map((c) => `${c.name || c.id} (${c.from || 'not said'}; ${c.how || 'not said'})`).join(' | ') : 'none named yet'}`,
+      `- Step ids to report: ${S.CHECK_STEPS[kind].map(([sid]) => sid).join(', ')}`, `- Output path: ${pending}`];
+    const job = { run, since: Date.now(), pending, sessionId: null, kind };
+    checkJobs.set(key, job);
+    writeRunning(base);
+    let s = null;
+    try {
+      s = ctx.spawnSession({ name: 'Report source check', agent: 'claude', ws: w.id, origin: `report-source-check:${id}:${sourceId}`, cwd: p.rel,
+        initialInput: `${skill}\n\nThis job:\n${lines.join('\n')}\n\nWrite the JSON to the output path, then close your tab and stop. Send and change nothing.\r`, launchFlags: flags });
+    } catch (e) { s = { state: 'exited', note: String((e && e.message) || e) }; }
+    if (!s || s.state === 'exited') return { ok: true, check: finishCheck(root, id, sourceId, kind, failSteps(kind, 'session', `A session could not start: ${(s && s.note) || 'no session'}`, base), { job }) };
+    job.sessionId = s.id;
+    return { ok: true, check: S.readCheck(root, id, sourceId) };
+  } catch (e) { return { ok: false, status: 500, error: String((e && e.message) || e) }; }
+}
+
+/** Collect the answers of the check sessions of one report; fail a check that took too long or whose server restarted. */
+function settleChecks(ctx, w, id) {
+  const root = w.root;
+  const pre = `${keyOf(root, id)}\u0000`;
+  const now = Date.now();
+  for (const [k, job] of [...checkJobs.entries()]) {
+    if (!k.startsWith(pre)) continue;
+    const sourceId = k.slice(pre.length);
+    if (!job.pending) continue;   // a stub finishes by itself
+    const cur = S.readCheck(root, id, sourceId);
+    const base = cur && Array.isArray(cur.steps) ? cur.steps : stepsOf(job.kind);
+    let raw = null; let age = 0;
+    try { raw = fs.readFileSync(job.pending, 'utf8'); age = now - fs.statSync(job.pending).mtimeMs; } catch { raw = null; }
+    if (raw != null) {
+      let data = null; try { data = JSON.parse(raw); } catch { data = null; }
+      if (!data && age < 20000) continue;   // still being written
+      const v = data ? S.validateCheck(data, job.kind) : { ok: false, error: 'the check result is not JSON' };
+      if (v.ok) {
+        const steps = v.steps.map((s) => (s.id === 'mac' ? base.find((b) => b.id === 'mac') || s : s));   // the server's own step wins
+        finishCheck(root, id, sourceId, job.kind, steps, { endSession: ctx && ctx.endSession, job });
+      } else finishCheck(root, id, sourceId, job.kind, failSteps(job.kind, 'read', `The check answered something PMOS could not use: ${v.error}`, base), { endSession: ctx && ctx.endSession, job });
+    } else if (now - job.since > CHECK_MS) {
+      finishCheck(root, id, sourceId, job.kind, failSteps(job.kind, 'session', 'The check session did not answer in 10 minutes. Check again.', base), { endSession: ctx && ctx.endSession, job });
+    }
+  }
+  // a check marked running that no job of this server holds (the workspace restarted) is over
+  for (const [sourceId, c] of Object.entries(S.readChecks(root, id))) {
+    if (c.running && !checkJobs.has(checkKey(root, id, sourceId)) && now - Date.parse(c.at) > 90000) {
+      try { finishCheck(root, id, sourceId, c.kind, failSteps(c.kind, 'session', 'The check stopped when the workspace restarted. Check again.', c.steps)); } catch { /* gone */ }
+    }
+  }
+}
+
+// ── the draft gate ──────────────────────────────────────────────────────────────────────────────────────
+const holdFile = (root, id) => path.join(S.paths(root, id).dir, 'hold.json');
+function readHold(root, id) { try { const o = JSON.parse(fs.readFileSync(holdFile(root, id), 'utf8')); return isObj(o) ? o : null; } catch { return null; } }
+const holdMs = () => (Number(process.env.PMOS_REPORT_HOLD_MS) >= 0 && process.env.PMOS_REPORT_HOLD_MS !== undefined && process.env.PMOS_REPORT_HOLD_MS !== '' ? Number(process.env.PMOS_REPORT_HOLD_MS) : HOLD_MS);
+
+/** The saved plan and its Chrome and computer sources, or null when the report has no saved structure. */
+function savedPlan(root, id) {
+  let st; try { st = S.stateOf(root, id); } catch { return null; }
+  if (!st.saved) return null;
+  const plan = S.readVersion(root, id, st.saved.n);
+  return plan ? { n: st.saved.n, plan, outside: plan.sources.filter((s) => (s.kind === 'chrome' || s.kind === 'computer') && s.state !== 'off') } : null;
+}
+
+/**
+ * The block the report-template draft job gets for a report with a saved structure (contract section 8), or '' for none.
+ * `note` says which sources could not be read when the draft goes ahead without them.
+ */
+function draftBlock(root, id, { note } = {}) {
+  const sp = savedPlan(root, id);
+  if (!sp) return '';
+  const p = S.paths(root, id);
+  const lines = ['This report has a saved structure. Draft it from the structure:',
+    `- Brief: ${p.brief}`, `- Saved plan: ${path.join(p.versions, `S${sp.n}.json`)}`,
+    `- Data file: write <slot>.data.json next to the draft (${p.folder}), as the skill says`];
+  if (note) lines.push(`- Sources that could not be read this cycle: ${note}. Draft without them. Under Sources, list each as not reached with that reason. Never guess a number for them.`);
+  return `\n\n${lines.join('\n')}`;
+}
+
+/**
+ * Before a scheduled draft: re-check each Chrome or computer source of the saved structure. → { hold: false, block } to draft now, or { hold: true }
+ * when a check is running or failed (sweep() starts the draft later). A report with no such source drafts now.
+ */
+function beforeDraft(ctx, w, id, sched) {
+  try {
+    const root = w.root;
+    const sp = savedPlan(root, id);
+    if (!sp) return { hold: false, block: '' };
+    if (!sp.outside.length) return { hold: false, block: draftBlock(root, id) };
+    if (readHold(root, id)) return { hold: true };
+    for (const src of sp.outside) {
+      startCheck(ctx, w, id, src.id, { plan: sp.plan });   // a check already running (409) is the one this draft waits for
+    }
+    fs.mkdirSync(S.paths(root, id).dir, { recursive: true });
+    fs.writeFileSync(holdFile(root, id), JSON.stringify({ since: new Date().toISOString(), sched: sched ? sched.id : null, sources: sp.outside.map((s) => s.id), saved: sp.n }) + '\n');
+    return { hold: true };
+  } catch (e) { return { hold: false, block: '' }; }
+}
+
+/** Start the held drafts whose checks are done, or whose 4 hours are up. ctx.fireDraft(schedId, { note }) starts the draft. → the ids released */
+function sweepHolds(ctx, w) {
+  const released = [];
+  let base;
+  try { base = path.join(path.resolve(w.root), RDraft.stateRel(w.root), 'reports'); } catch { return released; }
+  let ids = []; try { ids = fs.readdirSync(base); } catch { return released; }
+  for (const id of ids) {
+    if (!S.CADENCE_RE.test(id) || id === 'definitions') continue;
+    const hold = readHold(w.root, id);
+    if (!hold) continue;
+    try { settleChecks(ctx, w, id); } catch { /* next tick */ }
+    const since = Date.parse(hold.since);
+    const checks = S.readChecks(w.root, id);
+    const wanted = (Array.isArray(hold.sources) ? hold.sources : []).map((sid) => ({ sid, c: checks[sid] }));
+    const done = wanted.every((x) => x.c && !x.c.running && Date.parse(x.c.at) >= since - 1000);
+    const failing = wanted.filter((x) => x.c && !x.c.running && !x.c.ok);
+    const expired = Date.now() - since >= holdMs();
+    if (!(done && !failing.length) && !expired) continue;
+    let note = null;
+    if (failing.length || (expired && !done)) {
+      const sp = savedPlan(w.root, id);
+      const nameOf = (sid) => (sp && sp.plan.sources.find((s) => s.id === sid) || { name: sid }).name;
+      const bad = wanted.filter((x) => !x.c || x.c.running || !x.c.ok);
+      note = bad.map((x) => {
+        const step = x.c && !x.c.running ? (x.c.steps || []).find((s) => s.state === 'needs-you') : null;
+        return `${nameOf(x.sid)} (${step ? step.reason || step.label : 'the check did not finish'})`;
+      }).join('; ');
+    }
+    try { fs.unlinkSync(holdFile(w.root, id)); } catch { /* gone */ }
+    try { if (typeof ctx.fireDraft === 'function') ctx.fireDraft(hold.sched, { note, id, ws: w.id }); } catch { /* the schedule is gone */ }
+    released.push(id);
+  }
+  return released;
+}
+
+/** On the server tick: collect check answers, release held drafts. */
+function sweep(ctx) {
+  if (!ctx) return [];
+  lastCtx = ctx;
+  const out = [];
+  const list = typeof ctx.workspaceList === 'function' ? ctx.workspaceList() : [ctx.getWs(null)].filter(Boolean);
+  for (const w of list) {
+    if (!w || !w.root) continue;
+    try { out.push(...sweepHolds(ctx, w)); } catch { /* next tick */ }
+  }
+  for (const k of [...checkJobs.keys()]) {
+    const [root, id] = k.split('\u0000');
+    const w = list.find((x) => x && x.root && path.resolve(x.root) === root);
+    if (w) { try { settleChecks(ctx, w, id); } catch { /* next tick */ } }
+  }
+  return out;
+}
+
+// ── the handler ─────────────────────────────────────────────────────────────────────────────────────────────
+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 isCharts = p === '/api/charts' || p.startsWith('/api/charts/');
+  const sub = isCharts ? p.replace(/^\/api\/charts\/?/, '') : p.replace(/^\/api\/report-structure\/?/, '');
+
+  if (req.method === 'GET') {
+    const w = wsOf(ctx, url.searchParams.get('ws'));
+    if (!w) return send(bad(404, 'no such workspace'));
+    const nameOf = (cadence) => { const s = setupOf(w.root, cadence); return s ? s.name : cadence; };
+    if (isCharts) {
+      if (sub === '') return send({ status: 200, body: { ok: true, charts: CS.list(w.root, { runtimeDir: ctx.runtimeDir, nameOf }) } });
+      if (sub === 'one') {
+        const id = text(url.searchParams.get('id'));
+        const c = CS.ID_RE.test(id) ? CS.one(w.root, id, { runtimeDir: ctx.runtimeDir, nameOf }) : null;
+        return send(c ? { status: 200, body: { ok: true, chart: c } } : bad(404, 'no such chart'));
+      }
+      return send(bad(404, 'no such route'));
+    }
+    const id = text(url.searchParams.get('id'));
+    if (!S.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 === '') {
+      try { settleStale(w.root, id); settleChecks(ctx, w, id); } catch { /* a read never fails on this */ }
+      return send({ status: 200, body: { ok: true, setup: pub(setup), structure: answerOf(w.root, id) } });
+    }
+    if (sub === 'version') {
+      const n = Number(url.searchParams.get('n'));
+      const plan = S.readVersion(w.root, id, n);
+      return send(plan ? { status: 200, body: { ok: true, plan } } : bad(404, 'no such version'));
+    }
+    if (sub === 'check') {
+      const sid = text(url.searchParams.get('source'));
+      if (!S.SLUG_RE.test(sid)) return send(bad(400, 'source must be a source id'));
+      try { settleChecks(ctx, w, id); } catch { /* ignore */ }
+      const c = S.readCheck(w.root, id, sid);
+      return send(c ? { status: 200, body: { ok: true, check: c } } : bad(404, 'this source has not been checked'));
+    }
+    if (sub === 'dry') {
+      const run = text(url.searchParams.get('run'));
+      if (!S.RUN_RE.test(run)) return send(bad(400, 'run must be a run id'));
+      const d = S.readDry(w.root, id, run);
+      return send(d ? { status: 200, body: { ok: true, dry: d } } : bad(404, 'no such run'));
+    }
+    return send(bad(404, 'no such route'));
+  }
+
+  if (isCharts || !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 structure, add a source, start a check or save a chart. 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));
+  const id = text(body.id);
+  if (!S.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 busy = () => jobs.has(keyOf(root, id));
+  const answer = () => send({ status: 200, body: { ok: true, structure: answerOf(root, id) } });
+  const BUSY = 'PMOS is already working on this report. Wait for the answer, then try again.';
+  const current = () => { const st = S.stateOf(root, id); return { st, plan: st.current != null ? S.readVersion(root, id, st.current) : null }; };
+
+  if (sub === 'turn') {
+    if (busy()) return send(bad(409, BUSY));
+    const t = text(body.text).trim();
+    if (!t || t.length > S.LIMITS.turn) return send(bad(400, `text is required, at most ${S.LIMITS.turn} characters`));
+    const st = S.stateOf(root, id);
+    S.append(root, id, { ev: 'turn', text: t, base: st.current }, { actor: g.actor });
+    const s = startJob(ctx, w, id, { kind: 'turn', turnText: t });
+    if (!s.ok) { S.append(root, id, { ev: 'error', text: s.error, mode: 'turn' }); return fail(s); }
+    return send({ status: 200, body: { ok: true, running: true } });
+  }
+  if (sub === 'dry') {
+    if (busy()) return send(bad(409, BUSY));
+    const st = S.stateOf(root, id);
+    const n = body.n === undefined ? st.current : body.n;
+    if (!Number.isInteger(n) || !st.versions.has(n)) return send(bad(404, 'no such version'));
+    const s = startJob(ctx, w, id, { kind: 'dry', n });
+    if (!s.ok) return fail(s);
+    return send({ status: 200, body: { ok: true, running: true } });
+  }
+  if (sub === 'revert') {
+    if (busy()) return send(bad(409, BUSY));
+    const n = body.n;
+    if (!Number.isInteger(n) || !S.stateOf(root, id).versions.has(n)) return send(bad(404, 'no such version'));
+    S.append(root, id, { ev: 'revert', n }, { actor: g.actor });
+    return answer();
+  }
+  if (sub === 'accept') {
+    if (busy()) return send(bad(409, BUSY));
+    const n = body.n;
+    const st = S.stateOf(root, id);
+    if (!Number.isInteger(n) || !st.versions.has(n)) return send(bad(404, 'no such version'));
+    const plan = S.readVersion(root, id, n);
+    if (!plan) return send(bad(404, 'no such version'));
+    const v = S.validatePlan(plan, { charts: storeIds(root) });
+    if (!v.ok) return send(bad(409, `S${n} cannot be saved: ${v.error}`));
+    // each New chart is written to the chart store once and the plan then points at it; a From Charts chart is never copied
+    const next = { ...v.plan, charts: v.plan.charts.map((c) => ({ ...c })) };
+    const written = [];
+    for (const c of next.charts) {
+      if (c.chart) continue;
+      const src = next.sources.find((s) => s.id === c.source) || {};
+      const r = CS.addChart(root, { id: c.id, name: c.name, question: c.question, source: { kind: src.kind || 'pmos-level', name: src.name || '', ...(src.via ? { via: src.via } : {}), ...(src.ref ? { ref: src.ref } : {}) },
+        from: c.from, how: c.how, compare: c.compare, flag: c.flag, query: c.query, why: c.why, created_by: `report-structure:${id}` }, { actor: g.actor });
+      if (!r.ok) return fail(r);
+      c.chart = r.chart.id; written.push(r.chart.id);
+    }
+    if (written.length) S.rewriteVersion(root, id, n, next);
+    S.append(root, id, { ev: 'accept', n, charts: written }, { actor: g.actor });
+    const b = S.writeBrief(root, id, setup);
+    if (!b.ok) return fail(b);
+    return send({ status: 200, body: { ok: true, structure: answerOf(root, id), brief: b.path, charts: written } });
+  }
+  if (sub === 'source') {
+    if (busy()) return send(bad(409, BUSY));
+    const { st, plan } = current();
+    if (!plan) return send(bad(409, 'there is no structure yet. Tell PMOS what the report is for first'));
+    const v = S.validateSource(body.source, { taken: plan.sources.map((s) => s.id) });
+    if (!v.ok) return fail(v);
+    const added = S.addSourceTo(plan, v.source);
+    if (!added.ok) return fail(added);
+    const land = S.landVersion(root, id, added.plan, { turn: `Added the source ${v.source.name}`, answer: `Made S${S.nextN(st)} with ${v.source.name} added as a source.`, from: 'source',
+      before: [{ ev: 'source', source: v.source }], actor: g.actor, charts: storeIds(root) });
+    if (!land.ok) return fail({ status: 400, error: land.error });
+    if (v.source.kind === 'chrome' || v.source.kind === 'computer') startCheck(ctx, w, id, v.source.id);
+    return answer();
+  }
+  if (sub === 'remove') {
+    if (busy()) return send(bad(409, BUSY));
+    const { st, plan } = current();
+    if (!plan) return send(bad(409, 'there is no structure yet'));
+    const ref = text(body.ref);
+    if (!S.SLUG_RE.test(ref)) return send(bad(400, 'ref must be an id'));
+    const r = S.removeFrom(plan, text(body.kind), ref);
+    if (!r.ok) return fail(r);
+    const land = S.landVersion(root, id, r.plan, { turn: `Removed the ${body.kind} ${ref}`, answer: `Made S${S.nextN(st)} without the ${body.kind} ${ref}.`, from: 'remove',
+      before: [{ ev: 'remove', kind: body.kind, ref }], actor: g.actor, charts: storeIds(root) });
+    if (!land.ok) return fail({ status: 400, error: land.error });
+    return answer();
+  }
+  if (sub === 'check') {
+    const sid = text(body.source);
+    if (!S.SLUG_RE.test(sid)) return send(bad(400, 'source must be a source id'));
+    const r = startCheck(ctx, w, id, sid);
+    return r.ok ? send({ status: 200, body: { ok: true, check: r.check } }) : fail(r);
+  }
+  return send(bad(404, 'no such route'));
+}
+
+module.exports = { prefixes: ['/api/report-structure', '/api/charts'], handle, sweep, beforeDraft, draftBlock, startCheck, settleChecks, readHold, savedPlan, computerRule, resultJson, promptFor,
+  _jobs: jobs, _checks: checkJobs };

package/workspace/package-lock.json

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

package/workspace/package.json

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