create-pmos 0.131.0 → 0.132.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.131.0",
+  "version": "0.132.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@1d6493f
+kernel-source: pmos@b177828
 assembled: 2026-10-11
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-11T03:54:27Z"}
+generated: {by: process:create-pmos, at: "2026-10-11T04:03:34Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-11T03:54:27Z"}
+generated: {by: process:create-pmos, at: "2026-10-11T04:03:34Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-11T03:54:27Z"}
+generated: {by: process:create-pmos, at: "2026-10-11T04:03:34Z"}
 status: stable
 ---
 

package/workspace/guide/data-freshness.md

@@ -0,0 +1,40 @@
+---
+type: Guide
+title: "Data freshness: how the workspace keeps up to date, and how old each source is"
+timestamp: 2026-10-11
+---
+
+# Data freshness
+
+The workspace reads your repositories, and your agents read Jira, your calendar and My work for it. This page says when each one is read again and where you see how old it is.
+
+## Your repositories
+
+The workspace checks each registered repository every 10 seconds for a change: a commit, a checkout, a pull, or a file saved by you or an agent. The check is two read-only git commands. When something changed and then stays the same for 3 seconds, the workspace reads the repository again. It reads nothing when nothing changed.
+
+- **Initiatives** (Briefing, Calendar and the reports) are read in a separate process, so the workspace keeps answering while it reads. While a read runs, the pages show the last result. The result is kept on this machine, so after a restart the pages open at once with the last result and a new read starts only if the repository changed.
+- **Board and My work** are folded in a separate thread for the same reason.
+
+To stop the checks for one repository, press **Stop watching this repository** in Settings › Data freshness. The pages then show what was read last, and **Refresh** reads it again. Press **Watch this repository for changes** to start the checks again.
+
+## Jira, calendar, My work and tracker items
+
+The workspace holds no password or token, and it never calls these services. An agent session reads each one with your own connection, on a schedule or when you press **Refresh**:
+
+| Source | Skill | Default schedule | Shown as old after |
+|---|---|---|---|
+| Calendar | calendar-sync | 06:30 and 12:30 every day (set `calendar`) | 8 hours |
+| Jira status | jira-sync | 06:30 every day (set `jira`) | 26 hours |
+| My work | my-work-read | when you press Read again | 26 hours |
+| Tracker items | tracker-refresh | Friday 15:30 (set `tracker`) | 8 days |
+
+The calendar-sync skill reads today and the next 14 days, read-only, and saves the events with this command:
+
+- `pmos calendar import --from <file|-> --sensitivity <label>` saves the events the agent read. The label is `public`, `internal`, `confidential` or `private`. `--dry-run` checks the file and saves nothing.
+- `pmos calendar status` says how many events are saved and when they were read.
+
+The events are kept in your own runtime folder on this machine, never in a repository.
+
+## Where you see it
+
+Each page shows a short **as of** line for the sources it reads. The line turns amber when a source is older than its limit, and says **never read** when nothing was read yet. Settings › Data freshness shows every source in one table: when it was read, its state, its schedule, and **Refresh**.

package/workspace/guide/index.md

@@ -43,6 +43,7 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 - [Start the workspace without a terminal](launcher.md): the PMOS app, the login item and `pmos launcher`.
 - [Jira tickets](jira.md): Jira tickets drafted from the PRD, pushed when you select them, and their status.
 - [My work](my-work.md): the work assigned to you, its order, the brief to an agent, and `pmos my-work`.
+- [Data freshness](data-freshness.md): when each source is read again, how old it is, and `pmos calendar`.
 - [People](people.md): the people you work with in a repository, how they get there, and `pmos people`.
 - [Docs](docs.md): whether each linked document is the same as, ahead of or behind its Google Docs and Confluence copy.
 - [Calendar popup](calendar-popup.md): open the full calendar over any page of the console with the calendar button or the C key, and close it.

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

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/pmos-verbs.js

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

package/workspace/lib/route-modules.js

@@ -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-my-work.js

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

package/workspace/lib/routes-sources.js

@@ -0,0 +1,64 @@
+'use strict';
+/* routes-sources.js — how old each source of a workspace is, and Refresh now (workspace-data-freshness R6, R7).
+ *
+ *   GET  /api/sources?ws=<id>                → { ok, ws, version, sources: [row] }   lib/freshness.js sources()
+ *   POST /api/sources/refresh { ws, source } → { ok, source, started: 'rebuild'|'session', session? }
+ *   POST /api/sources/watch   { ws, on }     → { ok, watch }   the change detector on or off for this repository
+ *
+ * Both POSTs pass pm-guard requirePagePress: the PM's press from the page. An agent session cannot start a refresh or
+ * switch the detector off. A refresh of `repository` or `initiatives` rebuilds the facts in a child process; a refresh of
+ * an external source starts that source's skill as a session in the workspace, with the PM's own connections. The server
+ * itself calls nothing outside this machine.
+ */
+const guard = require('./pm-guard.js');
+const freshness = require('./freshness.js');
+
+function wsOf(ctx, id) {
+  const w = ctx.getWs(id || '');
+  return w && (!id || w.id === id) ? w : null;
+}
+const repoStateDir = (ctx, w) => { try { return ctx.stateDirFor ? ctx.stateDirFor(w) : null; } catch { return null; } };
+
+async function handle(req, res, url, ctx) {
+  const p = url.pathname;
+  const F = ctx.freshness;
+  if (!F) return false;
+  if (p === '/api/sources') {
+    if (req.method !== 'GET') { ctx.json(res, { ok: false, error: 'GET only' }, 405); return true; }
+    const w = wsOf(ctx, url.searchParams.get('ws'));
+    if (!w) { ctx.json(res, { ok: false, error: 'no such workspace' }, 404); return true; }
+    const sources = F.sources({ id: w.id, root: w.root, repoStateDir: repoStateDir(ctx, w) });
+    ctx.json(res, { ok: true, ws: w.id, version: F.versions()[w.id] || 0, sources });
+    return true;
+  }
+  if (p !== '/api/sources/refresh' && p !== '/api/sources/watch') return false;
+  if (req.method !== 'POST') { ctx.json(res, { ok: false, error: 'POST only' }, 405); return true; }
+  const got = await ctx.readJson(req);
+  if (!got.ok) { ctx.json(res, { ok: false, error: 'the body is not JSON' }, 400); return true; }
+  const body = got.body || {};
+  const g = guard.requirePagePress(req, body);
+  if (!g.ok) { ctx.json(res, { ok: false, error: g.error }, g.status); return true; }
+  const w = wsOf(ctx, typeof body.ws === 'string' ? body.ws : '');
+  if (!w) { ctx.json(res, { ok: false, error: 'no such workspace' }, 404); return true; }
+
+  if (p === '/api/sources/watch') {
+    if (typeof body.on !== 'boolean') { ctx.json(res, { ok: false, error: 'on must be true or false' }, 400); return true; }
+    if (!F.setEnabled(w.root, body.on)) { ctx.json(res, { ok: false, error: 'the setting could not be saved' }, 500); return true; }
+    ctx.json(res, { ok: true, watch: F.enabled(w.root) });
+    return true;
+  }
+
+  const src = freshness.SOURCES.find((s) => s.id === body.source);
+  if (!src) { ctx.json(res, { ok: false, error: 'source must be one of ' + freshness.SOURCES.map((s) => s.id).join(', ') }, 400); return true; }
+  if (!src.skill) {
+    ctx.factsRefresh(w.root);
+    ctx.json(res, { ok: true, source: src.id, started: 'rebuild' });
+    return true;
+  }
+  const r = ctx.startSkill(w.id, src.skill, `${src.label} · refresh`);
+  if (!r.ok) { ctx.json(res, { ok: false, error: r.error }, r.status || 500); return true; }
+  ctx.json(res, { ok: true, source: src.id, started: 'session', session: r.session });
+  return true;
+}
+
+module.exports = { prefixes: ['/api/sources'], handle };

package/workspace/package-lock.json

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

package/workspace/package.json

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

package/workspace/public/pm/c3-shell.js

@@ -44,6 +44,7 @@ import { mountTicker } from './shell-ticker.js';
 import { mountBell, openBellList } from './shell-bell.js';
 import { onBriefing, loadBriefing } from './shell-ticker.js';
 import { registry, filterPalette, rowStep } from './briefing-model.js';
+import { freshnessLine } from './freshness-line.js';
 
 /* In demo mode each tab's deck asks for its own cards (the mockup draws a different deck per tab); real mode sends no scope. */
 const sc = (name) => (DEMO ? name : undefined);
@@ -105,7 +106,9 @@ function header() {
   mountCalPopupTrigger(S.tools);   // the calendar button (before Search) and the key C (c3-calpop.js)
   S.moreBtn = ibtn('More', 'more', { 'aria-haspopup': 'menu', 'aria-expanded': 'false', 'data-c3pg': 'more', onclick: toggleMore });
   S.tools.append(el('span', { class: 'c3pg-menuwrap' }, S.moreBtn));
-  return el('div', { class: 'c3top' }, el('div', null, S.ttl, S.sub), S.tools);
+  /* workspace-data-freshness R9: how old the sources are, quiet when they are up to date (freshness-line.js) */
+  S.fresh = S.demo ? null : freshnessLine(S.ws);
+  return el('div', { class: 'c3top' }, el('div', null, S.ttl, S.sub, S.fresh), S.tools);
 }
 
 /* the More menu (console3.html menuPop, line 1940): why each element is here, incident day, agent playbooks, phone preview; and ours: the theme and a way to

package/workspace/public/pm/components.css

@@ -3499,6 +3499,39 @@
 .fr-set__envrows { display: flex; flex-direction: column; gap: 6px; }
 .fr-set__flags { display: flex; flex-direction: column; gap: 8px; align-items: flex-start; min-width: 0; width: 100%; }
 
+/* workspace-data-freshness: the console header's freshness line and Settings › Data freshness (pm/freshness-line.js) */
+.fr-fresh {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  font-size: 12px;
+  color: var(--muted-foreground);
+}
+.fr-fresh__state--fresh { color: var(--foreground); }
+.fr-fresh__state--stale { color: var(--warning); }
+.fr-fresh__state--failed { color: var(--destructive); }
+.fr-fresh__state--never,
+.fr-fresh__state--building,
+.fr-fresh__state--off { color: var(--muted-foreground); }
+.fr-fresh-table__grid {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12px;
+}
+.fr-fresh-table__grid th {
+  padding: 4px 8px;
+  text-align: left;
+  font-weight: 600;
+}
+.fr-fresh-table__grid td {
+  padding: 4px 8px;
+  vertical-align: top;
+}
+.fr-fresh-table__watch {
+  margin-top: 8px;
+}
+
 /* -- layouts · .td- Today (Run 3, slice 3B) -- */
 .td-board {
   display: flex;

package/workspace/public/pm/dest-settings.js

@@ -33,6 +33,7 @@ import { COPY } from './frame-copy.js';
 import { askConfirm } from './dialogs.js';
 import { icon } from './icons.js';
 import { flagPicker, flagsLine, flagsMissingValue } from './flag-picker.js';
+import { freshnessTable } from './freshness-line.js';
 
 const P = COPY.page;
 const roots = new WeakMap();      // host -> { root, sig }
@@ -542,6 +543,13 @@ function checkButton(scope) {
   });
 }
 
+/* ── Data freshness (workspace-data-freshness R9): how old each source is, Refresh, and the change detector switch ── */
+function freshnessSection(scope) {
+  const ws = wsOfRepo(scope === 'all' ? null : activeProduct());
+  if (!ws) return section('freshness', 'Data freshness', [empty({ text: 'Open a repository to see how old its data is.' })], null, 'refresh-cw');
+  return section('freshness', 'Data freshness', [freshnessTable(ws)], null, 'refresh-cw');
+}
+
 /* ── mount ────────────────────────────────────────────────────────────────────────────────────────────────────────── */
 
 function signature(scope) {
@@ -583,7 +591,8 @@ export function mountDestination(host, ctx) {
       peopleSection(scope),
       onlineSection(),
       themeSection(),
-      updatesSection(scope)),
+      updatesSection(scope),
+      freshnessSection(scope)),
   ]);
 }
 

package/workspace/public/pm/freshness-line.js

@@ -0,0 +1,123 @@
+/* pm/freshness-line.js — how old each source of the workspace is (workspace-data-freshness R9).
+ *
+ *   freshnessLine(ws)   → element   the console header's short line: the sources that are old or never read, else
+ *                                   "Up to date"; a Refresh button for the oldest one. Updates itself every 15 s.
+ *   freshnessTable(ws)  → element   Settings › Data freshness: every source, when it was read, its state, its schedule,
+ *                                   Refresh, and the repository's Watch for changes switch.
+ *
+ * Both read GET /api/sources (lib/routes-sources.js). The presses go through pmPost (the page nonce), so an agent cannot
+ * make them. When a workspace's data version moves, the line sends `pmos:data-changed` with { ws } on window, so a view
+ * that wants to read again only on a change can listen for it. One element per ws and kind, kept across redraws, so a
+ * page that rebuilds its DOM does not start a second poll.
+ */
+import { el, setChildren } from './dom.js';
+import { pmGet, pmPost } from './http.js';
+import { button, SEL } from './primitives.js';
+
+const POLL_MS = 15000;
+const live = new Map();   // kind|ws -> { node, timer, version }
+
+const hhmm = (iso) => { const d = new Date(iso); return String(d.getHours()).padStart(2, '0') + ':' + String(d.getMinutes()).padStart(2, '0'); };
+function ago(iso) {
+  if (!iso) return 'never read';
+  const ms = Date.now() - Date.parse(iso);
+  if (ms < 60000) return 'just now';
+  if (ms < 3600000) return Math.round(ms / 60000) + ' min ago';
+  if (ms < 24 * 3600000) return 'today ' + hhmm(iso);
+  return Math.round(ms / (24 * 3600000)) + ' d ago';
+}
+const STATE_WORD = { fresh: 'Up to date', stale: 'Old', never: 'Never read', building: 'Reading…', failed: 'Failed', off: 'Off' };
+// the colour of a state: a class in components.css (.fr-fresh__state--<state>), coloured from the tokens
+const tone = (state) => 'fr-fresh__state fr-fresh__state--' + (STATE_WORD[state] ? state : 'never');
+const label = (b, t) => { const l = b.querySelector(SEL.btnLabel); (l || b).textContent = t; };
+
+async function read(ws) {
+  const r = await pmGet('/api/sources' + (ws ? '?ws=' + encodeURIComponent(ws) : ''));
+  return r && r.ok ? r : null;
+}
+async function refresh(ws, source, btn) {
+  if (btn) { btn.disabled = true; label(btn, 'Starting…'); }
+  const r = await pmPost('/api/sources/refresh', { ws, source });
+  if (btn) label(btn, r && r.ok ? (r.started === 'session' ? 'Agent started' : 'Reading…') : 'Could not start');
+  return r;
+}
+
+function poll(key, ws, draw) {
+  let cur = live.get(key);
+  if (cur) return cur.node;
+  cur = { node: null, timer: null, version: null };
+  live.set(key, cur);
+  const tick = async () => {
+    const d = await read(ws).catch(() => null);
+    if (d) {
+      if (cur.version != null && d.version !== cur.version) {
+        try { window.dispatchEvent(new CustomEvent('pmos:data-changed', { detail: { ws: d.ws } })); } catch { /* no window */ }
+      }
+      cur.version = d.version;
+    }
+    draw(cur.node, d);
+  };
+  cur.tick = tick;
+  cur.node = draw(null, null);
+  tick();
+  cur.timer = setInterval(() => { if (!cur.node.isConnected && cur.node.dataset.mounted === '1') { clearInterval(cur.timer); live.delete(key); return; } if (cur.node.isConnected) cur.node.dataset.mounted = '1'; tick(); }, POLL_MS);
+  return cur.node;
+}
+
+/** The header line: quiet when everything is fresh, amber names when a source is old or never read. */
+export function freshnessLine(ws) {
+  return poll('line|' + ws, ws, (node, d) => {
+    const n = node || el('div', { class: 'fr-fresh', 'data-c3pg': 'freshness' });
+    if (!d) { if (!node) n.textContent = ''; return n; }
+    const watched = d.sources.filter((s) => s.state !== 'off');
+    const behind = watched.filter((s) => s.state === 'stale' || s.state === 'failed' || (s.state === 'never' && s.schedule));
+    const building = watched.find((s) => s.state === 'building');
+    const kids = [];
+    if (!behind.length) kids.push(el('span', { class: tone('fresh') }, building ? 'Reading the repository…' : 'Data up to date'));
+    for (const s of behind.slice(0, 3)) kids.push(el('span', { class: tone(s.state), title: STATE_WORD[s.state] }, s.label + ' ' + ago(s.as_of)));
+    if (behind.length) {
+      const first = behind[0];
+      const btn = button({ label: 'Refresh ' + first.label, size: 'sm', attrs: { 'data-c3pg': 'freshness-refresh' },
+        onClick: () => refresh(d.ws, first.id, btn) });
+      kids.push(btn);
+    }
+    setChildren(n, kids);
+    return n;
+  });
+}
+
+/** The Settings table: every source of the workspace, with Refresh, and the change detector switch. */
+export function freshnessTable(ws) {
+  return poll('table|' + ws, ws, (node, d) => {
+    const n = node || el('div', { class: 'fr-fresh-table', 'data-fr': 'freshness' });
+    if (!d) { if (!node) n.textContent = 'Reading…'; return n; }
+    const th = (t) => el('th', null, t);
+    const td = (...k) => el('td', null, ...k);
+    const rows = d.sources.map((s) => {
+      const btn = button({ label: 'Refresh', size: 'sm', disabled: s.state === 'off' || s.state === 'building',
+        attrs: { 'data-fr': 'freshness-refresh-' + s.id }, onClick: () => refresh(d.ws, s.id, btn) });
+      const sched = s.schedule ? [s.schedule.cadence, s.schedule.day, s.schedule.time].filter(Boolean).join(' ') : (s.skill ? 'no schedule' : 'on every change');
+      return el('tr', { 'data-fr-source': s.id },
+        td(s.label), td(s.id === 'repository' && s.state === 'fresh' ? 'watching' : s.as_of ? ago(s.as_of) : 'never'), td(el('span', { class: tone(s.state) }, STATE_WORD[s.state] || s.state)),
+        td(sched), td(btn));
+    });
+    const repo = d.sources.find((s) => s.id === 'repository');
+    const on = !repo || repo.state !== 'off';
+    // a button, not a checkbox: on a phone every control is 44px high (R27), and a checkbox box is not
+    const sw = button({ label: on ? 'Stop watching this repository' : 'Watch this repository for changes', size: 'sm',
+      attrs: { 'data-fr': 'freshness-watch', 'aria-pressed': on ? 'true' : 'false', class: 'fr-fresh-table__watch' },
+      onClick: async () => {
+        sw.disabled = true;
+        const r = await pmPost('/api/sources/watch', { ws: d.ws, on: !on });
+        if (r && r.ok) { const c = live.get('table|' + ws); if (c) c.tick(); } else { sw.disabled = false; label(sw, 'Could not save'); }
+      } });
+    setChildren(n, [
+      el('table', { class: 'fr-fresh-table__grid' },
+        el('thead', null, el('tr', null, th('Source'), th('Read'), th('State'), th('Schedule'), th(''))),
+        el('tbody', null, ...rows)),
+      sw,
+      el('p', { class: 'fr-set__note' }, 'The workspace holds no password or token. Calendar, Jira and My work are read by an agent session with your own connection.'),
+    ]);
+    return n;
+  });
+}

package/workspace/server.js

@@ -1942,6 +1942,21 @@ const autoSync = require('./lib/auto-sync').createAutoSync({
   onDone: (root) => boardCache.invalidate(root),
   label: `${os.hostname()} (auto-sync)`,
 });
+// workspace-data-freshness (R2 to R4): the facts cache is kept in the runtime state folder, and ONE change detector per
+// workspace starts the board and facts rebuilds when the repository changes, so nothing is re-read on a clock. The board
+// keeps its last value while it rebuilds (stale while revalidate): dropping it would show a blank Board on every change.
+const factsAsync = require('./lib/facts-async.js');
+factsAsync.configure({ stateDir: STATE });
+const freshness = require('./lib/freshness.js').create({
+  stateDir: STATE,
+  workspaces: () => [...workspaces.values()],
+  schedules: () => readSchedules(),
+  factsStatus: (root) => factsAsync.status(root),
+  onChange: (w) => { boardCache.board(w.root, { refreshNow: true }); factsAsync.refresh(w.root); },
+  pollMs: Math.max(250, Number(process.env.PMOS_FRESH_POLL_MS) || 10000),
+  stableMs: Math.max(0, Number(process.env.PMOS_FRESH_STABLE_MS) || 3000),
+});
+if (!REQUIRED_AS_LIBRARY) freshness.start();
 const STOPPED_STATES = ['closed', 'on-hold', 'cancelled'];
 function readLifecycle(w) {
   const latest = new Map();
@@ -2362,6 +2377,12 @@ const SEED_SETS = {
   // jira-wbs (J14): the agent step that reads the status of every pushed Jira ticket into each initiative's snapshot,
   // read-only. Daily at 06:30, so the morning brief (06:45) and every report read a status at most a day old.
   jira: [{ name: 'Jira status check', skill: 'jira-sync', cadence: 'daily', time: '06:30' }],
+  // workspace-data-freshness (R8): the read-only calendar pull, before the morning brief (06:45) and again at midday, so
+  // Briefing and Calendar never work from yesterday's events.
+  calendar: [
+    { name: 'Calendar pull (morning)', skill: 'calendar-sync', cadence: 'daily', time: '06:30' },
+    { name: 'Calendar pull (midday)', skill: 'calendar-sync', cadence: 'daily', time: '12:30' },
+  ],
 };
 function readSchedules() {
   try { const a = JSON.parse(fs.readFileSync(schedFile(), 'utf8')); return Array.isArray(a) ? a : []; } catch { return []; }
@@ -4065,6 +4086,18 @@ function myWorkRead(wsId) {
   if (!s || s.state === 'exited') return { ok: false, status: 500, error: (s && s.note) || 'the read session could not start' };
   return { ok: true, session: s.id };
 }
+/** Refresh now (workspace-data-freshness R7): start skill `skillId` in a session of repository `wsId`, as myWorkRead does. */
+function startSkillSession(wsId, skillId, name) {
+  const w = getWs(wsId);
+  if (!w) return { ok: false, status: 400, error: 'no workspace' };
+  const task = taskById(skillId, w.root);
+  if (!task || task.kind !== 'agent' || !task.prompt) return { ok: false, status: 409, error: `the ${skillId} skill is not installed for this repository` };
+  const prompt = skillStore.retargetFiling(task.prompt, filingContract(w));
+  const s = spawnSession({ name, agent: task.agent || 'claude', ws: w.id, origin: 'source-refresh', initialInput: prompt + '\r',
+    modelAsk: { scheduleTier: null, skillTier: task.tier || null, skill: task.skill } });
+  if (!s || s.state === 'exited') return { ok: false, status: 500, error: (s && s.note) || 'the refresh session could not start' };
+  return { ok: true, session: s.id };
+}
 /* The calendar the Agenda remembers (G23): one file beside the briefs, written only by the brief route. */
 const CAL_MEMORY = () => path.join(STATE, 'calendar-memory.json');
 // the PM's key-meeting marks (lib/calendar-memory.js setMark): a small file beside the calendar memory, written only by
@@ -6457,7 +6490,9 @@ async function handleRequest(req, res) {
   // `ledgers` (pm-os-absorb Run 1) — the plan-items signature of every registered workspace, so an open Breakdown
   // knows to refetch: `items` is one stat per workspace; `evidence` is computed only for the ids in ?ledgers=
   // (at most 4). Computed on this request and never stored (D33).
-  if (p === '/api/sessions') return json(res, { sessions: sessionList(), version: APP_VERSION,
+  // `data_versions` (workspace-data-freshness R4): a number per workspace that moves when its files change, so a page
+  // refetches only then.
+  if (p === '/api/sessions') return json(res, { sessions: sessionList(), version: APP_VERSION, data_versions: freshness.versions(),
     ledgers: planItems.ledgerSigs([...workspaces.values()].map((w) => ({ id: w.id, root: w.root })), url.searchParams.get('ledgers')) });
   if (p === '/api/git/branches') {
     // Read-only branch awareness for a workspace. A non-repo returns {ok:false} (never a fake
@@ -8654,7 +8689,9 @@ async function handleRequest(req, res) {
   if (await routeModules.dispatch(req, res, url, { json, readBody, getWs, invalidateNeedsAgg, boardCache, consoleState, stateDirFor, sessionList, initiativeIndex,
     runtimeDir: STATE, spawnSession, jevModelOpts, sendToSession,
     // initiative my-work: every registered repository, the day runs, and the two presses that start sessions
-    workspaceList: () => [...workspaces.values()], readDayRun, myWorkBrief, myWorkRead })) return;
+    workspaceList: () => [...workspaces.values()], readDayRun, myWorkBrief, myWorkRead,
+    // workspace-data-freshness: the source table, the facts rebuild and Refresh now's skill sessions
+    freshness, factsRefresh: (root) => factsAsync.refresh(root, { force: true }), startSkill: startSkillSession })) return;
   res.writeHead(404); res.end('not found');
 }
 

package/workspace/skills/calendar-sync.skill

@@ -0,0 +1,30 @@
+---
+name: calendar-sync
+label: "Calendar pull"
+description: "Read, read-only, the PM's calendar events for today and the next 14 days, and hand them to PMOS so Briefing and Calendar work from today's events. It writes nothing to the calendar."
+run: agent
+agent: claude
+output:
+  - Imported
+  - Not reached
+  - Needs you
+---
+
+/calendar-sync — bring the PM's calendar up to date in PMOS. You read the calendar with the PM's own calendar connection. PMOS saves what you read and shows it on Briefing and Calendar. You change nothing in the calendar.
+
+Rules that always hold:
+1. READ-ONLY on the calendar. Use only the tools that list or read events. Never create, edit, move, accept, decline, delete or respond to an event, and never send an invitation or a message.
+2. THE ONLY WRITE is `pmos calendar import --from <file> --sensitivity <label>`, once, at the end. Never edit a repository file. Never commit.
+3. LIGHT ON CONTENT. For each event, give only its id, title, start, end, the attendees' display names and, when you can tell, the initiative id it is for. Never copy a description, a meeting link, a dial-in number, an attachment, an email address or a token.
+4. SENSITIVITY. Use `internal` unless the PM said otherwise. Leave out any event marked private, personal, confidential or HR, and count it.
+5. TEMPORARY FILES OUTSIDE THE REPOSITORY. Write the events file in this session's scratch folder, and delete it after the import.
+6. NOTHING INVENTED. If the calendar cannot be reached, list it under "Not reached" and import nothing: an empty import is not a calendar with no meetings.
+
+Procedure:
+1. List the PM's events from the start of today to the end of the 14th day after today, from the primary calendar. Fetch every page. Skip an event the PM declined.
+2. Write the events as JSON in the scratch folder, for example `<scratch>/calendar.json`, as a list with one object per event:
+   `{"id", "title", "start", "end", "attendees": ["Display Name", …], "initiative": "<initiative id or null>"}`
+   `start` and `end` are ISO times with the offset, for example `2026-10-12T09:00:00+07:00`. An all-day event has the date only.
+3. Run `pmos calendar import --from <scratch>/calendar.json --sensitivity internal`. If it refuses the file, fix what it names and run it once more.
+4. Delete the scratch file.
+5. Report in four short lists: Imported (the count, and the first and last day), Left out (the count of private events), Not reached, and Needs you (only when something blocked the pull).

package/workspace/test-lists/workspace-data-freshness.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "workspace-data-freshness: the shared commit range, the change-keyed facts cache, the change detector and data version, the source table and Refresh now, the worker-thread folds, and pmos calendar.",
+  "modules": ["data-freshness.test.js"],
+  "panels": [],
+  "seconds": { "data-freshness.test.js": 25 }
+}