create-pmos 0.131.0 → 0.133.0

package/workspace/lib/freshness.js

@@ -0,0 +1,167 @@
+'use strict';
+/* freshness.js — one change detector per workspace, a data version the pages watch, and how old each source is
+ * (workspace-data-freshness R4, R6, R7).
+ *
+ *   create({ stateDir, workspaces, onChange, schedules, factsStatus, now, pollMs, stableMs, watcher }) → {
+ *     start(), stop(), tick(),                       the watcher (lib/repo-watch.js), one per server
+ *     versions() → { <ws id>: n }                    the number moves when that workspace's files change
+ *     sources(w) → [row]                             one row per source, oldest information first
+ *     enabled(root) · setEnabled(root, on)           the PM's off switch, per repository (default on)
+ *   }
+ *   SOURCES                                          the source table: id, label, skill, stale_after_ms
+ *
+ * THE DETECTOR. lib/repo-watch.js polls the repository signature (HEAD, porcelain status, dirty file times) every pollMs
+ * and runs `check` once the signature has held still for stableMs. Here `check` bumps the workspace's data version and
+ * calls onChange(w), which the server uses to start the board and facts rebuilds. Async git, read-only verbs, no network.
+ * A first look sets the data version but calls no onChange: a server that starts does not read every repository at once,
+ * and each cache is read on its first request (the facts from their disk entry when the repository has not changed).
+ *
+ * A ROW. { id, label, as_of: ISO|null, state: 'fresh'|'stale'|'never'|'building'|'failed', detail, stale_after_ms,
+ * skill: id|null, schedule: { cadence, time, day?, next_run }|null }. A source with no reading is `never`: it is never
+ * shown as fresh because nothing is known about it.
+ *
+ * Nothing here calls a tracker, a calendar or a network. The external sources are read by agent sessions with the PM's
+ * own connections; this module only reads the files those sessions leave behind.
+ */
+const fs = require('fs');
+const path = require('path');
+const repoWatch = require('./repo-watch.js');
+
+const H = 3600 * 1000;
+const SOURCES = Object.freeze([
+  { id: 'repository', label: 'Repository', skill: null, stale_after_ms: null },
+  { id: 'initiatives', label: 'Initiatives', skill: null, stale_after_ms: null },
+  { id: 'calendar', label: 'Calendar', skill: 'calendar-sync', stale_after_ms: 8 * H },
+  { id: 'jira', label: 'Jira status', skill: 'jira-sync', stale_after_ms: 26 * H },
+  { id: 'my-work', label: 'My work', skill: 'my-work-read', stale_after_ms: 26 * H },
+  { id: 'tracker', label: 'Tracker items', skill: 'tracker-refresh', stale_after_ms: 8 * 24 * H },
+]);
+
+const iso = (ms) => (ms ? new Date(ms).toISOString() : null);
+const mtime = (f) => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
+const readJson = (f, dflt) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return dflt; } };
+
+/** The newest `fetched_at` among the imported calendar events (scripts/calendar-import.js ledger), in ms, or 0. */
+function calendarAsOf(stateDir) {
+  let text = '';
+  try { text = fs.readFileSync(path.join(stateDir, 'calendar-import', 'events.jsonl'), 'utf8'); } catch { return 0; }
+  let best = 0;
+  for (const line of text.split('\n')) {
+    if (!line.includes('fetched_at')) continue;
+    try {
+      const o = JSON.parse(line);
+      const t = Date.parse((o.event && o.event.fetched_at) || o.fetched_at || '');
+      if (t > best) best = t;
+    } catch { /* a torn line is skipped */ }
+  }
+  return best;
+}
+
+/** The newest Jira status snapshot of a repository (lib/jira-status.js writes <state>/tracker/jira/<initiative>.md). */
+function jiraAsOf(repoStateDir) {
+  if (!repoStateDir) return 0;
+  const dir = path.join(repoStateDir, 'tracker', 'jira');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.md') && !n.endsWith('-tickets.md')); } catch { return 0; }
+  return names.reduce((m, n) => Math.max(m, mtime(path.join(dir, n))), 0);
+}
+
+function create(o) {
+  const now = o.now || Date.now;
+  const settingsFile = o.stateDir ? path.join(o.stateDir, 'freshness.json') : null;
+  const versions = new Map();          // ws id -> n
+  const seen = new Map();              // root -> { checked_at, changed_at }
+  let settings = settingsFile ? readJson(settingsFile, { repos: {} }) : { repos: {} };
+  if (!settings || typeof settings.repos !== 'object') settings = { repos: {} };
+
+  const enabled = (root) => !(settings.repos[root] && settings.repos[root].watch === false);
+  function setEnabled(root, on) {
+    settings = { repos: { ...settings.repos, [root]: { watch: !!on } } };
+    if (settingsFile) {
+      try {
+        fs.mkdirSync(path.dirname(settingsFile), { recursive: true });
+        const tmp = `${settingsFile}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+        fs.renameSync(tmp, settingsFile);
+      } catch { return false; }
+    }
+    return true;
+  }
+
+  const watcher = (o.watcher || repoWatch.createWatcher)({
+    repos: () => o.workspaces().map((w) => ({ id: w.id, root: w.root })),
+    enabled,
+    // a folder that is not a checkout: the times and sizes of its top-level files
+    listFiles: async (root) => ({ files: (() => { try { return fs.readdirSync(root).filter((n) => !n.startsWith('.')).slice(0, 2000); } catch { return []; } })() }),
+    check: async ({ root }) => {
+      const t = now();
+      const prev = seen.get(root) || {};
+      seen.set(root, { checked_at: t, changed_at: t, first: !prev.checked_at });
+      for (const w of o.workspaces()) {
+        if (w.root !== root) continue;
+        versions.set(w.id, (versions.get(w.id) || 0) + 1);
+        if (!prev.checked_at) continue;   // a first look only records the signature: the caches warm on their first read
+        try { if (o.onChange) o.onChange(w); } catch { /* a cache that cannot be refreshed is refreshed by its own rule */ }
+      }
+      return { ok: true };
+    },
+    pollMs: o.pollMs || 10000,
+    stableMs: o.stableMs == null ? 3000 : o.stableMs,
+    sweepEveryMs: 24 * H,
+  });
+
+  function scheduleOf(skill) {
+    if (!skill || !o.schedules) return null;
+    let list = [];
+    try { list = o.schedules() || []; } catch { return null; }
+    const s = list.find((x) => x && x.skill === skill && x.enabled !== false);
+    return s ? { cadence: s.cadence || null, time: s.time || null, day: s.day || null, next_run: s.nextRun || null, last_run: s.lastRun || null, last_status: s.lastStatus || null } : null;
+  }
+
+  function row(src, asOfMs, extra = {}) {
+    const t = now();
+    let state = asOfMs ? 'fresh' : 'never';
+    if (asOfMs && src.stale_after_ms && t - asOfMs > src.stale_after_ms) state = 'stale';
+    const schedule = scheduleOf(src.skill);
+    if (schedule && schedule.last_status === 'fail' && state !== 'never') state = 'failed';
+    return { id: src.id, label: src.label, as_of: iso(asOfMs), state, detail: null, stale_after_ms: src.stale_after_ms, skill: src.skill, schedule, ...extra };
+  }
+
+  /** One row per source for workspace `w` ({ id, root, repoStateDir }). Reads memory, small files and file times only. */
+  function sources(w) {
+    const S = Object.fromEntries(SOURCES.map((s) => [s.id, s]));
+    const out = [];
+    const sn = seen.get(w.root);
+    const watching = enabled(w.root);
+    // a watched repository is checked every few seconds, so it is as fresh as now; `changed_at` is the last change seen
+    out.push(row(S.repository, sn ? (watching ? now() : sn.checked_at) : 0, {
+      state: !watching ? 'off' : sn ? 'fresh' : 'never',
+      changed_at: sn ? iso(sn.changed_at) : null,
+      detail: !watching ? 'change detection is off for this repository' : sn ? 'checked every few seconds; the last change was read at once' : 'not looked at yet',
+    }));
+    const fs0 = o.factsStatus ? o.factsStatus(w.root) : null;
+    const factsAt = fs0 && fs0.as_of ? Date.parse(fs0.as_of) : 0;
+    let fstate = factsAt ? 'fresh' : 'never';
+    if (fs0 && fs0.building) fstate = 'building';
+    else if (fs0 && fs0.error) fstate = 'failed';
+    else if (factsAt && sn && sn.changed_at > factsAt) fstate = 'stale';
+    out.push(row(S.initiatives, factsAt, {
+      state: fstate,
+      detail: fs0 && fs0.error ? fs0.error : fs0 && fs0.took_ms != null ? `read in ${(fs0.took_ms / 1000).toFixed(1)} s` : null,
+    }));
+    out.push(row(S.calendar, o.stateDir ? calendarAsOf(o.stateDir) : 0));
+    out.push(row(S.jira, jiraAsOf(w.repoStateDir)));
+    const mw = o.stateDir ? readJson(path.join(o.stateDir, 'my-work', 'read.json'), null) : null;
+    out.push(row(S['my-work'], mw && mw.read_at ? Date.parse(mw.read_at) || 0 : 0));
+    const tr = scheduleOf('tracker-refresh');
+    out.push(row(S.tracker, tr && tr.last_run ? Date.parse(tr.last_run) || 0 : 0));
+    return out;
+  }
+
+  return {
+    start: () => watcher.start(), stop: () => watcher.stop(), tick: () => watcher.tick(),
+    versions: () => Object.fromEntries(versions), sources, enabled, setEnabled,
+  };
+}
+
+module.exports = { create, SOURCES, calendarAsOf, jiraAsOf };

package/workspace/lib/import-overlay.js

@@ -0,0 +1,32 @@
+'use strict';
+/* import-overlay.js: where a workspace's first-run import lives, and the fold of it (slice 2 of onboarding-scan-and-map).
+ *   overlayDir(stateRoot, wsId) = <stateRoot>/imports/<wsId>      overlayDirFor is the same function
+ *   importedFor(stateRoot, wsId) -> { boards, initiatives, imports } from scripts/onboarding/apply.js; empty shapes when nothing is there.
+ * Initiative rows carry import_id and source: 'import'; board rows too. Never throws on a missing folder or file. */
+const fs = require('fs');
+const path = require('path');
+
+/** Where scripts/onboarding/ is: the checkout's own, else the copy an installed package vendors under lib/vendor/
+ * (scripts/vendor-workspace-engine.js vendorTree). Null when neither is there. */
+function onboardingDir() {
+  for (const d of [path.join(__dirname, '..', '..', 'scripts', 'onboarding'), path.join(__dirname, 'vendor', 'scripts', 'onboarding')]) {
+    if (fs.existsSync(path.join(d, 'scan.js'))) return d;
+  }
+  return null;
+}
+
+const WS_ID = /^[A-Za-z0-9_-]{1,64}$/; // one safe path segment (server ids are 10 hex characters)
+const empty = () => ({ boards: [], initiatives: [], imports: [] });
+
+function overlayDir(stateRoot, wsId) {
+  if (!WS_ID.test(String(wsId))) throw new Error('bad workspace id');
+  return path.join(stateRoot, 'imports', String(wsId));
+}
+
+function importedFor(stateRoot, wsId) {
+  let apply;
+  try { apply = require(path.join(onboardingDir(), 'apply.js')); } catch { return empty(); }
+  try { return apply.importedFor(overlayDir(stateRoot, wsId)); } catch { return empty(); }
+}
+
+module.exports = { overlayDir, overlayDirFor: overlayDir, importedFor, onboardingDir };

package/workspace/lib/offloop.js

@@ -0,0 +1,94 @@
+'use strict';
+/* offloop.js — run a synchronous fold in a worker thread, so a request does not hold the server (workspace-data-freshness R5).
+ *
+ *   call(module, fn, args) → Promise<result>   `module` is a file in workspace/lib; `fn` one of its exports; `args` and the
+ *                                               result must survive structured clone (plain data).
+ *   fallback(module, fn, args) → result          the same call in this thread
+ *   stop()                                       end the worker (a test, or the server's exit)
+ *
+ * WHY. Board and My work fold every plan ledger and initiative record on each request: 0.2 to 0.5 s per workspace, all of
+ * it synchronous file reads. On the event loop that stalls every other request and every terminal's output for that long.
+ * In a worker it costs the same and stalls nothing.
+ *
+ * THE ANSWER IS THE SAME FUNCTION'S. The worker requires the same module and calls the same export with the same
+ * arguments; nothing is cached here. A worker that cannot start, crashes or times out rejects, and `run` then answers in
+ * this thread, so a route never fails because of the worker. One worker serves every call, one call at a time in order.
+ * Only modules in workspace/lib and only names in ALLOWED can be called.
+ */
+const path = require('path');
+
+const LIB = __dirname;
+const ALLOWED = Object.freeze({ 'board-fold.js': ['boardFor'] });
+const TIMEOUT_MS = 60000;
+
+let worker = null;
+let seq = 0;
+const pending = new Map();   // id -> { resolve, reject, timer }
+
+function allowed(mod, fn) { return Object.prototype.hasOwnProperty.call(ALLOWED, mod) && ALLOWED[mod].includes(fn); }
+
+const WORKER_SRC = `
+const { parentPort } = require('worker_threads');
+const path = require('path');
+parentPort.on('message', (m) => {
+  try {
+    const out = require(path.join(${JSON.stringify(LIB)}, m.mod))[m.fn](...m.args);
+    parentPort.postMessage({ id: m.id, ok: true, out });
+  } catch (e) {
+    parentPort.postMessage({ id: m.id, ok: false, error: String((e && e.message) || e) });
+  }
+});`;
+
+function failAll(err) {
+  for (const [id, p] of pending) { clearTimeout(p.timer); p.reject(err); pending.delete(id); }
+}
+
+function ensure() {
+  if (worker) return worker;
+  const { Worker } = require('worker_threads');
+  worker = new Worker(WORKER_SRC, { eval: true });
+  worker.unref();
+  worker.on('message', (m) => {
+    const p = pending.get(m.id);
+    if (!p) return;
+    pending.delete(m.id); clearTimeout(p.timer);
+    if (m.ok) p.resolve(m.out); else p.reject(new Error(m.error));
+  });
+  worker.on('error', (e) => { worker = null; failAll(e); });
+  worker.on('exit', () => { worker = null; failAll(new Error('the worker ended')); });
+  return worker;
+}
+
+function call(mod, fn, args = []) {
+  if (!allowed(mod, fn)) return Promise.reject(new Error(`offloop: ${mod}#${fn} is not allowed`));
+  return new Promise((resolve, reject) => {
+    let w;
+    try { w = ensure(); } catch (e) { reject(e); return; }
+    const id = ++seq;
+    const timer = setTimeout(() => {
+      pending.delete(id); reject(new Error('offloop: timed out'));
+      // a fold that hangs takes the worker with it; the next call starts a new one
+      try { w.terminate(); } catch { /* already gone */ }
+    }, TIMEOUT_MS);
+    if (timer.unref) timer.unref();
+    pending.set(id, { resolve, reject, timer });
+    w.ref();   // keep the process up while a call is in flight
+    w.postMessage({ id, mod, fn, args });
+  }).finally(() => { if (worker && !pending.size) worker.unref(); });
+}
+
+function fallback(mod, fn, args = []) {
+  if (!allowed(mod, fn)) throw new Error(`offloop: ${mod}#${fn} is not allowed`);
+  return require(path.join(LIB, mod))[fn](...args);
+}
+
+/** The worker's answer, or this thread's when the worker fails. PMOS_OFFLOOP=0 answers in this thread (a suite that
+ * replaces a module's export in its own process needs the fold to see the replacement). */
+async function run(mod, fn, args = []) {
+  if (process.env.PMOS_OFFLOOP === '0') return fallback(mod, fn, args);
+  try { return await call(mod, fn, args); } catch { return fallback(mod, fn, args); }
+}
+
+function stop() { if (worker) { const w = worker; worker = null; failAll(new Error('stopped')); return w.terminate(); } return Promise.resolve(); }
+
+module.exports = { call, run, fallback, stop, ALLOWED };

package/workspace/lib/pmos-verbs.js

@@ -47,6 +47,9 @@ const VERBS = Object.freeze({
   // Not a pm-os-absorb verb (run: null): initiative my-work added it through the same table.
   'my-work': Object.freeze({ module: 'my-work-cli.js', run: null, guide: 'my-work.md',
     help: 'pmos my-work list|show|submit … — the Jira tickets and WBS items assigned to you, ranked (pmos my-work help)' }),
+  // Not a pm-os-absorb verb (run: null): workspace-data-freshness added it through the same table.
+  calendar: Object.freeze({ module: 'calendar-cli.js', run: null, guide: 'data-freshness.md',
+    help: 'pmos calendar import|status — the calendar events an agent session read, saved for Briefing and Calendar (pmos calendar help)' }),
   launcher: Object.freeze({ module: 'launcher-cli.js', run: null, guide: 'launcher.md',
     help: 'pmos launcher on|off|status — a PMOS app and a login item, so the workspace starts without a terminal' }),
 });

package/workspace/lib/route-modules.js

@@ -60,7 +60,9 @@ const MODULES = Object.freeze([
   'routes-c3-life',       // console3 Lifecycle lens panels: newest evaluation per initiative, corrections per run, evidence sources (read-only)
   'routes-c3-strategy',   // console3 Calendar Quarter and Year panes: outcomes, north star, signals, synergy, bets (read-only)
   'routes-c3-reports',    // console3 Reports dashboards: library, per-scope data, page-press layouts (layouts are the only write)
+  'routes-onboarding',    // onboarding-scan-and-map slice 2: first run (scan read-only, structure, import into the overlay, undo, first Briefing)
   'routes-hooks',         // planning-flows run 7: CLI hook endpoints (session token, per-run JSONL)
+  'routes-sources',       // workspace-data-freshness: how old each source is, Refresh now, the change detector switch
 ]);
 const PM_DIR = path.join(__dirname, '..', 'public', 'pm');
 const MODULE_NAME = /^[a-z0-9][a-z0-9-]*\.js$/;

package/workspace/lib/routes-board.js

@@ -24,6 +24,7 @@ const grantMint = require('./grant-mint.js');
 const factoryJoin = require('./factory-join.js');
 const planItems = require('./plan-items.js');
 const boardFold = require('./board-fold.js');
+const offloop = require('./offloop.js');
 
 const BATCH_RE = /^[A-Za-z0-9][\w.-]{0,79}$/;
 const text = (v) => (typeof v === 'string' ? v : '');
@@ -46,7 +47,8 @@ async function handle(req, res, url, ctx) {
       return true;
     }
     let out;
-    try { out = boardFold.boardFor({ id: w.id, root: w.root }, { filter: url.searchParams.get('filter') || 'active' }); }
+    // in a worker thread (workspace-data-freshness R5): the same fold, without holding the server while it reads
+    try { out = await offloop.run('board-fold.js', 'boardFor', [{ id: w.id, root: w.root }, { filter: url.searchParams.get('filter') || 'active' }]); }
     catch (e) { ctx.json(res, { ok: false, error: 'the Board could not be read: ' + String((e && e.message) || 'error').slice(0, 160) }, 500); return true; }
     if (!out.ok) { ctx.json(res, { ok: false, error: out.error }, out.status || 400); return true; }
     ctx.json(res, { ...out, ws: w.id });

package/workspace/lib/routes-my-work.js

@@ -22,6 +22,7 @@ const path = require('path');
 const guard = require('./pm-guard.js');
 const myWork = require('./my-work.js');
 const boardFold = require('./board-fold.js');
+const offloop = require('./offloop.js');
 const { localDate } = require('./brief.js');
 
 const dirOf = (ctx) => path.join(ctx.runtimeDir, 'my-work');
@@ -37,16 +38,33 @@ function loadActions(ctx) {
 
 /** The whole list, as GET answers it. */
 function listFor(ctx, now) {
+  const all = typeof ctx.workspaceList === 'function' ? ctx.workspaceList() : [];
+  return foldList(ctx, now, all.map((w) => {
+    try { return { w, b: boardFold.boardFor({ id: w.id, root: w.root }, { filter: 'mine', now }) }; }
+    catch (e) { return { w, error: e }; }
+  }));
+}
+
+/* The same list with each repository's Board fold run in a worker thread (workspace-data-freshness R5): the GET answers
+ * what listFor answers, without holding the server for a fold per repository. */
+async function listForAsync(ctx, now) {
+  const all = typeof ctx.workspaceList === 'function' ? ctx.workspaceList() : [];
+  const folds = [];
+  for (const w of all) {
+    try { folds.push({ w, b: await offloop.run('board-fold.js', 'boardFor', [{ id: w.id, root: w.root }, { filter: 'mine', now }]) }); }
+    catch (e) { folds.push({ w, error: e }); }
+  }
+  return foldList(ctx, now, folds);
+}
+
+function foldList(ctx, now, folds) {
   const today = localDate(now);
   const banner = [];
   const boards = [];
-  const all = typeof ctx.workspaceList === 'function' ? ctx.workspaceList() : [];
-  for (const w of all) {
-    try {
-      const b = boardFold.boardFor({ id: w.id, root: w.root }, { filter: 'mine', now });
-      if (b.ok) boards.push({ ws: w.id, repo: w.name || path.basename(w.root), board: b });
-      else banner.push({ source: 'wbs:' + w.id, error: b.error });
-    } catch (e) { banner.push({ source: 'wbs:' + w.id, error: String((e && e.message) || e).slice(0, 160) }); }
+  for (const { w, b, error } of folds) {
+    if (error) { banner.push({ source: 'wbs:' + w.id, error: String((error && error.message) || error).slice(0, 160) }); continue; }
+    if (b.ok) boards.push({ ws: w.id, repo: w.name || path.basename(w.root), board: b });
+    else banner.push({ source: 'wbs:' + w.id, error: b.error });
   }
   const read = loadRead(ctx);
   const actions = loadActions(ctx);
@@ -71,7 +89,7 @@ async function handle(req, res, url, ctx) {
   const now = Date.now();
   if (p === '/api/my-work') {
     if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
-    ctx.json(res, listFor(ctx, now));
+    ctx.json(res, await listForAsync(ctx, now));
     return true;
   }
   if (!['/api/my-work/read', '/api/my-work/act', '/api/my-work/refresh'].includes(p)) return false;
@@ -119,4 +137,4 @@ async function handle(req, res, url, ctx) {
   return true;
 }
 
-module.exports = { prefixes: ['/api/my-work'], handle, listFor };
+module.exports = { prefixes: ['/api/my-work'], handle, listFor, listForAsync };

package/workspace/lib/routes-onboarding.js

@@ -0,0 +1,215 @@
+'use strict';
+/* routes-onboarding.js — the first run: scan a folder read-only, show the proposed portfolio, import it into the overlay
+ * (onboarding-scan-and-map, slice 2). Every read takes ?ws. Every POST passes pm-guard requirePagePress.
+ *
+ *   GET  /api/onboarding/status?ws        → { ok, state: 'new'|'scanned'|'imported', first_run, dismissed, scanning, scan_id, imported: { boards, initiatives }, imports }
+ *   POST /api/onboarding/scan { ws, extra_roots? } → { ok, scan_id, first_look: { sentence, numbers, findings } }
+ *   GET  /api/onboarding/structure?ws     → { ok, ...structure }
+ *   POST /api/onboarding/apply { ws, include, revisions, answers } → { ok, import_id, boards, initiatives }
+ *   POST /api/onboarding/undo { ws, import_id }    → { ok, retracted }
+ *   GET  /api/onboarding/briefing?ws      → { ok, items }
+ *   POST /api/onboarding/dismiss { ws }   → { ok }   "Not now": status.first_run turns false for this folder
+ *
+ * STATE: <STATE>/imports/<wsId>/ (brief.json, scan.json, firstlook.json, proposals.jsonl, imports.jsonl), in the per-user
+ * state folder and never in the scanned folder. The scan reads ws.root (and the root of each extra_roots entry that is a
+ * registered workspace) and writes nothing there. Apply writes to the overlay only.
+ *
+ * WHO WRITES: the press gives the page's actor ({ by: 'pm:<slug>', via: 'ui' }). The onboarding ledger wants a human actor,
+ * so humanOf() maps 'pm:<slug>' to 'human:<slug>'; an actor that is not a PM press is refused. Modules under
+ * scripts/onboarding/ are required inside the handlers, so a module that is not built yet answers 500 for its route only.
+ *
+ * EXTRA ROOTS. scan() reads one root. An extra root must be a registered workspace (never an arbitrary path); it is scanned
+ * on its own into its own overlay, so its own Welcome page shows it. The answer lists them in `extra`.
+ */
+const fs = require('fs');
+const path = require('path');
+const guard = require('./pm-guard.js');
+
+// the checkout's scripts/onboarding/, or the copy an installed package vendors under lib/vendor/ (import-overlay onboardingDir)
+const obDir = () => { const d = require('./import-overlay.js').onboardingDir(); if (!d) throw new Error('the onboarding modules are not installed'); return d; };
+const ob = (name) => require(path.join(obDir(), name));
+const stateRootOf = (ctx) => (ctx && (ctx.runtimeDir || ctx.stateRoot)) || require('./state-root.js').defaultRoot();
+const overlayOf = (ctx, w) => require('./import-overlay.js').overlayDir(stateRootOf(ctx), w.id);
+const today = () => new Date().toISOString().slice(0, 10);
+const bad = (status, error) => ({ status, body: { ok: false, error } });
+const len = (v) => (Array.isArray(v) ? v.length : Number(v) || 0);
+
+/** pm:<slug> from the press becomes human:<slug> for the onboarding ledger. Null for anything else. */
+function humanOf(actor) {
+  const by = actor && typeof actor.by === 'string' ? actor.by : '';
+  return /^pm:[a-z0-9_-]{1,40}$/.test(by) ? { by: 'human:' + by.slice(3), via: actor.via || 'ui' } : null;
+}
+
+function wsOf(ctx, id) {
+  if (typeof id !== 'string' || !id) return null;
+  const w = ctx.getWs(id);
+  return w && w.id === id ? w : null;
+}
+const readJsonFile = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
+
+function loadScan(dir) {
+  const scan = readJsonFile(path.join(dir, 'scan.json'));
+  return scan ? { scan, brief: readJsonFile(path.join(dir, 'brief.json')) } : null;
+}
+function imported(dir) {
+  const r = ob('apply.js').importedFor(dir) || {};
+  const imports = Array.isArray(r.imports) ? r.imports : [];
+  return { boards: len(r.boards), initiatives: len(r.initiatives), imports, live: imports.some((i) => !i.retracted) };
+}
+
+function status(ctx, w) {
+  const dir = overlayOf(ctx, w);
+  const have = loadScan(dir);
+  const imp = have ? imported(dir) : { boards: 0, initiatives: 0, imports: [], live: false };
+  const state = !have ? 'new' : imp.live ? 'imported' : 'scanned';
+  // first_run: `pmos` opens Welcome on its own only for a plain folder (no PMOS state folder of its own) that is not imported and
+  // where the PM did not choose "Not now". A PMOS repository, or a kit tenant, opens the console as before; `pmos welcome` still works.
+  let ownState = false; try { ownState = typeof ctx.stateDirFor === 'function' && !!ctx.stateDirFor(w); } catch { ownState = false; }
+  const dismissed = fs.existsSync(path.join(dir, 'dismissed.json'));
+  const first_run = state !== 'imported' && !dismissed && !ownState;
+  return { status: 200, body: { ok: true, state, first_run, dismissed, scanning: running.has(w.id), scan_id: have ? have.scan.scan_id : null, imported: { boards: imp.boards, initiatives: imp.initiatives }, imports: imp.imports } };
+}
+
+/* The scan runs in a child process (scripts/onboarding/scan-worker.js): a large folder takes a minute or more, and the server
+ * holds the PM's terminals, so it must never wait on it. A second press for the same workspace joins the running scan. */
+const running = new Map();
+function scanOne(ctx, w, now) {
+  if (running.has(w.id)) return running.get(w.id);
+  const dir = overlayOf(ctx, w);
+  const p = new Promise((resolve, reject) => {
+    const cp = require('child_process');
+    const child = cp.spawn(process.execPath, [path.join(obDir(), 'scan-worker.js'), w.root, dir, now], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = ''; let err = '';
+    child.stdout.on('data', (d) => { out += d; });
+    child.stderr.on('data', (d) => { err += d; });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code !== 0) return reject(new Error(err.trim() || 'the scan stopped with code ' + code));
+      const look = readJsonFile(path.join(dir, 'firstlook.json'));
+      let id = null; try { id = JSON.parse(out.trim().split('\n').pop()).scan_id; } catch { /* read below */ }
+      resolve({ scan_id: id || (readJsonFile(path.join(dir, 'scan.json')) || {}).scan_id, first_look: look });
+    });
+  }).finally(() => running.delete(w.id));
+  running.set(w.id, p);
+  return p;
+}
+
+async function scanRoute(ctx, w, body) {
+  const extra = body.extra_roots == null ? [] : body.extra_roots;
+  if (!Array.isArray(extra) || extra.some((x) => typeof x !== 'string')) return bad(400, 'extra_roots must be a list of folder paths');
+  const known = typeof ctx.workspaceList === 'function' ? ctx.workspaceList() : [];
+  const extras = [];
+  for (const r of extra) {
+    const root = path.resolve(r);
+    const hit = known.find((k) => k && k.root && path.resolve(k.root) === root);
+    if (!hit) return bad(400, 'extra_roots may name registered workspaces only: ' + r);
+    if (hit.id !== w.id) extras.push(hit);
+  }
+  const now = today();
+  let out;
+  try { out = await scanOne(ctx, w, now); } catch (e) { return bad(500, 'the scan failed: ' + String((e && e.message) || e).slice(0, 200)); }
+  out.extra = [];
+  for (const x of extras) {
+    try { out.extra.push({ ws: x.id, scan_id: (await scanOne(ctx, x, now)).scan_id }); } catch (e) { out.extra.push({ ws: x.id, error: String((e && e.message) || e).slice(0, 120) }); }
+  }
+  return { status: 200, body: { ok: true, ...out } };
+}
+
+function structureOf(dir) {
+  const have = loadScan(dir);
+  if (!have) return null;
+  return ob('structure.js').structure(have.scan, { brief: have.brief });
+}
+
+function structureRoute(ctx, w) {
+  const dir = overlayOf(ctx, w);
+  let s;
+  try { s = structureOf(dir); } catch (e) { return bad(500, 'the structure could not be built: ' + String((e && e.message) || e).slice(0, 200)); }
+  if (!s) return bad(409, 'scan first: there is no scan for this folder yet');
+  return { status: 200, body: { ok: true, ...s } };
+}
+
+function applyRoute(ctx, w, body, actor) {
+  const dir = overlayOf(ctx, w);
+  let s;
+  try { s = structureOf(dir); } catch (e) { return bad(500, 'the structure could not be built: ' + String((e && e.message) || e).slice(0, 200)); }
+  if (!s) return bad(409, 'scan first: there is no scan for this folder yet');
+  const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+  if (body.include != null && (!Array.isArray(body.include) || body.include.some((x) => typeof x !== 'string'))) return bad(400, 'include must be a list of proposal ids');
+  if (body.revisions != null && !isObj(body.revisions)) return bad(400, 'revisions must be an object keyed by proposal id');
+  if (body.answers != null && !isObj(body.answers)) return bad(400, 'answers must be an object keyed by question id');
+  const ids = new Set(s.boards.flatMap((b) => b.initiatives.map((r) => r.proposal_id)));
+  const unknown = (body.include || []).find((x) => !ids.has(x));
+  if (unknown) return bad(400, 'include names an unknown proposal: ' + unknown);
+  const include = body.include == null ? s.boards.flatMap((b) => b.initiatives.filter((r) => r.checked).map((r) => r.proposal_id)) : body.include;
+  try {
+    const r = ob('apply.js').apply(dir, s, { include, revisions: body.revisions || {}, answers: body.answers || {}, actor, now: new Date().toISOString(), root: w.root });
+    return { status: 200, body: { ok: true, import_id: r.import_id, boards: len(r.boards), initiatives: len(r.initiatives) } };
+  } catch (e) { return bad(400, String((e && e.message) || e).slice(0, 240)); }
+}
+
+function undoRoute(ctx, w, body, actor) {
+  const dir = overlayOf(ctx, w);
+  if (typeof body.import_id !== 'string' || !body.import_id) return bad(400, 'import_id is required');
+  const hit = imported(dir).imports.find((i) => i.import_id === body.import_id);
+  if (!hit) return bad(404, 'no such import');
+  if (hit.retracted) return bad(409, 'this import is already undone');
+  try {
+    const r = ob('apply.js').undo(dir, body.import_id, { actor, now: new Date().toISOString() });
+    return { status: 200, body: { ok: true, retracted: len(r.retracted) } };
+  } catch (e) { return bad(400, String((e && e.message) || e).slice(0, 240)); }
+}
+
+function briefingRoute(ctx, w) {
+  const dir = overlayOf(ctx, w);
+  const have = loadScan(dir);
+  if (!have) return bad(409, 'scan first: there is no scan for this folder yet');
+  const imp = imported(dir);
+  if (!imp.live) return bad(409, 'nothing is imported yet');
+  try {
+    const r = ob('first-briefing.js').firstBriefing(have.scan, ob('apply.js').importedFor(dir), { today: today() });
+    return { status: 200, body: { ok: true, items: r.items || [] } };
+  } catch (e) { return bad(500, 'the briefing could not be built: ' + String((e && e.message) || e).slice(0, 200)); }
+}
+
+/** "Not now": Welcome stops opening on its own for this folder. One file in the overlay; `pmos welcome` still opens it. */
+function dismissRoute(ctx, w, body, actor) {
+  const dir = overlayOf(ctx, w);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'dismissed.json'), JSON.stringify({ at: new Date().toISOString(), by: actor.by }) + '\n');
+  return { status: 200, body: { ok: true } };
+}
+
+const GETS = { status: status, structure: structureRoute, briefing: briefingRoute };
+const POSTS = { scan: scanRoute, apply: applyRoute, undo: undoRoute, dismiss: dismissRoute };
+
+module.exports = {
+  prefixes: ['/api/onboarding'],
+  humanOf, status, dismissRoute, scanRoute, structureRoute, applyRoute, undoRoute, briefingRoute,
+  handle: async (req, res, url, ctx) => {
+    const m = url.pathname.match(/^\/api\/onboarding\/([a-z]+)$/);
+    if (!m) return false;
+    const verb = m[1];
+    const isGet = Object.prototype.hasOwnProperty.call(GETS, verb);
+    const isPost = Object.prototype.hasOwnProperty.call(POSTS, verb);
+    if (!isGet && !isPost) return false;
+    const send = (r) => { ctx.json(res, r.body, r.status); return true; };
+    if (isGet) {
+      if (req.method !== 'GET') return send(bad(405, 'GET only'));
+      const w = wsOf(ctx, url.searchParams.get('ws'));
+      if (!w) return send(bad(404, 'no such workspace'));
+      return send(GETS[verb](ctx, w));
+    }
+    if (req.method !== 'POST') return send(bad(405, 'POST only'));
+    const got = await ctx.readJson(req);
+    if (!got.ok) return send(bad(400, 'invalid JSON body'));
+    const body = got.body || {};
+    const g = guard.requirePagePress(req, body);
+    if (!g.ok) return send(bad(g.status, g.error));
+    const w = wsOf(ctx, body.ws);
+    if (!w) return send(bad(404, 'no such workspace'));
+    const actor = humanOf(g.actor);
+    if (!actor) return send(bad(403, 'only the PM can do this, from the page'));
+    return send(await POSTS[verb](ctx, w, body, actor));
+  },
+};