create-pmos 0.130.0 → 0.132.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/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/pm-items.js

@@ -6,6 +6,10 @@
  * and the fold of the whole file is the current list. Stage is never stored; a list is derived from the due
  * date, priority and waiting-on fields by placement() below.
  *
+ * The Work page (console3) reads a second placement, workPlacement(), into five views: inbox, today, upcoming,
+ * waiting, someday. placement() and its five lists stay for the old routes. A sixth view, Review, is a queue
+ * (reviewQueue) of items nobody has touched for a week. fold() stamps `touched_at` from the event's `at`.
+ *
  * SINGLE WRITER: appendEvent() is the only function that writes the file. Callers pass the event; they never
  * choose `at` or `by` themselves (attribution comes from the call path, as in plan-items.js).
  */
@@ -14,6 +18,11 @@ const path = require('path');
 
 const UNDO_MS = 8000;
 const LISTS = ['waiting', 'today', 'week', 'triage', 'later'];
+const WORK_LISTS = ['inbox', 'today', 'upcoming', 'waiting', 'someday'];
+const REVIEW_DAYS = 7;
+const REVIEW_FROM = ['inbox', 'someday', 'waiting'];
+// A legacy list_override (set by /move) maps onto the Work views.
+const LEGACY_TO_WORK = { today: 'today', triage: 'inbox', waiting: 'waiting', week: 'upcoming', later: 'someday' };
 const WEEKDAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
 
 const DUE_WORD = /\b(?:due|by)\s+(today|tomorrow|sun(?:day)?|mon(?:day)?|tue(?:s(?:day)?)?|wed(?:nesday)?|thu(?:r(?:s(?:day)?)?)?|fri(?:day)?|sat(?:urday)?)\b/i;
@@ -66,15 +75,71 @@ function placement(item, today) {
   return 'later';
 }
 
+// Place an item in one of the five Work views (console3 PRD R2). The one place this is decided; the client never
+// copies an item between views. `today` is a Date. Rules, in order: a legacy override, parked is Someday, waiting
+// on someone is Waiting, a defer date after today is Upcoming, flagged is Today, due today or earlier is Today,
+// a later due date is Upcoming, no date is Inbox. One addition to R2, for R6 ("the item returns to Today on that
+// date"): an undated item whose defer date has arrived is Today, not Inbox.
+function workPlacement(item, today) {
+  if (item.list_override && LEGACY_TO_WORK[item.list_override]) return LEGACY_TO_WORK[item.list_override];
+  if (item.parked) return 'someday';
+  if (item.waiting_on) return 'waiting';
+  const t = iso(today);
+  if (item.defer && item.defer > t) return 'upcoming';
+  if (item.flagged) return 'today';
+  if (item.due && item.due <= t) return 'today';
+  if (item.due) return 'upcoming';
+  if (item.defer) return 'today';
+  return 'inbox';
+}
+
+const PRIORITY_RANK = { P1: 1, P2: 2, P3: 3 };
+const prio = (i) => PRIORITY_RANK[i.priority] || 9;
+const cmpStr = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+// The day an Upcoming item arrives: its defer date while that is still ahead, else its due date.
+function arrivesOn(item, todayIso) { return item.defer && item.defer > todayIso ? item.defer : (item.due || ''); }
+
+// Sort one Work view. today: overdue first (oldest first), then flagged, then by due date. upcoming: by arrival
+// day. inbox and someday: newest first. waiting: the one waited on longest first.
+function sortWorkList(name, items, today) {
+  const t = iso(today);
+  const byNew = (a, b) => cmpStr(b.created_at || '', a.created_at || '');
+  const out = [...items];
+  if (name === 'today') {
+    const group = (i) => (i.due && i.due < t ? 0 : i.flagged ? 1 : 2);
+    out.sort((a, b) => group(a) - group(b) || cmpStr(a.due || '9999', b.due || '9999') || prio(a) - prio(b) || byNew(a, b));
+  } else if (name === 'upcoming') {
+    out.sort((a, b) => cmpStr(arrivesOn(a, t) || '9999', arrivesOn(b, t) || '9999') || prio(a) - prio(b) || byNew(a, b));
+  } else if (name === 'waiting') {
+    out.sort((a, b) => cmpStr(a.waiting_since || a.created_at || '', b.waiting_since || b.created_at || ''));
+  } else out.sort(byNew);
+  return out;
+}
+
+// The review queue: open items in Inbox, Someday or Waiting that nobody touched for `days` days, most stale first.
+// `now` is a Date. An item with no readable touched_at is left out, never guessed.
+function reviewQueue(items, now, days = REVIEW_DAYS) {
+  const today = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+  const cutoff = now.getTime() - days * 86400000;
+  const stamp = (i) => Date.parse(i.touched_at || i.created_at || '');
+  return items
+    .filter((i) => !i.done && REVIEW_FROM.includes(workPlacement(i, today)) && Number.isFinite(stamp(i)) && stamp(i) <= cutoff)
+    .sort((a, b) => stamp(a) - stamp(b));
+}
+
 // Fold the event lines into the current items, keyed by id. A dropped or deleted item is removed.
 function fold(lines) {
   const items = new Map();
   for (const ev of lines) {
     if (!ev || !ev.id) continue;
-    if (ev.event === 'created') items.set(ev.id, { ...ev.fields, id: ev.id, source: ev.source || 'local', created_at: ev.at });
-    else if (ev.event === 'edited' && items.has(ev.id)) items.set(ev.id, { ...items.get(ev.id), ...ev.fields });
-    else if (ev.event === 'done' && items.has(ev.id)) items.set(ev.id, { ...items.get(ev.id), done: true, done_at: ev.at });
-    else if (ev.event === 'reopened' && items.has(ev.id)) items.set(ev.id, { ...items.get(ev.id), done: false, done_at: null });
+    if (ev.event === 'created') items.set(ev.id, { ...ev.fields, id: ev.id, source: ev.source || 'local', created_at: ev.at, touched_at: ev.at });
+    else if (ev.event === 'edited' && items.has(ev.id)) items.set(ev.id, { ...items.get(ev.id), ...ev.fields, touched_at: ev.at });
+    else if (ev.event === 'done' && items.has(ev.id)) {
+      const outcome = typeof ev.outcome === 'string' && ev.outcome.trim() ? { outcome: ev.outcome.trim() } : {};
+      items.set(ev.id, { ...items.get(ev.id), done: true, done_at: ev.at, touched_at: ev.at, ...outcome });
+    }
+    else if (ev.event === 'reopened' && items.has(ev.id)) items.set(ev.id, { ...items.get(ev.id), done: false, done_at: null, touched_at: ev.at });
+    else if (ev.event === 'kept' && items.has(ev.id)) items.set(ev.id, { ...items.get(ev.id), touched_at: ev.at });
     else if (ev.event === 'dropped' || ev.event === 'deleted') items.delete(ev.id);
   }
   return [...items.values()];
@@ -92,7 +157,7 @@ function removalEvent(item, now) {
 function undoEvent(lines, id, now = new Date()) {
   const removal = [...lines].reverse().find((ev) => ev && ev.id === id && (ev.event === 'deleted' || ev.event === 'dropped'));
   if (!removal || !removal.snapshot || !canUndo(removal.at, now)) return null;
-  const { id: _id, source, created_at, ...fields } = removal.snapshot;
+  const { id: _id, source, created_at, touched_at, ...fields } = removal.snapshot;
   return { event: 'created', id, fields, source: source || 'local', restored: true };
 }
 
@@ -112,4 +177,4 @@ function readLines(file) {
   return fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } });
 }
 
-module.exports = { UNDO_MS, LISTS, parseLine, placement, fold, removalEvent, undoEvent, canUndo, appendEvent, readLines };
+module.exports = { UNDO_MS, LISTS, WORK_LISTS, REVIEW_DAYS, workPlacement, sortWorkList, reviewQueue, arrivesOn, parseLine, placement, fold, removalEvent, undoEvent, canUndo, appendEvent, readLines };

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/report-needs.js

@@ -216,4 +216,4 @@ function sig(w) {
   return [reportsOf(w.root).sig, schedulesStamp(), kill, hour].join(':');
 }
 
-module.exports = { kinds, rowsFor, sig, rowsAt, reportsOf, cadenceOfSkill, cadenceOfSchedule, blobSha, reportsDir, KILL_FILE, GRACE_MS };
+module.exports = { kinds, rowsFor, sig, rowsAt, reportsOf, readSchedules, cadenceOfSkill, cadenceOfSchedule, blobSha, reportsDir, KILL_FILE, GRACE_MS };

package/workspace/lib/route-modules.js

@@ -61,6 +61,7 @@ const MODULES = Object.freeze([
   '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-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-calendar-views.js

@@ -1,7 +1,8 @@
 'use strict';
 /* routes-calendar-views.js — GET /api/calendar-views?view=day|week|month|quarter|year&date=YYYY-MM-DD&ws=<id> (console3 wave C2).
  *
- *   → { ok, view, range, cells, unit, gantt, strategy, events_source }
+ *   → { ok, view, range, cells, unit, gantt, strategy, events_source, today,
+ *       layers, layers_total, layers_note, free, context, context_total }     (the last six: lib/calendar-layers.js)
  *
  * READ ONLY. Initiatives come from the signal engine's repo reader (scripts/signals/facts.js readRepoFacts), required inside
  * the handler so a failure answers 500 { ok:false } and never reaches the server. The date and the plan come from the records:
@@ -13,10 +14,12 @@
  * gets none and says so. */
 const path = require('path');
 const model = require('../../scripts/calendar-model.js');
+const layersLib = require('./calendar-layers.js');
 
 const today = () => { const d = new Date(); const p = (n) => String(n).padStart(2, '0'); return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`; };
 
-/** The pure handler. deps: { readFacts(root), readEvents?(range), readKrs?(), today } so tests need no repo. */
+/** The pure handler. deps: { readFacts(), readEvents?(range), readKrs?(), today, nowMs?, readDated?(range), readItems?(),
+ *  readContextSources?() } so tests need no repo. A dep that is missing gives its source as empty, said in layers_note. */
 function handle(query, deps = {}) {
   const view = (query && query.view) || 'month';
   const date = (query && query.date) || (deps.today || today());
@@ -33,13 +36,118 @@ function handle(query, deps = {}) {
     const nowDay = deps.today || today();
     const gantt = model.ganttRows(inis, view, date, { today: nowDay });
     const strategy = view === 'quarter' || view === 'year' ? model.strategyLens(inis, krs, nowDay) : null;
-    return { status: 200, body: { ok: true, view, range, unit: b.unit, cells: b.cells, gantt, strategy, events_source: source, today: nowDay } };
+    const dated = typeof deps.readDated === 'function' ? (deps.readDated(range) || {}) : {
+      unavailable: { plan_items: 'no reader is wired', releases: 'no reader is wired', reports: 'no reader is wired', own: 'no reader is wired' } };
+    // the initiatives come from the facts this handler already holds, so every caller gets their promised dates
+    if (!dated.initiatives && !(dated.unavailable && dated.unavailable.initiatives)) dated.initiatives = inis;
+    const items = typeof deps.readItems === 'function' ? (deps.readItems() || {}) : {};
+    const src = typeof deps.readContextSources === 'function' ? (deps.readContextSources() || {}) : {};
+    const nowMs = Number.isFinite(deps.nowMs) ? deps.nowMs : (deps.today ? undefined : Date.now());
+    const extra = layersLib.build({ range, today: nowDay, nowMs, events, dated, src, own: items.own, planItemsDue: items.planItems });
+    return { status: 200, body: { ok: true, view, range, unit: b.unit, cells: b.cells, gantt, strategy, events_source: source, today: nowDay, ...extra } };
   } catch (e) {
     return { status: 500, body: { ok: false, error: String(e && e.message || e) } };
   }
 }
 
+/* ── the readers behind the layers, free time and context (each source on its own: one that cannot be read is named in
+ *    layers_note and gives nothing; it never takes the answer down) ────────────────────────────────────────────────── */
+const reason = (e) => String((e && e.message) || e).slice(0, 160);
+
+function readers(root, runtimeDir) {
+  let plan = null;
+  const planFold = () => { if (!plan) plan = require('./plan-items.js').readFold(root); return plan; };
+  const planRows = () => Object.values(planFold().items).filter((p) => !(p.proposed && !p.kept));
+  let ownLines = null;
+  const ownRows = () => {
+    if (!ownLines) ownLines = require('./pm-items.js').readLines(path.join(runtimeDir, 'pm-items', 'items.jsonl'));
+    return require('./pm-items.js').fold(ownLines);
+  };
+  const planItem = (p) => ({ id: p.id, initiative: p.initiative, title: p.title, due: p.due, milestone: !!p.milestone, state: p.state });
+  return {
+    readDated(range) {
+      const unavailable = {};
+      const out = { unavailable };
+      try { out.planItems = planRows().map(planItem); } catch (e) { unavailable.plan_items = 'the plan ledger could not be read: ' + reason(e); }
+      try {
+        const R = require('../../scripts/releases.js');
+        const f = path.join(runtimeDir, 'releases', 'releases.jsonl');
+        let lines = []; try { lines = require('fs').readFileSync(f, 'utf8').split('\n').filter(Boolean); } catch { lines = []; }
+        out.releases = R.foldReleases(lines);
+      } catch (e) { unavailable.releases = 'the releases file could not be read: ' + reason(e); }
+      try {
+        const RN = require('./report-needs.js');
+        out.reports = RN.reportsOf(root).reports.map((r) => ({ cadence: r.cadence, slot: r.slot, issued: r.issued ? { at: r.issued.at } : null }));
+        out.reportSchedules = reportSchedules(RN, range);
+      } catch (e) { unavailable.reports = 'the report folders could not be read: ' + reason(e); }
+      try { out.own = ownRows().map((o) => ({ id: o.id, title: o.title, due: o.due, done: !!o.done })); } catch (e) { unavailable.own = 'your items could not be read: ' + reason(e); }
+      return out;
+    },
+    readItems() {
+      const out = { own: [], planItems: [] };
+      try { out.planItems = planRows().map(planItem); } catch { /* the plan ledger is named in layers_note */ }
+      try { out.own = ownRows().map((o) => ({ id: o.id, title: o.title, due: o.due, done: !!o.done, priority: o.priority || null })); } catch { /* likewise */ }
+      return out;
+    },
+    readContextSources() {
+      const src = { notes: [], planItems: [], ownItems: [] };
+      try { src.planItems = planRows().map((p) => ({ id: p.id, initiative: p.initiative, title: p.title, createdAt: p.createdAt, doneAt: p.doneAt })); } catch { /* no plan ledger: no moved items */ }
+      try { src.ownItems = ownRows().map((o) => ({ id: o.id, title: o.title, initiative: o.initiative || null, created_at: o.created_at || null, done_at: o.done_at || null })); } catch { /* no own items */ }
+      try { src.notes = linkedNotes(runtimeDir); } catch { /* no notes: no decisions or actions */ }
+      return src;
+    },
+  };
+}
+
+/** The dates a report schedule fires on, from the range start, using the same slot math the scheduler runs on. */
+function reportSchedules(RN, range) {
+  const logic = require('./schedule-logic.js');
+  const out = [];
+  const t0 = new Date();
+  const today = `${t0.getFullYear()}-${String(t0.getMonth() + 1).padStart(2, '0')}-${String(t0.getDate()).padStart(2, '0')}`;
+  const first = range && range.start > today ? range.start : today;
+  const from = new Date(Number(first.slice(0, 4)), Number(first.slice(5, 7)) - 1, Number(first.slice(8, 10)));
+  for (const s of RN.readSchedules()) {
+    if (!s || !s.enabled) continue;
+    const cadence = RN.cadenceOfSchedule(s);
+    if (!cadence) continue;
+    const dates = [];
+    let at = from;
+    for (let i = 0; i < 62; i++) {
+      const next = logic.nextRun(s, at);
+      if (!next) break;
+      const d = new Date(next);
+      const ds = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+      if (range && ds > range.end) break;
+      dates.push(ds);
+      at = new Date(d.getTime() + 1000);
+    }
+    out.push({ id: String(s.id || s.name || cadence), name: s.name, cadence, dates: [...new Set(dates)] });
+  }
+  return out;
+}
+
+/** Notes linked to a calendar event, read straight from the notes folder (no import, no write). */
+function linkedNotes(runtimeDir) {
+  const fs = require('fs');
+  const dir = path.join(runtimeDir, 'notes');
+  const out = [];
+  for (const f of fs.readdirSync(dir).filter((x) => x.endsWith('.json'))) {
+    let n; try { n = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')); } catch { continue; }
+    if (!n || !n.id || !n.meeting || n.meeting.kind !== 'event') continue;
+    const fin = n.final_notes && typeof n.final_notes === 'object' ? n.final_notes : null;
+    const sec = n.summary && n.summary.sections ? n.summary.sections : null;
+    const pick = (a, b) => (Array.isArray(a) && a.length ? a : Array.isArray(b) ? b : []);
+    out.push({ id: n.id, title: n.title || '', private: !!n.private, initiative: n.initiative && n.initiative.id ? String(n.initiative.id) : null,
+      meeting: { event_id: n.meeting.event_id || null, start: n.meeting.start, title: n.meeting.title },
+      decisions: pick(fin && fin.decisions, sec && sec.decisions).map((x) => ({ text: x && x.text })),
+      actions: pick(fin && fin.actions, sec && sec.actions).map((x) => ({ text: x && x.text, owner: x && x.owner || null, due: x && x.due || null })) });
+  }
+  return out;
+}
+
 module.exports = {
+  readers,
   prefixes: ['/api/calendar-views'],
   handlePure: handle,
   handle: async (req, res, url, ctx) => {
@@ -54,6 +162,7 @@ module.exports = {
     const out = handle({ view: url.searchParams.get('view') || undefined, date: url.searchParams.get('date') || undefined }, {
       readFacts: () => facts,
       readEvents: () => require('./routes-calendar-import.js').readEvents(ctx.runtimeDir),
+      ...readers(root, ctx.runtimeDir),
     });
     ctx.json(res, out.body, out.status);
     return true;

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 };