create-pmos 0.131.0 → 0.133.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.131.0",
+  "version": "0.133.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@c3d0fb4
 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:26:11Z"}
 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:26:11Z"}
 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:26:11Z"}
 status: stable
 ---
 

package/workspace/bin/pmos.js

@@ -188,6 +188,7 @@ function ensureInstalled() {
 // Register the target directory and open the browser ON IT. The `focus` broadcast matters:
 // the OS may refocus an already-open tab instead of opening our URL, and without it the PM
 // would be looking at the previously-opened repo — the defect this replaces.
+let FORCE_WELCOME = false; // `pmos welcome [path]`
 async function openWorkspace(dir, port, { open = true } = {}) {
   const root = repoRootOf(dir);
   const reg = await api(port, 'POST', '/api/workspaces', { root, name: path.basename(root) });
@@ -199,7 +200,17 @@ async function openWorkspace(dir, port, { open = true } = {}) {
   const w = reg.workspace;
   say(`✓ workspace “${w.name}” — ${urlOf(port)}?ws=${w.id}`);
   say(`  ${root}`);
-  if (open) openBrowser(`${urlOf(port)}?ws=${w.id}`);
+  // First run (onboarding-scan-and-map): a plain folder PMOS has never imported opens on Welcome (the route's first_run);
+  // `pmos welcome` opens it on purpose. Any failure keeps the old URL.
+  let first = FORCE_WELCOME;
+  if (!first) {
+    try {
+      const st = await api(port, 'GET', `/api/onboarding/status?ws=${encodeURIComponent(w.id)}`);
+      first = !!(st && st.ok && st.first_run);
+    } catch { first = false; }
+  }
+  if (first) say(FORCE_WELCOME ? '✓ opening Welcome' : '✓ first run — opening Welcome');
+  if (open) openBrowser(first ? `${urlOf(port)}/welcome?ws=${w.id}` : `${urlOf(port)}?ws=${w.id}`);
   return 0;
 }
 
@@ -511,9 +522,10 @@ function doctor() {
     if (r.error) { say('✗ could not run ' + npx + ' — ' + r.error.message); code = 1; }
     else code = r.status === null ? 1 : r.status;
   } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    say('usage: pmos [<path>|status|ls|stop|doctor|phone|upgrade|schedule|skill|proactive|kg|item|' + require('../lib/pmos-verbs.js').names().join('|') + ']');
+    say('usage: pmos [<path>|welcome|status|ls|stop|doctor|phone|upgrade|schedule|skill|proactive|kg|item|' + require('../lib/pmos-verbs.js').names().join('|') + ']');
     say('  pmos          open the current repo as a workspace (starts the server if needed)');
     say('  pmos <path>   open another repo as a workspace');
+    say('  pmos welcome [<path>]  scan a folder and bring its products and initiatives into PMOS (undoable)');
     say('  pmos phone    turn on phone access over Tailscale and show the QR code to scan');
     say('  pmos schedule …  create, edit and run scheduled tasks (pmos schedule --help)');
     say('  pmos skill …     list, read, create and edit skills');
@@ -523,6 +535,10 @@ function doctor() {
     for (const line of require('../lib/pmos-verbs.js').helpLines()) say(line);
     say('  pmos upgrade  reinstall the workspace app from the latest published create-pmos');
     code = 0;
+  } else if (cmd === 'welcome') {
+    // the first-run page on purpose: scan this folder, import it, or undo an import (onboarding-scan-and-map)
+    FORCE_WELCOME = true;
+    code = await up(process.argv[3] && !process.argv[3].startsWith('-') ? path.resolve(process.argv[3]) : process.cwd());
   } else if (cmd === 'up' || cmd === 'start' || cmd === 'open') {
     // `pmos open ../other-repo` — the path is the argument AFTER the verb
     code = await up(process.argv[3] && !process.argv[3].startsWith('-') ? path.resolve(process.argv[3]) : process.cwd());

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

@@ -39,10 +39,12 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 
 ## Where to read next
 
+- [Welcome (first run)](welcome.md): scan a new folder, review the proposed portfolio, import it and undo it.
 - [The Briefing](briefing.md): the console's first page: Today's meetings, Needs you (Done, Not yet, Drop) and the Portfolio pulse.
 - [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/guide/welcome.md

@@ -0,0 +1,38 @@
+---
+type: Guide
+title: "Guide: Welcome (first run)"
+timestamp: 2026-10-11
+---
+
+# Welcome (first run)
+
+The Welcome page is the first screen of a new folder. It reads your folder, shows what it found, and sets up your portfolio from it. You do not need to answer questions first.
+
+## How you get there
+
+Run `pmos` in a plain folder that PMOS has not imported. The terminal says "first run — opening Welcome" and the browser opens `/welcome`. A folder that already has its own PMOS state folder opens the console as before. After an import, `pmos` opens the console.
+
+Run `pmos welcome` to open the page on purpose, for example to scan a folder again or to undo an import. `pmos welcome <path>` opens it for another folder.
+
+Choose **Not now** on the first screen to go to the console. Welcome then stops opening on its own for that folder. `pmos welcome` still opens it.
+
+## The promise
+
+The page says it before the scan: PMOS reads only, writes nothing in your folder, and nothing leaves this computer. The scan runs on your machine and uses no model. The import is stored in the PMOS state folder, never in your folder.
+
+## The steps
+
+1. **Welcome.** The page shows the folder name and path. Choose **Add another folder** to open the system folder chooser and add a second folder. Choose **Scan** to start. A spinner shows while the scan runs. A large folder can take a minute or two, and the rest of PMOS keeps working.
+2. **First look.** One sentence gives the counts: initiatives, documents, deadlines, stale documents, duplicates, people and risks. Up to ten findings follow. Each finding shows the file and line it comes from. Choose **Continue**.
+3. **Your portfolio.** PMOS proposes one board for each product folder (`products/<name>/`). If there is no product folder, it proposes one board for the whole folder. Each board lists its initiatives. Each row has a checkbox, a title you can edit, a lane, an anchor, a stage and a document count. Choose the document count to see the documents. Use the board list on a row to move it to another board. Each board shows how many documents PMOS could not place. High and medium confidence rows start checked. The button reads **Import N initiatives into M boards**. The numbers change as you check, uncheck and move rows.
+4. **Questions.** This step appears only when the scan could not decide something. There are three questions at most. Each question shows its default already chosen. Choose **Import** to accept what is chosen. Choose **Skip** to leave a question open: for the anchor question, the proposed anchors then stay marked for you to confirm later.
+5. **First Briefing.** After the import, the page lists up to five things that need you first. An item that belongs to an imported initiative names the initiative and its board. Choose **Continue**. Choose **Undo this import** to take the import back and return to your portfolio.
+6. **More sources.** This step is optional. It offers Calendar (your meetings today and for the next 14 days) and Jira (the issues assigned to you). PMOS reads nothing from them until you choose **Bring in**. Bring in starts the source's read-only skill as an agent session in the workspace, with your own connection. The skill writes nothing to the tool. Choose **Skip** to leave a source out. You can bring it in later from Settings. Inbox and Slack have no import yet. Choose **Open PMOS** to go to the console.
+
+## Undo
+
+**Undo this import** retracts the import. Nothing is deleted: the import and its undo stay in the record. You can then change the portfolio and import again. When you open Welcome after an import, the page shows the first Briefing with the Undo link.
+
+## What the page does not do
+
+The page does not change your folder. It does not open the files that the exclusion list names, such as `.git`, `node_modules` and files that look like secrets. It does not read Calendar or Jira until you choose **Bring in** on More sources, and the PMOS server itself calls nothing outside this computer. It does not import from Drive, Inbox, Slack or other tools.

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