create-pmos 0.130.0 → 0.132.0

package/workspace/lib/calendar-cli.js

@@ -0,0 +1,84 @@
+'use strict';
+/* calendar-cli.js — `pmos calendar …`: the calendar events an agent session read, saved for Briefing and Calendar
+ * (workspace-data-freshness R8).
+ *   pmos calendar import --from <file|-> --sensitivity public|internal|confidential|private [--dry-run] [--json]
+ *   pmos calendar status [--json]
+ * This command never talks to a calendar. The calendar-sync skill reads it in an agent session, with the PM's own
+ * connection, and hands the events to `import`. The import goes through scripts/calendar-import.js unchanged: hidden text
+ * is stripped, every line is marked, the raw text is hashed, and a missing sensitivity is refused. The events are kept in
+ * the per-user runtime folder, never in a repository.
+ */
+const fs = require('fs');
+const path = require('path');
+const stateRoot = require('./state-root');
+const CI = require('../../scripts/calendar-import.js');
+const L = require('../../scripts/trust/ledger.js');
+
+const COMMANDS = { calendar: ['import', 'status'] };
+const USAGE = [
+  'usage: pmos calendar import|status — the calendar events an agent session read for Briefing and Calendar',
+  '  pmos calendar import --from <file|-> --sensitivity <label> [--dry-run]   save the events (the calendar-sync skill runs this)',
+  '  pmos calendar status                                   how many events are saved, and when they were read',
+  '  every command: [--json]',
+  'This command never calls a calendar. Your agent reads it with your own connection.',
+];
+const BOOL = new Set(['json', 'dry-run', 'help']);
+const VALUE = new Set(['from', 'sensitivity']);
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (!t.startsWith('--')) { out._.push(t); continue; }
+    const eq = t.indexOf('=');
+    const key = eq > 0 ? t.slice(2, eq) : t.slice(2);
+    if (BOOL.has(key)) out[key] = true;
+    else if (eq > 0) out[key] = t.slice(eq + 1);
+    else if (VALUE.has(key) && argv[i + 1] !== undefined) out[key] = argv[++i];
+    else out[key] = '';
+  }
+  return out;
+}
+
+const ledgerOf = (dir) => path.join(dir, 'calendar-import', 'events.jsonl');
+
+function readInput(from, stdin) {
+  if (from === '-') return stdin();
+  return fs.readFileSync(path.resolve(from), 'utf8');
+}
+
+async function run(argv, { say = console.log, env = process.env, stateDir, stdin = () => fs.readFileSync(0, 'utf8'), now = () => new Date(), isTTY } = {}) {
+  const a = parseArgs(argv.slice(1));
+  const sub = a._ && a._[0];
+  const out = (o, line) => { if (a.json) say(JSON.stringify(o)); else say(line); };
+  if (!sub || a.help || sub === 'help') { USAGE.forEach((l) => say(l)); return sub || a.help ? 0 : 2; }
+  if (!COMMANDS.calendar.includes(sub)) { say(`✗ pmos calendar ${sub} is not a command`); USAGE.forEach((l) => say(l)); return 2; }
+  const dir = stateDir || stateRoot.defaultRoot({ env });
+  const file = ledgerOf(dir);
+
+  if (sub === 'status') {
+    const events = CI.foldEvents(CI.readLines(file));
+    const last = events.reduce((m, e) => (e.fetched_at && e.fetched_at > m ? e.fetched_at : m), '');
+    out({ ok: true, events: events.length, read_at: last || null }, events.length ? `${events.length} events saved, last read ${last}` : 'no calendar events are saved yet');
+    return 0;
+  }
+
+  if (!a.from) { say('✗ --from <file|-> is required'); return 2; }
+  let raw;
+  try { raw = JSON.parse(readInput(a.from, stdin)); } catch (e) { say(`✗ the events file is not JSON: ${String(e.message).slice(0, 160)}`); return 1; }
+  const list = Array.isArray(raw) ? raw : raw && Array.isArray(raw.events) ? raw.events : null;
+  if (!list) { say('✗ the file must hold a list of events, or { "events": [ … ] }'); return 1; }
+  const at = now().toISOString();
+  let evs;
+  try { evs = CI.importEvents(list, { fetchedAt: at, sensitivity: a.sensitivity }); }
+  catch (e) { say(`✗ ${e.message}`); return 1; }
+  if (a['dry-run']) { out({ ok: true, dryRun: true, count: evs.length }, `would save ${evs.length} events (dry run, nothing written)`); return 0; }
+  const actor = L.actorFrom({ env, isTTY: isTTY == null ? !!(process.stdin.isTTY && process.stdout.isTTY) : isTTY });
+  try { CI.appendImport(file, evs, actor, at); }
+  catch (e) { say(`✗ the events could not be saved: ${String(e.message).slice(0, 160)}`); return 1; }
+  const flagged = evs.filter((e) => e.findings && e.findings.length).length;
+  out({ ok: true, count: evs.length, flagged, read_at: at }, `✓ saved ${evs.length} calendar events${flagged ? ` (${flagged} carried hidden or suspicious text, marked)` : ''}`);
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/calendar-layers.js

@@ -0,0 +1,372 @@
+'use strict';
+/* calendar-layers.js — the pure part of the console3 Calendar page's server answer (initiative calendar-time-page, R2 to R5, R8).
+ *
+ *   layersFrom(dated, range, today)                  → { layers, layers_total, layers_note }   dated items inside the range
+ *   freeFrom(events, range, today, opts)             → { min_minutes, day_start, day_end, days, count }
+ *   contextFrom(events, range, src, opts)            → { context, context_total }              keyed by event id
+ *   build({ range, today, nowMs, events, dated, src, view })   all three, for routes-calendar-views.js
+ *
+ * No I/O and no clock: `today` comes in as 'YYYY-MM-DD', `nowMs` as a number. Nothing is invented. A source with no reader
+ * is named in layers_note with the reason, and gives no item. Meetings are not layers; they stay in `cells`.
+ *
+ * INPUT SHAPES (plain data; the route reads them from the repository and the per-user store).
+ *   dated = { initiatives:[{id,title,promised,done}], planItems:[{id,initiative,title,due,milestone,state}],
+ *             releases:[{id,type,fix_version,deploy_at,release_at}], reports:[{cadence,slot,issued}],
+ *             reportSchedules:[{id,name,cadence,dates:['YYYY-MM-DD']}], own:[{id,title,due,done}], unavailable:{ source: why } }
+ *   src   = { notes:[{id,title,private,meeting:{event_id,start,title},initiative,decisions:[{text}],actions:[{text,owner,due}]}],
+ *             planItems:[{id,initiative,title,createdAt,doneAt}], ownItems:[{id,title,initiative,created_at,done_at}] }
+ *   event = the imported event ({ id, at, end, title, initiative, pm_notes, agent_prep_notes, prep, prep_done, steps }).
+ *
+ * TONE. bad: past its date and not done. warn: due today up to 2 days ahead and not done. ok: done. Otherwise null.
+ * FREE TIME. Working days only (Monday to Friday), from DAY_START to DAY_END, a block of min_minutes or more (calendar-memory's
+ * dayLoad). Days before today are left out: free time that has passed cannot be used. An event with a date and no time (all day)
+ * does not block; an event with no end lasts 30 minutes. Quarter and Year answer days:[] and the count only. */
+const memory = require('./calendar-memory.js');
+
+const DAY_MS = 86400000;
+const LAYER_CAP = 400;
+const CONTEXT_CAP = 60;
+const MIN_BLOCK = memory.FREE_BLOCK;     // 90
+const PER_STEP = memory.PER_STEP;        // 30 minutes of free time for each prep step left
+const PER_DAY = 60;                      // minutes of a whole working day before the meeting that count toward its prep
+const DAY_START = 9 * 60;
+const DAY_END = 18 * 60;
+const WARN_DAYS = 2;
+const SUGGEST_DAYS = 7;
+const WINDOW_MS = 48 * 3600000;
+const PER_KIND = { decision: 6, action: 6, moved: 8, prepared: 8, todo: 8 };
+const LIGHT_VIEWS = ['quarter', 'year'];
+
+const pad = (n) => String(n).padStart(2, '0');
+const isDay = (s) => typeof s === 'string' && /^\d{4}-\d{2}-\d{2}/.test(s) && !Number.isNaN(Date.parse(s.slice(0, 10) + 'T00:00:00Z'));
+const day10 = (s) => String(s).slice(0, 10);
+const hasTime = (s) => typeof s === 'string' && /T\d{2}:\d{2}/.test(s);
+const ymdMs = (s) => Date.parse(day10(s) + 'T00:00:00Z');
+const addDays = (s, n) => new Date(ymdMs(s) + n * DAY_MS).toISOString().slice(0, 10);
+const diffDays = (a, b) => Math.round((ymdMs(a) - ymdMs(b)) / DAY_MS);
+const dow = (s) => new Date(ymdMs(s)).getUTCDay();                  // 0 Sunday
+const isWorkday = (s) => dow(s) >= 1 && dow(s) <= 5;
+const hhmm = (m) => `${pad(Math.floor(m / 60))}:${pad(m % 60)}`;
+const localMs = (s) => { const [y, m, d] = day10(s).split('-').map(Number); return new Date(y, m - 1, d).getTime(); };
+const localDay = (ms) => { const d = new Date(ms); return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`; };
+const minuteOfDay = (ms) => { const d = new Date(ms); return d.getHours() * 60 + d.getMinutes(); };
+const str = (v) => (typeof v === 'string' ? v.trim() : '');
+const norm = (t) => String(t || '').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, ' ').trim();
+const inRange = (d, range) => d >= range.start && d <= range.end;
+const overlaps = (a, b, range) => a <= range.end && b >= range.start;
+
+/* ── layers ────────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function toneOf(date, done, today) {
+  if (done) return 'ok';
+  if (date < today) return 'bad';
+  if (diffDays(date, today) <= WARN_DAYS) return 'warn';
+  return null;
+}
+
+function layersFrom(dated, range, today) {
+  const d = dated || {};
+  const out = [];
+  const note = {};
+  const dateless = {};                       // source -> items that carry a date at all (in range or not)
+  const inside = {};                         // source -> items inside the range
+  const put = (source, x) => {
+    dateless[source] = (dateless[source] || 0) + 1;
+    const end = x.end && x.end > x.date ? x.end : null;
+    if (!overlaps(x.date, end || x.date, range)) return;
+    inside[source] = (inside[source] || 0) + 1;
+    const { end: _e, ...rest } = x;
+    out.push(end ? { ...rest, end } : rest);
+  };
+  const unavailable = d.unavailable && typeof d.unavailable === 'object' ? d.unavailable : {};
+  const why = (source, fallback) => { if (unavailable[source]) note[source] = String(unavailable[source]); else if (fallback) note[source] = fallback; };
+
+  // initiatives: the promised date
+  if (unavailable.initiatives) why('initiatives');
+  else {
+    let n = 0;
+    for (const i of d.initiatives || []) {
+      if (!i || !i.id || !isDay(i.promised)) continue;
+      n++;
+      const date = day10(i.promised);
+      put('initiatives', { id: `ini:${i.id}:promised`, date, kind: 'milestone', layer: 'milestones', title: str(i.title) || i.id, tone: toneOf(date, !!i.done, today), ref: { type: 'initiative', id: i.id }, initiative: i.id });
+    }
+    if (!n) why('initiatives', 'no initiative has a promised date');
+  }
+  // plan items: a milestone or a due date
+  if (unavailable.plan_items) why('plan_items');
+  else {
+    let n = 0;
+    for (const p of d.planItems || []) {
+      if (!p || !p.id || !isDay(p.due)) continue;
+      n++;
+      const date = day10(p.due);
+      put('plan_items', { id: `plan:${p.id}:${p.milestone ? 'milestone' : 'due'}`, date, kind: p.milestone ? 'milestone' : 'due', layer: 'milestones', title: str(p.title) || p.id,
+        tone: toneOf(date, p.state === 'done', today), ref: { type: 'plan-item', id: p.id }, ...(p.initiative ? { initiative: p.initiative } : {}) });
+    }
+    if (!n) why('plan_items', 'no plan item has a due date');
+  }
+  // releases
+  if (unavailable.releases) why('releases');
+  else {
+    let n = 0;
+    for (const r of d.releases || []) {
+      if (!r || !r.id) continue;
+      const dep = isDay(r.deploy_at) ? day10(r.deploy_at) : null; const rel = isDay(r.release_at) ? day10(r.release_at) : null;
+      const date = dep || rel; if (!date) continue;
+      n++;
+      const last = rel || dep;
+      put('releases', { id: `rel:${r.id}`, date, ...(last > date ? { end: last } : {}), kind: 'release', layer: 'releases', title: str(r.fix_version) || `Release ${str(r.type) || r.id}`,
+        tone: null, ref: { type: 'release', id: r.id } });
+    }
+    if (!n) why('releases', 'no release has a deploy or release date');
+  }
+  // reports: the issue date of a report file, and the next runs of a report schedule
+  if (unavailable.reports) why('reports');
+  else {
+    let n = 0;
+    for (const r of d.reports || []) {
+      if (!r || !r.cadence || !isDay(r.slot)) continue;
+      const date = r.issued && isDay(r.issued.at) ? day10(r.issued.at) : day10(r.slot);
+      n++;
+      put('reports', { id: `report:${r.cadence}:${day10(r.slot)}`, date, kind: 'report', layer: 'reports', title: `${r.cadence} report${r.issued ? '' : ' (not issued)'}`,
+        tone: r.issued ? 'ok' : null, ref: { type: 'report', id: `${r.cadence}/${day10(r.slot)}` } });
+    }
+    for (const s of d.reportSchedules || []) {
+      if (!s || !s.id) continue;
+      for (const dt of s.dates || []) {
+        if (!isDay(dt)) continue;
+        n++;
+        put('reports', { id: `report-sched:${s.id}:${day10(dt)}`, date: day10(dt), kind: 'report', layer: 'reports', title: `${str(s.name) || s.cadence || s.id} (scheduled)`, tone: null,
+          ref: { type: 'report', id: s.cadence || s.id } });
+      }
+    }
+    if (!n) why('reports', 'no report file and no report schedule gives an issue date');
+  }
+  // the PM's own items with a due date: markers only
+  if (unavailable.own) why('own');
+  else {
+    let n = 0;
+    for (const o of d.own || []) {
+      if (!o || !o.id || !isDay(o.due)) continue;
+      n++;
+      const date = day10(o.due);
+      put('own', { id: `own:${o.id}`, date, kind: 'own', layer: 'mine', title: str(o.title) || o.id, tone: toneOf(date, !!o.done, today), ref: { type: 'item', id: o.id } });
+    }
+    if (!n) why('own', 'none of your own items has a due date');
+  }
+  out.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : a.title < b.title ? -1 : a.title > b.title ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const layers = out.slice(0, LAYER_CAP);
+  // a source that read fine but has nothing inside this range says so too, so an empty layer is never a silent one
+  for (const source of ['initiatives', 'plan_items', 'releases', 'reports', 'own']) {
+    if (note[source]) continue;
+    if (dateless[source] && !inside[source]) note[source] = 'nothing dated falls inside this range';
+  }
+  return { layers, layers_total: out.length, layers_note: note };
+}
+
+/* ── free time ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+/** An event as a span in epoch ms, or null for an all-day event or one with no usable start. */
+function spanOf(e) {
+  if (!e || !hasTime(e.at || e.start)) return null;
+  const s = Date.parse(e.at || e.start);
+  if (!Number.isFinite(s)) return null;
+  let f = e.end ? Date.parse(e.end) : s + 30 * 60000;
+  if (!Number.isFinite(f) || f < s) f = s + 30 * 60000;
+  return { s, f };
+}
+
+/** Meetings that touch `date`, as minutes of that day. */
+function minutesOn(spans, date) {
+  const a = localMs(date); const b = a + DAY_MS;
+  const out = [];
+  for (const sp of spans) {
+    if (sp.f <= a || sp.s >= b) continue;
+    out.push({ from: sp.s <= a ? 0 : minuteOfDay(sp.s), to: sp.f >= b ? 1440 : minuteOfDay(sp.f) });
+  }
+  return out;
+}
+
+/** Free minutes inside working hours between two minutes of a day, given the merged busy intervals. */
+function freeBetween(merged, from, until) {
+  const a = Math.max(DAY_START, from); const b = Math.min(DAY_END, until);
+  if (b <= a) return 0;
+  let busy = 0;
+  for (const [s, e] of merged) busy += Math.max(0, Math.min(e, b) - Math.max(s, a));
+  return b - a - busy;
+}
+
+/** The prep steps of an event: { steps:[text], done:n }. Reads prep / prep_done, else steps.before. */
+function prepOf(e) {
+  if (!e) return { steps: [], done: 0 };
+  if (Array.isArray(e.prep) && e.prep.length) {
+    const steps = e.prep.map((x) => str(typeof x === 'string' ? x : x && (x.t || x.text))).filter(Boolean);
+    const done = Math.min(steps.length, Math.max(0, Number(e.prep_done) || 0));
+    return { steps, done, doneFlags: steps.map((_, i) => i < done) };
+  }
+  const before = e.steps && Array.isArray(e.steps.before) ? e.steps.before : [];
+  const steps = before.map((x) => str(x && (x.t || x.text))).filter(Boolean);
+  const flags = before.filter((x) => str(x && (x.t || x.text))).map((x) => !!x.done);
+  return { steps, done: flags.filter(Boolean).length, doneFlags: flags };
+}
+
+function nextWorkday(date) { let d = addDays(date, 1); while (!isWorkday(d)) d = addDays(d, 1); return d; }
+
+function freeFrom(events, range, today, opts = {}) {
+  const view = range.view;
+  const nowMs = Number.isFinite(opts.nowMs) ? opts.nowMs : localMs(today);
+  const spans = (events || []).map((e) => ({ e, ...(spanOf(e) || {}) })).filter((x) => x.s !== undefined);
+  const memo = new Map();
+  const loadOf = (date) => { if (!memo.has(date)) memo.set(date, memory.dayLoad(minutesOn(spans, date))); return memo.get(date); };
+
+  // prep at risk: a coming event with steps left and less free time before it than PER_STEP for each step
+  const risky = [];
+  for (const x of spans) {
+    const p = prepOf(x.e);
+    const left = p.steps.length - p.done;
+    if (!left || x.f <= nowMs) continue;
+    const date = localDay(x.s);
+    const startMin = minuteOfDay(x.s);
+    let free = freeBetween(loadOf(date).merged, date === today ? minuteOfDay(nowMs) : DAY_START, startMin);
+    for (let dd = today; dd < date; dd = addDays(dd, 1)) {
+      if (!isWorkday(dd)) continue;
+      free += Math.min(PER_DAY, freeBetween(loadOf(dd).merged, dd === today ? minuteOfDay(nowMs) : DAY_START, DAY_END));
+    }
+    if (free < left * PER_STEP) risky.push({ id: x.e.id, title: str(x.e.title) || 'a meeting', date, s: x.s, left });
+  }
+  risky.sort((a, b) => a.s - b.s);
+
+  // items due soon, most pressing first: overdue and nearest due date, then the higher priority, then the title
+  const prio = (p) => (/^P[1-3]$/.test(String(p || '')) ? Number(String(p)[1]) : 9);
+  const due = [];
+  for (const o of opts.own || []) if (o && o.id && !o.done && isDay(o.due)) due.push({ id: o.id, type: 'item', title: str(o.title) || o.id, due: day10(o.due), p: prio(o.priority) });
+  for (const p of opts.planItems || []) if (p && p.id && p.state !== 'done' && isDay(p.due)) due.push({ id: p.id, type: 'plan-item', title: str(p.title) || p.id, due: day10(p.due), p: 5 });
+  due.sort((a, b) => (a.due < b.due ? -1 : a.due > b.due ? 1 : a.p - b.p || (a.title < b.title ? -1 : a.title > b.title ? 1 : a.id < b.id ? -1 : 1)));
+
+  const usedEvent = new Set(); const usedItem = new Set();
+  const suggest = (date, block) => {
+    const next = nextWorkday(date);
+    const hit = risky.find((r) => !usedEvent.has(r.id) && (r.date === next || (r.date === date && r.s >= localMs(date) + block.from * 60000)));
+    if (hit) {
+      usedEvent.add(hit.id);
+      return { text: `Prepare for "${hit.title}": ${hit.left} ${hit.left === 1 ? 'step is' : 'steps are'} left and little free time remains before it.`, ref: { type: 'event', id: hit.id } };
+    }
+    const top = due.find((x) => !usedItem.has(x.id) && diffDays(x.due, date) <= SUGGEST_DAYS);
+    if (top) {
+      usedItem.add(top.id);
+      return { text: top.due < date ? `Work on "${top.title}". It was due ${top.due}.` : `Work on "${top.title}". It is due ${top.due}.`, ref: { type: top.type, id: top.id } };
+    }
+    return null;
+  };
+
+  const days = []; let count = 0;
+  const light = LIGHT_VIEWS.includes(view);
+  for (let dd = range.start < today ? today : range.start; dd <= range.end; dd = addDays(dd, 1)) {
+    if (!isWorkday(dd)) continue;
+    const blocks = loadOf(dd).gaps.map(([a, b]) => ({ from: hhmm(a), to: hhmm(b), minutes: b - a, _a: a, _b: b }));
+    count += blocks.length;
+    if (light) continue;
+    const out = blocks.map((b) => ({ from: b.from, to: b.to, minutes: b.minutes, suggestion: suggest(dd, { from: b._a, to: b._b }) }));
+    if (out.length) days.push({ date: dd, blocks: out });
+  }
+  return { min_minutes: MIN_BLOCK, day_start: hhmm(DAY_START), day_end: hhmm(DAY_END), days, count };
+}
+
+/* ── context ───────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function noteMatches(n, e) {
+  const m = n && n.meeting;
+  if (!m) return false;
+  if (m.event_id && e.id && String(m.event_id) === String(e.id)) return true;
+  const a = Date.parse(m.start); const b = Date.parse(e.at || e.start);
+  return Number.isFinite(a) && Number.isFinite(b) && Math.floor(a / 60000) === Math.floor(b / 60000) && norm(m.title) === norm(e.title);
+}
+
+function referencesEvent(text, e) {
+  const t = norm(text);
+  if (!t) return false;
+  if (e.id && t.includes(norm(e.id)) && norm(e.id).length >= 6) return true;
+  const title = norm(e.title);
+  return title.length >= 4 && t.includes(title);
+}
+
+function movedBy(e, eventEnd, src) {
+  const lo = eventEnd; const hi = eventEnd + WINDOW_MS;
+  const within = (iso) => { const t = Date.parse(iso); return Number.isFinite(t) && t >= lo && t <= hi; };
+  const out = [];
+  const same = (ini, text) => (ini && e.initiative && ini === e.initiative) || referencesEvent(text, e);
+  for (const p of src.planItems || []) {
+    if (!p || !p.id || !same(p.initiative, p.title)) continue;
+    if (within(p.createdAt)) out.push({ kind: 'moved', text: `Created plan item: ${str(p.title) || p.id}`, ref: { type: 'plan-item', id: p.id }, at: p.createdAt });
+    if (within(p.doneAt)) out.push({ kind: 'moved', text: `Closed plan item: ${str(p.title) || p.id}`, ref: { type: 'plan-item', id: p.id }, at: p.doneAt });
+  }
+  for (const o of src.ownItems || []) {
+    if (!o || !o.id || !same(o.initiative, o.title)) continue;
+    if (within(o.created_at)) out.push({ kind: 'moved', text: `Created your item: ${str(o.title) || o.id}`, ref: { type: 'item', id: o.id }, at: o.created_at });
+    if (within(o.done_at)) out.push({ kind: 'moved', text: `Closed your item: ${str(o.title) || o.id}`, ref: { type: 'item', id: o.id }, at: o.done_at });
+  }
+  out.sort((a, b) => Date.parse(a.at) - Date.parse(b.at) || (a.text < b.text ? -1 : 1));
+  return out;
+}
+
+function capKinds(items) {
+  const n = {};
+  return items.filter((x) => { n[x.kind] = (n[x.kind] || 0) + 1; return n[x.kind] <= (PER_KIND[x.kind] || 8); });
+}
+
+function contextFrom(events, range, src, opts = {}) {
+  const s = src || {};
+  const today = opts.today;
+  const nowMs = Number.isFinite(opts.nowMs) ? opts.nowMs : localMs(today);
+  const inside = [];
+  for (const e of events || []) {
+    const at = e && (e.at || e.start);
+    if (!e || !e.id || !isDay(at)) continue;
+    const a = day10(at); const b = e.end && isDay(e.end) ? day10(e.end) : a;
+    if (overlaps(a, b < a ? a : b, range)) inside.push(e);
+  }
+  const mid = (e) => (spanOf(e) ? spanOf(e).s : localMs(e.at || e.start));
+  inside.sort((x, y) => Math.abs(mid(x) - nowMs) - Math.abs(mid(y) - nowMs) || (String(x.id) < String(y.id) ? -1 : 1));
+  const context = {};
+  for (const e of inside.slice(0, CONTEXT_CAP)) {
+    const sp = spanOf(e);
+    const endMs = sp ? sp.f : localMs(e.end && isDay(e.end) ? e.end : e.at) + DAY_MS;     // an all-day event ends at the end of its day
+    const past = endMs <= nowMs;
+    const notes = (s.notes || []).filter((n) => noteMatches(n, e));
+    const items = [];
+    if (past) {
+      for (const n of notes) {
+        if (n.private) continue;                       // a private note shows its title and nothing of its content
+        for (const d of n.decisions || []) if (str(d && d.text)) items.push({ kind: 'decision', text: str(d.text), ref: { type: 'note', id: n.id } });
+        for (const a of n.actions || []) {
+          if (!str(a && a.text)) continue;
+          const tail = [a.owner && `owner: ${a.owner}`, a.due && `due: ${a.due}`].filter(Boolean).join(', ');
+          items.push({ kind: 'action', text: str(a.text) + (tail ? ` (${tail})` : ''), ref: { type: 'note', id: n.id } });
+        }
+      }
+      const moved = movedBy({ ...e, initiative: e.initiative || (notes.find((n) => n.initiative) || {}).initiative || null }, endMs, s);
+      items.push(...moved);
+    } else {
+      const p = prepOf(e);
+      p.steps.forEach((t, i) => items.push({ kind: p.doneFlags && p.doneFlags[i] ? 'prepared' : 'todo', text: t, ref: { type: 'event', id: e.id } }));
+      if (str(e.agent_prep_notes)) items.push({ kind: 'prepared', text: 'Prep notes from your agent session are saved.', ref: { type: 'event', id: e.id } });
+      for (const m of e.pm_notes || []) if (str(m && m.text)) items.push({ kind: 'prepared', text: `Your note: ${str(m.text)}`, ref: { type: 'event', id: e.id }, ...(m.at ? { at: m.at } : {}) });
+      for (const n of notes) items.push({ kind: 'prepared', text: `A meeting note is linked: ${str(n.title) || n.id}`, ref: { type: 'note', id: n.id } });
+    }
+    const kept = capKinds(items);
+    context[e.id] = { phase: past ? 'past' : 'upcoming', held: kept.length > 0, items: kept };
+  }
+  return { context, context_total: inside.length };
+}
+
+/* ── all three ─────────────────────────────────────────────────────────────────────────────────────────────────── */
+
+function build({ range, today, nowMs, events, dated, src, own, planItemsDue }) {
+  const l = layersFrom(dated, range, today);
+  const free = freeFrom(events, range, today, { nowMs, own: own || (dated && dated.own) || [], planItems: planItemsDue || (dated && dated.planItems) || [] });
+  const c = contextFrom(events, range, src, { today, nowMs });
+  return { layers: l.layers, layers_total: l.layers_total, layers_note: l.layers_note, free, context: c.context, context_total: c.context_total };
+}
+
+module.exports = { layersFrom, freeFrom, contextFrom, build, toneOf, prepOf, spanOf, LAYER_CAP, CONTEXT_CAP, MIN_BLOCK, WINDOW_MS };

package/workspace/lib/facts-async.js

@@ -1,51 +1,160 @@
 'use strict';
-/* facts-async.js — the repo's initiative facts (scripts/signals/facts.js readRepoFacts) WITHOUT blocking the server.
+/* facts-async.js — the repo's initiative facts (scripts/signals/facts.js readRepoFacts) WITHOUT blocking the server, and
+ * read again only when the repository changed (workspace-data-freshness R2, R3).
  *
- * readRepoFacts derives every initiative's stage from git, once per initiative: minutes for ~300 records, and synchronous.
- * Called inside the server process it stops every other request (the page sat "just loading"). This runs it in a child
- * process (scripts/signals/facts-cli.js), keeps one result per root and day for five minutes, and shares one read in
- * flight between callers, so a burst of requests starts one child, not one each. Once a result is older than five minutes it
- * is still returned at once while a new read runs in the background (stale while revalidate), so only the first read waits.
+ * readRepoFacts derives every initiative's stage from git and is synchronous, so it runs in a child process
+ * (scripts/signals/facts-cli.js). One read in flight is shared between callers.
+ *
+ * ONE ENTRY PER REPOSITORY. The entry is not keyed by day: a caller that passes `today` gets the same facts normalized for
+ * that day (normalizeFacts is pure and cheap), so Briefing and Calendar share one read instead of running two.
+ *
+ * REFRESHED ON A CHANGE, NOT ON A CLOCK. The entry carries the repository's signature (lib/repo-watch.js: HEAD, the
+ * porcelain status, and the size and time of each dirty file) and the engine version (a hash of the scripts that derive
+ * the facts). A read whose signature and engine match is served from the entry. A changed signature returns the entry at
+ * once and starts one rebuild (stale while revalidate); only a repository never read before waits. An entry older than
+ * MAX_AGE_MS is rebuilt in the background even when the signature holds, which catches an input the signature cannot see
+ * (an ignored file). A folder that is not a git checkout has no signature and keeps the old rule: a TTL of TTL_MS.
+ *
+ * KEPT ON DISK. configure({ stateDir }) names the runtime state folder; each entry is then written to
+ * <stateDir>/facts-cache/<hash of root>.json and read back after a restart. Never into the repository. Unconfigured (a
+ * suite), nothing is written.
  */
 const { execFile } = require('child_process');
+const crypto = require('crypto');
+const fs = require('fs');
 const path = require('path');
+const repoWatch = require('./repo-watch.js');
 
 const CLI = path.resolve(__dirname, '..', '..', 'scripts', 'signals', 'facts-cli.js');
-const TTL_MS = 5 * 60 * 1000;
-const memo = new Map();       // root|today -> { at, facts }
-const inflight = new Map();   // root|today -> Promise
+const TTL_MS = 5 * 60 * 1000;            // only for a folder with no signature
+const MAX_AGE_MS = 24 * 3600 * 1000;     // an entry this old is rebuilt even when the signature holds
+const SIG_REUSE_MS = 2000;               // a burst of requests asks git once
+const memo = new Map();       // root -> { at, sig, engine, facts, ms }
+const inflight = new Map();   // root -> Promise
+const sigMemo = new Map();    // root -> { at, sig }
+const lastError = new Map();  // root -> { at, error }
+let stateDir = null;
+let engineMemo = null;
+
+const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex');
+
+/** The version of the code that derives the facts: a change to it makes every entry stale. */
+function engineVersion() {
+  if (engineMemo) return engineMemo;
+  const sig = path.resolve(__dirname, '..', '..', 'scripts');
+  const parts = [CLI, path.join(sig, 'signals', 'facts.js'), path.join(sig, 'workflow-state.js')].map((f) => {
+    try { return sha1(fs.readFileSync(f)); } catch { return '-'; }
+  });
+  engineMemo = sha1(parts.join('|')).slice(0, 12);
+  return engineMemo;
+}
+
+function configure(o = {}) { stateDir = o.stateDir || null; }
+const fileOf = (root) => (stateDir ? path.join(stateDir, 'facts-cache', sha1(root).slice(0, 16) + '.json') : null);
+
+function loadDisk(root) {
+  const f = fileOf(root);
+  if (!f) return null;
+  try {
+    const e = JSON.parse(fs.readFileSync(f, 'utf8'));
+    return e && e.root === root && e.facts && typeof e.at === 'number' ? e : null;
+  } catch { return null; }
+}
+function saveDisk(root, entry) {
+  const f = fileOf(root);
+  if (!f) return;
+  try {
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    const tmp = `${f}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ root, ...entry }));
+    fs.renameSync(tmp, f);
+  } catch { /* a cache that cannot be written is only a slower next start */ }
+}
+
+async function currentSig(root, opts, clock) {
+  if (opts.signature) return opts.signature(root);
+  const hit = sigMemo.get(root);
+  if (hit && clock() - hit.at < SIG_REUSE_MS) return hit.sig;
+  let sig = null;
+  try {
+    // a folder with no HEAD is not a checkout: no signature, and the TTL rule decides
+    const head = await new Promise((resolve) => execFile('git', ['rev-parse', 'HEAD'], { cwd: root, timeout: 15000 }, (e, out) => resolve(e ? null : out)));
+    if (head != null) sig = await repoWatch.signature(root, async () => ({ files: [] }));
+  } catch { sig = null; }
+  sigMemo.set(root, { at: clock(), sig });
+  return sig;
+}
+
+function normalize(facts, today) {
+  try { return require('../../scripts/signals/facts.js').normalizeFacts(facts, today || undefined); } catch { return facts; }
+}
 
 function readFactsAsync(root, opts = {}) {
-  const today = opts.today || '';
   const resolved = path.resolve(root || process.cwd());
-  const key = resolved + '|' + today;
   const clock = opts.clock || Date.now;
-  const hit = memo.get(key);
-  const fresh = hit && clock() - hit.at < (opts.ttlMs == null ? TTL_MS : opts.ttlMs);
-  if (fresh) return Promise.resolve(hit.facts);
-
-  const start = () => {
-    if (inflight.has(key)) return inflight.get(key);
-    const run = opts.run || ((r, t) => new Promise((resolve, reject) => {
-      execFile(process.execPath, [CLI, r, t], { maxBuffer: 512 * 1024 * 1024, timeout: 15 * 60 * 1000 }, (err, out) => {
-        if (err) return reject(err);
-        try { resolve(JSON.parse(out)); } catch (e) { reject(e); }
-      });
-    }));
-    const p = Promise.resolve(run(resolved, today)).then((facts) => {
-      memo.set(key, { at: clock(), facts });
-      return facts;
-    }).finally(() => { inflight.delete(key); });
-    inflight.set(key, p);
-    return p;
+  const today = opts.today || '';
+  const out = (facts) => (opts.run ? facts : normalize(facts, today));
+  return (async () => {
+    let hit = memo.get(resolved);
+    if (!hit) { const d = loadDisk(resolved); if (d) { hit = d; memo.set(resolved, d); } }
+    const sig = await currentSig(resolved, opts, clock);
+    const engine = opts.run ? 'test' : engineVersion();
+
+    const start = () => {
+      if (inflight.has(resolved)) return inflight.get(resolved);
+      const run = opts.run || ((r) => new Promise((resolve, reject) => {
+        execFile(process.execPath, [CLI, r], { maxBuffer: 512 * 1024 * 1024, timeout: 15 * 60 * 1000 }, (err, stdout) => {
+          if (err) return reject(err);
+          try { resolve(JSON.parse(stdout)); } catch (e) { reject(e); }
+        });
+      }));
+      const t0 = Date.now();
+      const p = Promise.resolve(run(resolved)).then((facts) => {
+        const entry = { at: clock(), sig, engine, facts, ms: Date.now() - t0 };
+        memo.set(resolved, entry);
+        lastError.delete(resolved);
+        saveDisk(resolved, entry);
+        return facts;
+      }, (e) => { lastError.set(resolved, { at: clock(), error: String((e && e.message) || e).slice(0, 200) }); throw e; })
+        .finally(() => { inflight.delete(resolved); });
+      inflight.set(resolved, p);
+      return p;
+    };
+
+    if (hit) {
+      const age = clock() - hit.at;
+      const fresh = sig != null
+        ? hit.sig === sig && hit.engine === engine && age < MAX_AGE_MS
+        : age < (opts.ttlMs == null ? TTL_MS : opts.ttlMs);
+      if (fresh) return out(hit.facts);
+      if (opts.stale !== false) { start().catch(() => {}); return out(hit.facts); }
+    }
+    return out(await start());
+  })();
+}
+
+/** How old the facts of `root` are, for the freshness surface (R6). Reads nothing but memory and the disk entry. */
+function status(root) {
+  const resolved = path.resolve(root);
+  const hit = memo.get(resolved) || loadDisk(resolved);
+  const err = lastError.get(resolved);
+  return {
+    as_of: hit ? new Date(hit.at).toISOString() : null,
+    building: inflight.has(resolved),
+    took_ms: hit && hit.ms != null ? hit.ms : null,
+    error: err ? err.error : null,
   };
+}
 
-  // Stale while revalidate: an expired result is still the best answer for now. Return it at once and refresh in the
-  // background, so only the very first read of a repository ever waits (opts.stale === false turns this off).
-  if (hit && opts.stale !== false) { start().catch(() => {}); return Promise.resolve(hit.facts); }
-  return start();
+/** Start a rebuild now (a change the watcher saw, or the PM's Refresh). The signature is asked again first. */
+function refresh(root, opts = {}) {
+  const resolved = path.resolve(root);
+  sigMemo.delete(resolved);
+  const hit = memo.get(resolved);
+  if (hit && opts.force) memo.set(resolved, { ...hit, sig: '(forced)' });
+  return readFactsAsync(resolved, opts).catch(() => null);
 }
 
-function resetFactsCache() { memo.clear(); inflight.clear(); }
+function resetFactsCache() { memo.clear(); inflight.clear(); sigMemo.clear(); lastError.clear(); }
 
-module.exports = { readFactsAsync, resetFactsCache, TTL_MS };
+module.exports = { readFactsAsync, resetFactsCache, refresh, status, configure, engineVersion, TTL_MS, MAX_AGE_MS };