create-pmos 0.210.0 → 0.212.0

package/workspace/lib/refresh.js

@@ -0,0 +1,464 @@
+'use strict';
+/* refresh.js — what PMOS refreshes, when, and what each refresh did (initiative data-refresh-settings).
+ *
+ * THE SOURCES. One registry of the 13 places PMOS refreshes data (SOURCES). Each says how it runs (`skill`: a Claude skill this module
+ * schedules; `job`: a PMOS job with its own tick, which this module only gates; `change`: a watcher with no schedule), what it USES (its
+ * inputs, as read in the code: dependencies.md section 3) and the IMPACT line shown when it fails or is off.
+ *
+ * THE SETTINGS. <state>/refresh.json: { sources: { id: { on, s, ws } }, rules, migrated }. `s` is the schedule of a skill source:
+ *   { kind: 'manual' }                         only when the PM presses Refresh
+ *   { kind: 'every', every: '15'..'240', work } every N minutes from midnight; `work` keeps it inside the background working hours
+ *   { kind: 'daily' | 'weekdays', times: ['HH:MM', …] }   one to four times a day (weekdays: Monday to Friday)
+ *   { kind: 'weekly', day: 'Mon'..'Sun', times: ['HH:MM'] }
+ * A job source keeps only `on` here; the day check's minutes live in the proactive settings (dayCheck.every), their one home.
+ *
+ * THE STATE. <state>/refresh-state.json: per source { last_slot, running, run, started_at, trigger, retry_at, retried, waiting_since, pending }.
+ * It is what the tick needs between minutes; the log is the record.
+ *
+ * THE LOG. <state>/refresh-log.jsonl, append-only: { at, source, ws, ev: 'start'|'end'|'skip', run, trigger, result?, took_ms?, got?, error?,
+ * inputs?, note?, copy? }. Every background run writes a start and an end; a slot that does not run writes a skip with the reason. A done run of
+ * a source whose data is overwritten (Jira, work assigned to you) keeps a copy of what it read under <state>/refresh-copies/<source>/<stamp>/.
+ * prune() removes lines and copies older than the keep rule, once a day.
+ *
+ * Everything that decides is pure (lastSlot, nextSlot, decide, rowsOf); the file helpers are at the bottom.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const HHMM = /^([01]\d|2[0-3]):[0-5]\d$/;
+const SKILL_KINDS = Object.freeze(['manual', 'every', 'daily', 'weekdays', 'weekly']);
+const EVERY = Object.freeze(['15', '30', '60', '120', '240']);
+const WAIT_MS = 30 * 60 * 1000;          // a refresh waits at most this long for its inputs
+const LATE_MS = 15 * 60 * 1000;          // a slot older than this when first seen was missed (PMOS was closed)
+const MAX_TIMES = 4;
+
+/* The sources. `fresh` names the lib/freshness.js row whose age and detail this source shares; `copy` names the files a done run keeps. */
+const SOURCES = Object.freeze([
+  { id: 'calendar', label: 'Calendar', group: 'tools', ic: 'cal', run: 'skill', skill: 'calendar-sync', how: 'tool', fresh: 'calendar',
+    what: 'Events from your calendars, for Calendar, the phone day, meeting focus and meeting notes.', uses: [],
+    impact: 'Calendar, the phone day, meeting focus and meeting notes show the last import. The Briefing reads your calendar itself, so it is not affected.',
+    def: { kind: 'daily', times: ['06:30', '12:30'] } },
+  { id: 'jira', label: 'Jira tickets and sprints', group: 'tools', ic: 'org', run: 'skill', skill: 'jira-sync', how: 'tool', fresh: 'jira', copy: 'jira',
+    what: 'The status of every pushed ticket, the active sprints, and each sprint\'s goal and team summary.', uses: [],
+    impact: 'Tickets keep their last status. Sprint summaries stop. The initiative driver cannot see ticket moves or blocked tickets, core documents write the sprint review from old data, and report drafts say Jira was not checked.',
+    def: { kind: 'daily', times: ['06:30'] } },
+  { id: 'mywork', label: 'Work assigned to you', group: 'tools', ic: 'todo', run: 'skill', skill: 'my-work-read', how: 'tool', fresh: 'my-work', copy: 'mywork',
+    what: 'Jira tickets assigned to you, for the Work page and the Briefing.', uses: [],
+    impact: 'The Work page and the Briefing keep the last list of work assigned to you.',
+    def: { kind: 'manual' } },
+  { id: 'tracker', label: 'Tracker files', group: 'tools', ic: 'sheet', run: 'skill', skill: 'tracker-refresh', how: 'code', fresh: 'tracker',
+    what: 'Plan items brought up to date from the tracker files in the workspace.', uses: [],
+    impact: 'The bi-weekly report says the tracker was not refreshed.',
+    def: { kind: 'weekly', day: 'Fri', times: ['15:30'] } },
+  { id: 'brief', label: 'Morning briefing', group: 'pmos', ic: 'sun', run: 'skill', skill: 'morning-brief', how: 'bg',
+    what: 'Your Briefing for the day, ranked by what needs you first.', uses: ['mywork'],
+    impact: 'No new Briefing for the day, and the day check has nothing to update.',
+    def: { kind: 'daily', times: ['06:45'] } },
+  { id: 'daycheck', label: 'Day check', group: 'pmos', ic: 'clock', run: 'job', how: 'bg',
+    what: 'Looks at today\'s plan, moves what is done and flags what slipped. It also runs before and after meetings, on a day with a plan.', uses: ['brief'],
+    impact: 'Today\'s plan is not checked during the day.', def: { kind: 'every', every: '60', work: true }, every: ['30', '60'] },
+  { id: 'scan', label: 'Horizon scan', group: 'pmos', ic: 'search', run: 'job', how: 'bg', setIn: 'Initiatives, Horizon scan',
+    what: 'Reads the web and your repositories for changes that matter to your initiatives.', uses: ['repo'],
+    impact: 'Core documents cite the older scan.' },
+  { id: 'coredocs', label: 'Core documents', group: 'pmos', ic: 'doc', run: 'job', how: 'bg', fixed: 'Every 30 min in working hours, each document at most once a day',
+    what: 'Drafts the portfolio, board and initiative documents that are due, old or missing.', uses: ['repo', 'jira', 'scan'],
+    impact: 'The initiative driver no longer sees documents that are due or old.' },
+  { id: 'driver', label: 'Initiative driver', group: 'pmos', ic: 'bolt', run: 'job', how: 'bg', fixed: 'Every 30 min in working hours, and when an initiative moves',
+    what: 'Checks each driven initiative for its next step and unblocks what it can.', uses: ['repo', 'jira', 'coredocs'],
+    impact: 'Driven initiatives get no unblocks or next steps.' },
+  { id: 'finder', label: 'Report finder', group: 'pmos', ic: 'report', run: 'job', how: 'bg', setIn: 'Connectors, Report finder',
+    what: 'Looks at your calendar, Slack, mail subjects and Drive for reports you write by hand, and proposes them.', uses: [],
+    impact: 'No new report proposals.' },
+  { id: 'signals', label: 'Signals', group: 'pmos', ic: 'bell', run: 'job', how: 'code', fixed: 'Every 10 min, outside quiet hours',
+    what: 'Five checks for things that need you, such as a stalled initiative or a schedule that failed.', uses: ['repo'],
+    impact: 'No new signal cards.' },
+  { id: 'repo', label: 'Repository and initiatives', group: 'change', ic: 'repo', run: 'change', how: 'code', fresh: 'initiatives',
+    what: 'Initiative facts and boards, rebuilt when a file or commit in the workspace changes.', uses: [],
+    impact: 'Boards, the driver, signals, core documents and the scan use the last built board.' },
+  { id: 'sync', label: 'Git sync', group: 'change', ic: 'branch', run: 'change', how: 'code',
+    what: 'Pulls and pushes your records once they have been quiet for 5 minutes.', uses: [],
+    impact: 'Your records are not pulled or pushed, so other computers do not see your changes.' },
+]);
+const BY_ID = new Map(SOURCES.map((s) => [s.id, s]));
+const SKILL_OF = new Map(SOURCES.filter((s) => s.skill).map((s) => [s.skill, s.id]));
+const usedBy = (id) => SOURCES.filter((s) => s.uses.includes(id)).map((s) => s.id);
+
+const RULE_DEFAULTS = Object.freeze({ catchup: true, retry: '15', tell: 'brief', max: '3', keep: '90' });
+const RULE_OPTS = Object.freeze({ retry: ['15', '60', 'no'], tell: ['brief', 'here'], max: ['1', '2', '3', '5'], keep: ['30', '90', '365', 'forever'] });
+
+/* ── schedules ── */
+function cleanTimes(t) {
+  const a = [...new Set((Array.isArray(t) ? t : []).map(String).filter((x) => HHMM.test(x)))].sort();
+  return a.slice(0, MAX_TIMES);
+}
+/** Check a schedule from the PM. → { ok, s } | { ok: false, error } */
+function normalize(src, s) {
+  if (!src || src.run !== 'skill') {
+    if (src && src.id === 'daycheck' && s && s.kind === 'every' && src.every.includes(String(s.every))) return { ok: true, s: { kind: 'every', every: String(s.every), work: true } };
+    return { ok: false, error: src && src.id === 'daycheck' ? 'The day check runs every 30 or 60 minutes.' : 'This source has no schedule to set here.' };
+  }
+  if (!s || typeof s !== 'object' || !SKILL_KINDS.includes(s.kind)) return { ok: false, error: 'kind must be one of ' + SKILL_KINDS.join(', ') };
+  if (s.kind === 'manual') return { ok: true, s: { kind: 'manual' } };
+  if (s.kind === 'every') {
+    if (!EVERY.includes(String(s.every))) return { ok: false, error: 'every must be one of ' + EVERY.join(', ') + ' (minutes)' };
+    return { ok: true, s: { kind: 'every', every: String(s.every), work: !!s.work } };
+  }
+  const times = cleanTimes(s.times);
+  if (!times.length) return { ok: false, error: 'times must hold one to four HH:MM times (24-hour)' };
+  if (Array.isArray(s.times) && s.times.some((x) => !HHMM.test(String(x)))) return { ok: false, error: 'each time must be HH:MM (24-hour)' };
+  if (s.kind === 'weekly') {
+    if (!DAYS.includes(s.day)) return { ok: false, error: 'day must be one of Mon, Tue, Wed, Thu, Fri, Sat, Sun' };
+    return { ok: true, s: { kind: 'weekly', day: s.day, times: times.slice(0, 1) } };
+  }
+  return { ok: true, s: { kind: s.kind, times } };
+}
+const minutesOf = (hhmm) => { const [h, m] = String(hhmm).split(':').map(Number); return h * 60 + m; };
+const at = (dayMs, hhmm) => { const d = new Date(dayMs); const m = minutesOf(hhmm); d.setHours(Math.floor(m / 60), m % 60, 0, 0); return d.getTime(); };
+const dayStart = (ms) => { const d = new Date(ms); d.setHours(0, 0, 0, 0); return d.getTime(); };
+const addDays = (ms, n) => { const d = new Date(ms); d.setDate(d.getDate() + n); return d.getTime(); };
+const dayOk = (s, ms) => { const d = new Date(ms).getDay(); return s.kind === 'weekdays' ? d >= 1 && d <= 5 : s.kind === 'weekly' ? DAYS[d] === s.day : true; };
+
+/** The slots of one day, in ms, ascending. `win` is { start, end } HH:MM, the background working hours. */
+function slotsOfDay(s, dayMs, win) {
+  if (!s || s.kind === 'manual') return [];
+  if (s.kind === 'every') {
+    const step = Number(s.every) || 60; const out = [];
+    const lo = s.work && win ? minutesOf(win.start) : 0; const hi = s.work && win ? minutesOf(win.end) : 24 * 60;
+    for (let m = 0; m < 24 * 60; m += step) if (m >= lo && m < hi) out.push(dayStart(dayMs) + m * 60000);
+    // A clock change can shift a day; dayStart + minutes is near enough for minute slots.
+    return out;
+  }
+  if (!dayOk(s, dayMs)) return [];
+  return cleanTimes(s.times).map((t) => at(dayMs, t));
+}
+/** The most recent slot at or before `now`, in ms, or null (none in the last 8 days). */
+function lastSlot(s, now, win) {
+  for (let k = 0; k < 8; k++) {
+    const day = addDays(dayStart(now), -k);
+    const hits = slotsOfDay(s, day, win).filter((x) => x <= now);
+    if (hits.length) return hits[hits.length - 1];
+  }
+  return null;
+}
+/** The next slot strictly after `now`, in ms, or null. */
+function nextSlot(s, now, win) {
+  for (let k = 0; k < 9; k++) {
+    const day = addDays(dayStart(now), k);
+    const hit = slotsOfDay(s, day, win).find((x) => x > now);
+    if (hit != null) return hit;
+  }
+  return null;
+}
+const inWindow = (now, win) => { if (!win) return true; const d = new Date(now); const m = d.getHours() * 60 + d.getMinutes(); return m >= minutesOf(win.start) && m < minutesOf(win.end); };
+function inQuiet(now, quiet) {
+  if (!quiet || !quiet.start || !quiet.end) return false;
+  const d = new Date(now); const m = d.getHours() * 60 + d.getMinutes();
+  const a = minutesOf(quiet.start); const b = minutesOf(quiet.end);
+  return a < b ? m >= a && m < b : m >= a || m < b;
+}
+
+/* ── settings ── */
+/** The settings with every default filled in. A missing or bad entry falls back to the source's default, off. */
+function withDefaults(raw) {
+  const r = raw && typeof raw === 'object' ? raw : {};
+  const sources = {};
+  for (const src of SOURCES) {
+    const x = (r.sources && r.sources[src.id]) || {};
+    const on = typeof x.on === 'boolean' ? x.on : src.run !== 'skill';   // a job or watcher is on unless the PM turned it off; a skill source starts off
+    const n = src.run === 'skill' && x.s ? normalize(src, x.s) : null;
+    sources[src.id] = { on, s: n && n.ok ? n.s : (src.def ? { ...src.def, ...(src.def.times ? { times: src.def.times.slice() } : {}) } : null), ws: typeof x.ws === 'string' ? x.ws : null };
+  }
+  const rules = { ...RULE_DEFAULTS };
+  const rr = r.rules || {};
+  if (typeof rr.catchup === 'boolean') rules.catchup = rr.catchup;
+  for (const k of Object.keys(RULE_OPTS)) if (RULE_OPTS[k].includes(String(rr[k]))) rules[k] = String(rr[k]);
+  return { sources, rules, migrated: !!r.migrated };
+}
+/** Check a rules patch. → { ok, patch } | { ok: false, error } */
+function normalizeRules(p) {
+  const out = {};
+  if (!p || typeof p !== 'object') return { ok: false, error: 'rules must be an object' };
+  for (const [k, v] of Object.entries(p)) {
+    if (k === 'catchup') { if (typeof v !== 'boolean') return { ok: false, error: 'catchup must be true or false' }; out.catchup = v; continue; }
+    if (!RULE_OPTS[k]) return { ok: false, error: `unknown rule '${k}'` };
+    if (!RULE_OPTS[k].includes(String(v))) return { ok: false, error: `${k} must be one of ${RULE_OPTS[k].join(', ')}` };
+    out[k] = String(v);
+  }
+  return { ok: true, patch: out };
+}
+
+/** Adopt the schedules.json entries of the managed skills (R3). → { settings, schedules, adopted: [id] }. Pure: the caller writes both. */
+function migrate(settings, schedules, { homeWs } = {}) {
+  const next = JSON.parse(JSON.stringify(settings));
+  const list = (schedules || []).map((x) => ({ ...x }));
+  const adopted = [];
+  if (next.migrated) return { settings: next, schedules: list, adopted };
+  for (const src of SOURCES.filter((x) => x.run === 'skill')) {
+    const mine = list.filter((x) => x.skill === src.skill && x.enabled !== false && !x.endedReason);
+    if (!mine.length) continue;
+    const ws = mine[0].ws || homeWs || null;
+    const same = mine.filter((x) => (x.ws || null) === ws);
+    let s = null;
+    if (same.every((x) => x.cadence === 'daily')) s = { kind: 'daily', times: cleanTimes(same.map((x) => x.time)) };
+    else if (same[0].cadence === 'weekly' || same[0].cadence === 'bi-weekly') s = { kind: 'weekly', day: same[0].day || 'Mon', times: cleanTimes([same[0].time]) };
+    else s = { kind: 'daily', times: cleanTimes(same.map((x) => x.time)) };
+    const n = normalize(src, s);
+    next.sources[src.id] = { on: true, s: n.ok ? n.s : src.def, ws };
+    for (const x of same) { x.enabled = false; x.endedReason = 'Moved to Settings › Data refresh'; x.nextRun = null; }
+    adopted.push(src.id);
+  }
+  next.migrated = true;
+  return { settings: next, schedules: list, adopted };
+}
+
+/* ── the decision ── */
+/**
+ * What the tick should do for skill source `src` now. → { act: 'start'|'skip'|'wait'|'none', trigger?, slot?, why?, note? }
+ *   st      the source's state record (refresh-state.json)
+ *   ctx     { now, settings, rules, win, quiet, runningCount, inputState(id) → 'running'|'due'|'waiting'|'ok'|'off', first }
+ * `first` is true on the first tick after PMOS started: a slot older than LATE_MS then is a missed slot, which catch-up runs or skips.
+ */
+function decide(src, st, ctx) {
+  const set = ctx.settings.sources[src.id];
+  const now = ctx.now; const rules = ctx.rules;
+  st = st || {};
+  if (st.running) return { act: 'none', why: 'running' };
+  if (!set || !set.on) {
+    if (st.pending) return gateInputs(src, st, ctx, { trigger: st.pending.trigger || 'pressed', pressed: true });
+    return { act: 'none', why: 'off' };
+  }
+  // A pressed refresh that waits for its inputs.
+  if (st.pending) return gateInputs(src, st, ctx, { trigger: st.pending.trigger || 'pressed', pressed: true });
+  // A retry of a failed run.
+  if (st.retry_at && now >= st.retry_at) return gateInputs(src, st, ctx, { trigger: 'retry', slot: st.last_slot || null });
+  const slot = lastSlot(set.s, now, ctx.win);
+  if (slot == null) return { act: 'none', why: 'no slot' };
+  if (st.last_slot != null && st.last_slot >= slot) return { act: 'none', why: 'done' };
+  // A slot from before the last start (a run pressed after it) is done too.
+  if (st.started_at && st.started_at >= slot && !st.waiting_since) return { act: 'skip', slot, why: 'already refreshed after this slot', quiet: true };
+  const late = now - slot > LATE_MS;
+  if (late && !st.waiting_since) {
+    if (!rules.catchup) return { act: 'skip', slot, why: 'PMOS was closed at ' + hm(slot) + ', and catch-up is off' };
+    if (inQuiet(now, ctx.quiet)) return { act: 'skip', slot, why: 'missed at ' + hm(slot) + ', and it is quiet hours now' };
+    return gateInputs(src, st, ctx, { trigger: 'catch-up', slot });
+  }
+  if (inQuiet(now, ctx.quiet) && !st.waiting_since) return { act: 'skip', slot, why: 'quiet hours' };
+  return gateInputs(src, st, ctx, { trigger: 'schedule', slot });
+}
+function gateInputs(src, st, ctx, { trigger, slot, pressed }) {
+  const busy = src.uses.filter((id) => ['running', 'due', 'waiting'].includes(ctx.inputState(id)));
+  if (busy.length) {
+    const since = st.waiting_since || ctx.now;
+    if (ctx.now - since < WAIT_MS) return { act: 'wait', trigger, slot, waiting: busy, since };
+    return startOrHold(ctx, { act: 'start', trigger, slot, pressed, note: 'Waited 30 min for ' + busy.map(labelOf).join(', ') + ', then ran without it' });
+  }
+  return startOrHold(ctx, { act: 'start', trigger, slot, pressed });
+}
+function startOrHold(ctx, d) {
+  if (!d.pressed && ctx.runningCount >= Number(ctx.rules.max || 3)) return { ...d, act: 'wait', why: 'the run limit', waiting: [] };
+  return d;
+}
+const labelOf = (id) => (BY_ID.get(id) || { label: id }).label;
+const hm = (ms) => { const d = new Date(ms); return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`; };
+
+/** May job `id` run its tick now? → { ok } | { ok: false, why }. Off, or an input running or waiting (up to WAIT_MS since `waitingSince`). */
+function jobGate(id, ctx) {
+  const set = ctx.settings.sources[id];
+  if (set && set.on === false) return { ok: false, why: 'off' };
+  const src = BY_ID.get(id);
+  const busy = (src ? src.uses : []).filter((x) => ['running', 'waiting'].includes(ctx.inputState(x)));
+  if (busy.length && (!ctx.waitingSince || ctx.now - ctx.waitingSince < WAIT_MS)) return { ok: false, why: 'waiting', waiting: busy };
+  return { ok: true };
+}
+
+/** The source a session belongs to, from its origin, or null. `skillOfSchedule(id)` maps a schedules.json id to its skill. */
+function sourceOfOrigin(origin, { skillOfSchedule } = {}) {
+  const o = String(origin || '');
+  let m = /^refresh:([a-z]+)$/.exec(o); if (m && BY_ID.has(m[1])) return m[1];
+  if (o === 'my-work-read') return 'mywork';
+  if (o === 'day-check') return 'daycheck';
+  if (/^scan-(web|repo):/.test(o)) return 'scan';
+  if (/^core-doc:/.test(o)) return 'coredocs';
+  if (/^drive:/.test(o)) return 'driver';
+  if (/^report-find:/.test(o)) return 'finder';
+  m = /^schedule:(.+)$/.exec(o);
+  if (m && skillOfSchedule) { const sk = skillOfSchedule(m[1]); return sk && SKILL_OF.has(sk) ? SKILL_OF.get(sk) : null; }
+  return null;
+}
+
+/* ── rows for the page ── */
+/**
+ * One row per source for GET /api/refresh. → [row]
+ *   opts { now, settings, state, log (folded: lastRun(id), runs(id, n)), fresh (Map id → freshness row), win, quiet, jobSchedule(id) → text|null, ws }
+ */
+function rowsOf(opts) {
+  const { now, settings, state, log, fresh, win } = opts;
+  const rows = SOURCES.map((src) => {
+    const set = settings.sources[src.id]; const st = state[src.id] || {};
+    const last = log.lastRun(src.id);
+    const fr = src.fresh && fresh ? fresh.get(src.fresh) : null;
+    const lastAt = (last && last.end_at) || (fr && fr.as_of) || null;
+    let stateName;
+    // A pressed refresh runs even when the source is off, so running and waiting come before off.
+    if (st.running || (last && !last.end_at && last.start_at && now - Date.parse(last.start_at) < 6 * 3600000)) stateName = 'running';
+    else if (st.waiting_since || st.pending) stateName = 'waiting';
+    else if (!set.on) stateName = 'off';
+    else if (last && last.result === 'failed') stateName = 'failed';
+    else if (fr && fr.state === 'failed') stateName = 'failed';
+    else if (fr && fr.state === 'stale') stateName = 'old';
+    else if (!lastAt) stateName = 'never';
+    else stateName = staleOf(src, set, lastAt, now, win) ? 'old' : 'recent';
+    const next = set.on && src.run === 'skill' ? nextSlot(set.s, now, win) : null;
+    return {
+      id: src.id, label: src.label, group: src.group, ic: src.ic, run: src.run, how: src.how, what: src.what, uses: src.uses.slice(), used_by: usedBy(src.id), impact: src.impact,
+      on: set.on, schedule: src.run === 'skill' || src.id === 'daycheck' ? set.s : null, default: src.def || null, ws: set.ws,
+      kinds: src.run === 'skill' ? SKILL_KINDS.slice() : src.id === 'daycheck' ? ['every'] : [], every: src.run === 'skill' ? EVERY.slice() : src.every ? src.every.slice() : [],
+      schedule_text: src.run === 'skill' || src.id === 'daycheck' ? textOf(set.s) : src.run === 'change' ? 'On every change' : (opts.jobSchedule && opts.jobSchedule(src.id)) || src.fixed || '',
+      set_in: src.setIn || null,
+      state: stateName,
+      last: last ? { at: lastAt, start_at: last.start_at, result: last.result || (last.end_at ? 'done' : null), took_ms: last.took_ms != null ? last.took_ms : null,
+        got: last.got || (fr && fr.detail) || null, error: last.error || null, trigger: last.trigger || null, note: last.note || null } : (lastAt ? { at: lastAt, got: fr && fr.detail || null } : null),
+      next_at: next ? new Date(next).toISOString() : null,
+      waiting_for: st.waiting_for || [],
+      runs: log.runs(src.id, 5),
+    };
+  });
+  // What each source was built on: an input that is failed, old or off now (R5, R9).
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  for (const r of rows) {
+    r.inputs = r.uses.map((id) => { const x = byId.get(id); return { id, label: x.label, state: x.state, at: x.last ? x.last.at : null }; });
+    r.built_on = r.inputs.filter((x) => ['failed', 'old', 'off', 'never'].includes(x.state));
+  }
+  return rows;
+}
+/** Old: no refresh since the slot before the last one (a skill source), or older than a day (a job). */
+function staleOf(src, set, lastAt, now, win) {
+  const t = Date.parse(lastAt); if (!Number.isFinite(t)) return false;
+  if (src.run === 'skill') {
+    const s = set.s; if (!s || s.kind === 'manual') return now - t > 26 * 3600000;
+    const l1 = lastSlot(s, now, win); if (l1 == null) return false;
+    const l0 = lastSlot(s, l1 - 1, win);
+    return l0 != null && t < l0;
+  }
+  if (src.run === 'change') return false;
+  return now - t > (src.id === 'finder' ? 8 * 86400000 : src.id === 'scan' ? 4 * 86400000 : 26 * 3600000);
+}
+const DAYN = { Mon: 'Monday', Tue: 'Tuesday', Wed: 'Wednesday', Thu: 'Thursday', Fri: 'Friday', Sat: 'Saturday', Sun: 'Sunday' };
+const everyText = (v) => ({ 15: '15 min', 30: '30 min', 60: 'hour', 120: '2 hours', 240: '4 hours' })[v] || v + ' min';
+/** The plain sentence for a schedule. */
+function textOf(s) {
+  if (!s) return '';
+  if (s.kind === 'manual') return 'Only when you press Refresh';
+  if (s.kind === 'every') return 'Every ' + everyText(s.every) + (s.work ? ', working hours only' : '');
+  const t = (s.times || []).join(' and ');
+  if (s.kind === 'daily') return 'Daily at ' + t;
+  if (s.kind === 'weekdays') return 'Working days at ' + t;
+  if (s.kind === 'weekly') return 'Every ' + (DAYN[s.day] || s.day) + ' at ' + t;
+  return '';
+}
+
+/* ── files ── */
+const files = (stateDir) => ({
+  settings: path.join(stateDir, 'refresh.json'),
+  state: path.join(stateDir, 'refresh-state.json'),
+  log: path.join(stateDir, 'refresh-log.jsonl'),
+  copies: path.join(stateDir, 'refresh-copies'),
+});
+function readJson(f, fallback) { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return fallback; } }
+function writeJson(f, v) {
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  const tmp = `${f}.${process.pid}.tmp`; fs.writeFileSync(tmp, JSON.stringify(v, null, 1) + '\n'); fs.renameSync(tmp, f);
+}
+const readSettings = (dir) => withDefaults(readJson(files(dir).settings, null));
+const writeSettings = (dir, s) => writeJson(files(dir).settings, { sources: s.sources, rules: s.rules, migrated: !!s.migrated });
+const readState = (dir) => { const s = readJson(files(dir).state, {}); return s && typeof s === 'object' && !Array.isArray(s) ? s : {}; };
+const writeState = (dir, s) => writeJson(files(dir).state, s);
+
+let runSeq = 0;
+const newRun = (source, now = Date.now()) => `${source}-${now.toString(36)}-${(runSeq++ % 1296).toString(36)}`;
+const clip = (s, n) => (s == null ? null : String(s).replace(/\s+/g, ' ').trim().slice(0, n) || null);
+/** Append one log line. Bad source ids are refused. → the line, or null */
+function append(dir, line, now = Date.now()) {
+  if (!line || !BY_ID.has(line.source) || !['start', 'end', 'skip'].includes(line.ev)) return null;
+  const rec = { at: new Date(now).toISOString(), ...line };
+  for (const k of ['got', 'error', 'note']) if (rec[k] != null) rec[k] = clip(rec[k], k === 'error' ? 400 : 200);
+  try { fs.mkdirSync(dir, { recursive: true }); fs.appendFileSync(files(dir).log, JSON.stringify(rec) + '\n'); } catch { return null; }
+  return rec;
+}
+let cache = { f: null, mtime: 0, size: 0, lines: [] };
+function readLog(dir) {
+  const f = files(dir).log;
+  let st; try { st = fs.statSync(f); } catch { return []; }
+  if (cache.f === f && cache.mtime === st.mtimeMs && cache.size === st.size) return cache.lines;
+  const lines = [];
+  for (const l of fs.readFileSync(f, 'utf8').split('\n')) { if (!l.trim()) continue; try { lines.push(JSON.parse(l)); } catch { /* a torn line is skipped */ } }
+  cache = { f, mtime: st.mtimeMs, size: st.size, lines };
+  return lines;
+}
+/** Fold the log into runs: { runs: [run], lastRun(id), runs(id, n) }. A run is { run, source, ws, trigger, start_at, end_at, result, took_ms, got, error, note, inputs, copy }. */
+function foldLog(lines) {
+  const byRun = new Map(); const order = [];
+  for (const l of lines) {
+    if (l.ev === 'skip') { const r = { run: l.run || 'skip-' + l.at, source: l.source, ws: l.ws || null, trigger: l.trigger || 'schedule', start_at: l.at, end_at: l.at, result: 'skipped', note: l.note || null, error: null }; byRun.set(r.run, r); order.push(r.run); continue; }
+    let r = byRun.get(l.run);
+    if (!r) { r = { run: l.run, source: l.source, ws: l.ws || null, trigger: l.trigger || null, start_at: null, end_at: null, result: null }; byRun.set(l.run, r); order.push(l.run); }
+    if (l.ev === 'start') { r.start_at = l.at; r.trigger = l.trigger || r.trigger; r.inputs = l.inputs || null; r.note = l.note || r.note || null; r.session = l.session || null; }
+    if (l.ev === 'end') { r.end_at = l.at; r.result = l.result || 'done'; r.took_ms = l.took_ms != null ? l.took_ms : (r.start_at ? Date.parse(l.at) - Date.parse(r.start_at) : null); r.got = l.got || null; r.error = l.error || null; if (l.copy) r.copy = l.copy; if (l.note) r.note = l.note; }
+  }
+  const runs = order.map((id) => byRun.get(id));
+  const real = (r) => r.result !== 'skipped';
+  return {
+    all: runs,
+    lastRun: (id) => { for (let i = runs.length - 1; i >= 0; i--) if (runs[i].source === id && real(runs[i])) return runs[i]; return null; },
+    runs: (id, n) => runs.filter((r) => r.source === id).slice(-n).reverse(),
+  };
+}
+/** Keep a copy of what a done run read. `paths` are files or folders. → the copy folder relative to the state dir, or null */
+function keepCopy(dir, source, paths, now = Date.now()) {
+  const stamp = new Date(now).toISOString().replace(/[:.]/g, '-');
+  const dest = path.join(files(dir).copies, source, stamp);
+  let n = 0;
+  for (const p of paths || []) {
+    try {
+      const st = fs.statSync(p);
+      fs.mkdirSync(dest, { recursive: true });
+      if (st.isDirectory()) { for (const f of fs.readdirSync(p)) { const fp = path.join(p, f); if (fs.statSync(fp).isFile()) { fs.copyFileSync(fp, path.join(dest, f)); n++; } } }
+      else { fs.copyFileSync(p, path.join(dest, path.basename(p))); n++; }
+    } catch { /* a missing file is not copied */ }
+  }
+  return n ? path.relative(dir, dest).split(path.sep).join('/') : null;
+}
+/** Remove log lines and copies older than `keep` days ('forever' keeps all). → { lines, copies } removed */
+function prune(dir, keep, now = Date.now()) {
+  const out = { lines: 0, copies: 0 };
+  if (!keep || keep === 'forever') return out;
+  const cut = now - Number(keep) * 86400000;
+  const f = files(dir).log;
+  try {
+    const all = fs.readFileSync(f, 'utf8').split('\n').filter((l) => l.trim());
+    const kept = all.filter((l) => { try { return Date.parse(JSON.parse(l).at) >= cut; } catch { return false; } });
+    if (kept.length !== all.length) { const tmp = `${f}.${process.pid}.tmp`; fs.writeFileSync(tmp, kept.join('\n') + (kept.length ? '\n' : '')); fs.renameSync(tmp, f); out.lines = all.length - kept.length; }
+  } catch { /* no log yet */ }
+  try {
+    for (const src of fs.readdirSync(files(dir).copies)) {
+      const sd = path.join(files(dir).copies, src);
+      for (const c of fs.readdirSync(sd)) { try { if (fs.statSync(path.join(sd, c)).mtimeMs < cut) { fs.rmSync(path.join(sd, c), { recursive: true, force: true }); out.copies++; } } catch { /* gone */ } }
+    }
+  } catch { /* no copies yet */ }
+  return out;
+}
+/** The log as CSV, newest first. */
+function toCsv(runs) {
+  const q = (v) => { const s = v == null ? '' : String(v); return /[",\n]/.test(s) ? '"' + s.replace(/"/g, '""') + '"' : s; };
+  const head = ['source', 'run', 'trigger', 'started', 'ended', 'result', 'took_seconds', 'got', 'error', 'note', 'inputs', 'copy'];
+  const rows = runs.slice().reverse().map((r) => [r.source, r.run, r.trigger, r.start_at, r.end_at, r.result, r.took_ms != null ? Math.round(r.took_ms / 1000) : '', r.got, r.error, r.note,
+    (r.inputs || []).map((i) => `${i.id}:${i.state}${i.at ? '@' + i.at : ''}`).join(' '), r.copy]);
+  return [head, ...rows].map((r) => r.map(q).join(',')).join('\n') + '\n';
+}
+
+module.exports = {
+  SOURCES, BY_ID, SKILL_OF, SKILL_KINDS, EVERY, WAIT_MS, LATE_MS, RULE_DEFAULTS, RULE_OPTS,
+  usedBy, normalize, normalizeRules, withDefaults, migrate, lastSlot, nextSlot, slotsOfDay, inWindow, inQuiet, decide, jobGate, sourceOfOrigin, rowsOf, textOf,
+  files, readSettings, writeSettings, readState, writeState, newRun, append, readLog, foldLog, keepCopy, prune, toCsv,
+};

package/workspace/lib/report-finder.js

@@ -150,7 +150,28 @@ function create(deps) {
     return summary;
   }
 
-  return { tick, active: () => [...active.keys()] };
+  /** Refresh now (data-refresh-settings R8): start the weekly run at once for the lead workspace, whatever the day. → { ok, error? } */
+  function runNow({ now = Date.now(), env } = {}) {
+    if (off(env || deps.env)) return { ok: false, error: 'The report finder is switched off on this computer (PMOS_REPORT_FIND=off).' };
+    if (deps.headlessOff()) return { ok: false, error: 'The report finder runs only as a background run, and background runs are off.' };
+    if (active.size) return { ok: false, error: 'The report finder is already running.' };
+    const home = deps.homeId ? deps.homeId() : null;
+    for (const w of deps.workspaces()) {
+      let lead = false;
+      try { lead = !!deps.isLead(w) && (!home || w.id === home); } catch { lead = false; }
+      if (!lead) continue;
+      let file = null;
+      try { file = RS.ledgerFile(w.root); } catch { file = null; }
+      if (!file) continue;
+      const state = RS.fold(RS.readLines(file));
+      if (!sourcesOn(state).length) return { ok: false, error: 'Turn on at least one place to look first, in Connectors, Report finder.' };
+      start(w, file, state, now);
+      return { ok: true };
+    }
+    return { ok: false, error: 'No repository holds the reports yet.' };
+  }
+
+  return { tick, runNow, active: () => [...active.keys()] };
 }
 
 module.exports = { create, off, weekStart, dueNow, nextRun, findPrompt, sourcesOn, SLOT };

package/workspace/lib/route-modules.js

@@ -74,6 +74,7 @@ const MODULES = Object.freeze([
   'routes-report-setups', // report-workspace: recurring reports, the Ask box, the finder, the report documents and their export (report-setups.jsonl)
   'routes-core-docs',     // core-documents: the core documents of each level, Draft it (a core-doc run), Issue it and Drop (core-docs.jsonl)
   'routes-report-design', // report-design-studio: the design studio (describe, samples, turns, versions, This is it), cycle renders and decisions, speaker notes and pins
+  'routes-refresh',       // data-refresh-settings: Settings › Data refresh: what refreshes, when, the refresh log, Refresh now
 ]);
 const PM_DIR = path.join(__dirname, '..', 'public', 'pm');
 const MODULE_NAME = /^[a-z0-9][a-z0-9-]*\.js$/;

package/workspace/lib/routes-calendar-views.js

@@ -4,6 +4,7 @@
  *   → { ok, view, range, cells, unit, gantt, strategy, events_source, today,
  *       layers, layers_total, layers_note, free, context, context_total,      (lib/calendar-layers.js)
  *       link_boards }                                                         every board a meeting can be linked to: [{ ws, id, name }]
+ *   &only=gantt → { ok, view, range, gantt, no_plan, strategy, today }      the rows with a plan date or a Jira read, and how many have neither
  *   POST /api/calendar-links → { ok, link }                                   what a meeting is about (lib/calendar-links.js, below)
  *       tidy, tidy_total, tidy_note }                                          (lib/calendar-tidy.js: suggestions in words, no write)
  *
@@ -39,7 +40,7 @@ function handle(query, deps = {}) {
     const inis = facts.inis || [];
     const range = model.rangeFor(view, date);
     let events = []; let source = 'none';
-    if (typeof deps.readEvents === 'function') { events = deps.readEvents(range) || []; source = 'calendar-memory'; }
+    if (typeof deps.readEvents === 'function' && !(query && query.only === 'gantt')) { events = deps.readEvents(range) || []; source = 'calendar-memory'; }
     const krs = typeof deps.readKrs === 'function' ? deps.readKrs() : [];
     const b = model.bucketEvents(events, view, date);
     const nowDay = deps.today || today();
@@ -50,6 +51,12 @@ function handle(query, deps = {}) {
       if (jira && typeof jira.get === 'function') for (const g of gantt) { const p = jira.get(g.id); if (p) g.jira = p; }
     }
     const strategy = view === 'quarter' || view === 'year' ? model.strategyLens(inis, krs, nowDay) : null;
+    // only=gantt: for the Briefing's Portfolio pulse (c3-plan.js readQuarter). No events, layers or tidy, and only the rows a reader can
+    // draw: a plan date or a Jira read. The rest are counted in no_plan (a large repository has hundreds of them).
+    if (query && query.only === 'gantt') {
+      const rows = gantt.filter((g) => g.status !== 'no plan' || g.jira);
+      return { status: 200, body: { ok: true, view, range, gantt: rows, no_plan: gantt.length - rows.length, strategy, 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
@@ -228,7 +235,8 @@ module.exports = {
     let facts;
     try { facts = await require('./facts-async.js').readFactsAsync(root); }
     catch (e) { ctx.json(res, { ok: false, error: 'the calendar could not read the repository: ' + (e && e.message ? e.message : String(e)) }, 500); return true; }
-    const out = handle({ view: url.searchParams.get('view') || undefined, date: url.searchParams.get('date') || undefined }, {
+    const only = url.searchParams.get('only') || undefined;
+    const out = handle({ view: url.searchParams.get('view') || undefined, date: url.searchParams.get('date') || undefined, only }, {
       readFacts: () => facts,
       readEvents: () => require('./calendar-events.js').readAll(ctx.runtimeDir),
       readLinks: () => require('./calendar-links.js').read(ctx.runtimeDir),

package/workspace/lib/routes-pm-items.js

@@ -7,6 +7,7 @@
  *                                              review, review_days: 7        open items untouched 7 days, most stale first
  *                                              focus: { suggestions, accepted, dismissed }   at most 3 suggestions: { key, title, why, item_ids, job }; dismissed = the keys marked not today
  *                                              counts: { inbox, today, upcoming, waiting, someday, review } }
+ *   GET  /api/pm-items?counts=1            → { ok, today, counts }   the counts alone (the console's Work tab badge)
  *   POST /api/pm-items/add    { line }     → { ok, item }            one line: the parser (lib/pm-items.js) reads the parts
  *   POST /api/pm-items/edit   { id, fields }→ { ok, item }            fields: title, due, priority, waiting_on, job,
  *                                              defer, flagged, resolves, kind, person, evidence, outcome
@@ -343,6 +344,7 @@ module.exports = {
     if (p === '/api/pm-items' && req.method === 'GET') {
       const c = prepare(ctx);
       const v = view(c.itemLines, c.jobLines, c.now, c.stepLines, c.focusLines, proofSources(ctx, c.itemLines), await assignedAsync(ctx, c.now));
+      if (url.searchParams.get('counts') === '1') { ctx.json(res, { ok: v.ok, today: v.today, counts: v.counts }); return true; }
       v.resolves_titles = resolvesTitles(v.items, ctx, url);
       // an item the PM added: the agent can draft a first version of it (c3-work-agent amendment 11)
       const runs = assigned.recentRuns(ctx.readDayRun, c.now.getTime());