create-pmos 0.523.0 → 0.525.0

package/workspace/lib/proposals.js

@@ -21,6 +21,8 @@
  *   description the record's own description (initiative-description-field; filed by lib/description-props.js): type new (none yet) or
  *           enrich (the PRD says more). data { text, from? }; one item { id: 'description', title: the text cut }. Always section 'check'.
  *           ✓ writes the record's description line (lib/initiative-writer.js setDescription)
+ *   prototyped · improved · scanned   what the idle lab made while the PM was away (lib/idle-lab.js result): a first round of 2–3 specimens,
+ *           a new round of one, a scan finding to attach as evidence. No items; always section 'check'. ✓ keeps it as a document
  *   grill   what Claude found when it grilled the initiative by itself (lib/grill.js): type = the angle, no items, a next step in data.next;
  *           always section 'check' (its own ✓, never Keep all). 3 show, best rank first; the group's `more` counts the rest
  *
@@ -30,7 +32,7 @@
  *   end      { ini, run, ok, stopped? }                           the run ended (stopped: the PM pressed ■)
  *   propose  { ini, board, run, id, group, type, section, title, why, sources: [{ label, ref }], items: [item], data }
  *            an agent filed it (`pmos propose …`); the last line for an id wins, so a newer run replaces what it files again
- *   drop     { ini, sig, facts? }   ✕ on a proposal or on one item of it: gone until its evidence changes (a new signature) or the date
+ *   drop     { ini, sig, facts?, why? }   why: the PM's reason, when given (the idle lab learns from it). ✕ on a proposal or on one item of it: gone until its evidence changes (a new signature) or the date
  *            passes again. `facts` (batch 24 item 6) are what the ✕ rests on, not where the work sits: a date proposal's facts are its tasks
  *            and the due dates they missed, a grill finding's are its angle and its sources. A ✕ holds while they hold, so a workflow switch
  *            (new section keys, so new ids and signatures), a reworded reason or a new day (new computed dates) does not bring it back
@@ -64,6 +66,7 @@ const TYPES = { found: ['stage', 'docs', 'tasks', 'link', 'maybe', 'unplaced'],
 const SOURCES = ['drive', 'docs', 'sheets', 'slides', 'jira', 'calendar', 'notes', 'mail', 'slack', 'confluence', 'chat', 'repo'];
 const SOURCE_NAMES = { drive: 'Drive and Slides', docs: 'Docs', sheets: 'Sheets', slides: 'Slides', jira: 'Jira', calendar: 'Calendar and meeting notes', notes: 'Meeting notes',
   mail: 'Gmail', slack: 'Slack', confluence: 'Confluence', chat: 'Chat', repo: 'This repository' };
+const LAB = ['prototyped', 'improved', 'scanned'];   // the idle lab's results (lib/idle-lab.js result): no items, always section 'check'
 const CLOSED = new Set(['Done', "Won't do", 'Archived']);
 const RISK_DAYS = 3;
 const MON = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
@@ -201,6 +204,7 @@ function tidyName(from, to) {
 function fold(lines) {
   const props = new Map();    // id → the newest propose line
   const drops = new Set();    // signatures
+  const dropWhy = new Map();  // signature → the PM's reason for the ✕, when one was given (the idle lab learns from it)
   const kept = [];            // keep lines, oldest first
   const undone = new Set();
   const looks = new Map();    // ini → { run, why, at, ended, ok, stopped, sources: Map source → { state, n, what } }
@@ -214,11 +218,11 @@ function fold(lines) {
     else if (l.kind === 'src' && ini) { const L = looks.get(ini); if (L && L.run === l.run && str(l.source)) L.sources.set(l.source, { state: l.state === 'done' ? 'done' : 'reading', n: Number(l.n) || 0, what: str(l.what) }); }
     else if (l.kind === 'end' && ini) { const L = looks.get(ini); if (L && L.run === l.run) { L.ended = true; L.ok = !!l.ok; L.stopped = !!l.stopped; L.endAt = l.at || ''; } }
     else if (l.kind === 'propose' && ini && str(l.id)) props.set(l.id, { id: l.id, ini, board: str(l.board), run: str(l.run), group: l.group, type: l.type, section: str(l.section) || 'sure', title: str(l.title), why: str(l.why), sources: Array.isArray(l.sources) ? l.sources : [], items: Array.isArray(l.items) ? l.items.filter(isObj) : [], data: isObj(l.data) ? l.data : {}, at: l.at || '', by: l.by || null });
-    else if (l.kind === 'drop' && str(l.sig)) { drops.add(l.sig); for (const f of Array.isArray(l.facts) ? l.facts : []) if (/^f:[0-9a-f]{10}$/.test(String(f))) drops.add(f); }
+    else if (l.kind === 'drop' && str(l.sig)) { drops.add(l.sig); if (str(l.why)) dropWhy.set(l.sig, one(l.why, 300)); for (const f of Array.isArray(l.facts) ? l.facts : []) if (/^f:[0-9a-f]{10}$/.test(String(f))) drops.add(f); }
     else if (l.kind === 'keep' && str(l.batch)) kept.push({ batch: l.batch, ini, board: str(l.board), ids: Array.isArray(l.ids) ? l.ids : [], wrote: Array.isArray(l.wrote) ? l.wrote.filter(isObj) : [], at: l.at || '', by: l.by || null });
     else if (l.kind === 'undo' && str(l.batch)) undone.add(l.batch);
   }
-  return { props, drops, kept, undone, looks, epoch, t };
+  return { props, drops, dropWhy, kept, undone, looks, epoch, t };
 }
 /** The kept proposal ids (a batch undone gives its proposals back). */
 const keptIds = (F) => { const s = new Set(); for (const k of F.kept) if (!F.undone.has(k.batch)) for (const id of k.ids) s.add(id); return s; };
@@ -332,7 +336,7 @@ function datesOf(ini, T, o = {}) {
 }
 
 /* ── what r.props carries ── */
-const ORDER = { description: -2, outcome: -1, found: 0, dates: 1, status: 2, names: 3, links: 4, grill: 5 };
+const ORDER = { description: -2, outcome: -1, prototyped: -0.6, improved: -0.5, scanned: -0.4, found: 0, dates: 1, status: 2, names: 3, links: 4, grill: 5 };
 const GRILL_SHOWN = 3;
 /**
  * One initiative's proposals, as the ✦ and the Viewer draw them, or null when there is nothing to show.
@@ -351,7 +355,7 @@ function viewOf(F, ini, o = {}) {
     p.items = p.items.filter((x) => !F.drops.has(itemSig(p, x)) && (!x.task || (T.has(x.task) && !(p.group !== 'found' && T.get(x.task).closed && p.group !== 'status'))));
     if (p.group === 'status') p.items = p.items.filter((x) => T.has(x.task) && !T.get(x.task).closed);
     if (p.group === 'names') p.items = p.items.filter((x) => T.has(x.task) && T.get(x.task).title !== x.to).map((x) => ({ ...x, from: T.get(x.task).title, ...(T.get(x.task).jira ? { jira: true } : {}) }));
-    if (!p.items.length && p.type !== 'stage' && p.group !== 'grill') continue;
+    if (!p.items.length && p.type !== 'stage' && p.group !== 'grill' && !LAB.includes(p.group)) continue;
     if (p.group === 'grill' && factsOf(p).some((f) => F.drops.has(f))) continue;
     props.push(p);
   }

package/workspace/lib/read-fingerprint.js

@@ -0,0 +1,127 @@
+'use strict';
+/* read-fingerprint.js — did a source read bring anything new? (smart refresh, step 1: measure)
+ *
+ *   of(source, dirs)  → { hash, n } | null      the fingerprint of what PMOS stores for `source` now; null when nothing is stored
+ *   compare(prev, fp) → 'first' | 'same' | 'changed' | null    prev is the { hash, keys? } kept from the last read
+ *   SOURCES · SHORT
+ *     dirs { runtime: <per-user state folder>, jira: <repository state>/tracker/jira }
+ *
+ * THE RULE. A fingerprint hashes the FACTS a read stored and nothing else:
+ *   - no read time (read_at, fetched_at, timestamp, "Read from Jira at …"): a read of the same data an hour later is the same read;
+ *   - no text Claude wrote (a card's ask, a mention's gist, a digest's decisions, a sprint summary): Claude words the same facts a
+ *     little differently each time, and a new wording is not new data.
+ * So two reads have the same fingerprint exactly when the tool said the same thing. `n` is how many records the hash covers.
+ *
+ * Calendar, Jira and work assigned to you store a whole snapshot each read, so a read is 'changed' when its hash differs (a meeting
+ * that was cancelled is a change). Your tools store only what is new since the last read, so an empty read after a full one is not
+ * a change: their fingerprint also carries `keys`, one short hash per item, and a read is 'changed' only when it holds a key the
+ * last read did not.
+ *
+ * Per source, the facts are:
+ *   calendar  each current event (the folded ledger): id, start, end, title, attendees
+ *   jira      each initiative's and the sprints' snapshot: every ticket's key, status, category, sprint, subtasks, points, flag
+ *   mywork    each card: key, title, status, category, priority, due, estimate, blocks, from
+ *   tools     each tool's stored read: its state, and per item its id, link, who, when, where and the mention flags
+ * The tracker is read by code from files in the repository, so it has no fingerprint here.
+ *
+ * Pure apart from reading the stores. It never writes.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const SOURCES = Object.freeze(['calendar', 'jira', 'mywork', 'tools']);
+const SHORT = 16;   // hex digits kept: enough to tell two reads apart, short enough for a log line
+
+const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
+/** The same JSON text for the same value, whatever order its keys were written in. Undefined and null fields are left out. */
+function canon(v) {
+  if (Array.isArray(v)) return '[' + v.map(canon).join(',') + ']';
+  if (isObj(v)) return '{' + Object.keys(v).sort().filter((k) => v[k] !== undefined && v[k] !== null).map((k) => JSON.stringify(k) + ':' + canon(v[k])).join(',') + '}';
+  return JSON.stringify(v === undefined ? null : v);
+}
+const pick = (o, keys) => { const out = {}; for (const k of keys) if (o && o[k] !== undefined && o[k] !== null && o[k] !== '') out[k] = o[k]; return out; };
+const byKey = (k) => (a, b) => String(a[k] || '').localeCompare(String(b[k] || ''));
+const hashOf = (records) => ({ hash: crypto.createHash('sha256').update(canon(records)).digest('hex').slice(0, SHORT), n: records.length });
+
+/* ── per source ── */
+function calendar(runtime) {
+  const f = path.join(runtime, 'calendar-import', 'events.jsonl');
+  if (!fs.existsSync(f)) return null;
+  let CI;
+  try { CI = require(require('./repo-script.js').repoScript('calendar-import.js')); } catch { return null; }
+  let events = [];
+  try { events = CI.foldEvents(CI.readLines(f)); } catch { return null; }
+  return hashOf(events.map((e) => pick(e, ['id', 'at', 'end', 'title', 'attendees'])).sort(byKey('id')));
+}
+const SNAPSHOT_JSON = /```json\n([\s\S]*?)\n```/;
+function jira(dir) {
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.md') && !n.endsWith('-tickets.md') && n !== '_sprint-notes.md').sort(); } catch { return null; }
+  if (!names.length) return null;
+  const out = [];
+  for (const n of names) {
+    let text = ''; try { text = fs.readFileSync(path.join(dir, n), 'utf8'); } catch { continue; }
+    const m = SNAPSHOT_JSON.exec(text); if (!m) continue;
+    let data = null; try { data = JSON.parse(m[1]); } catch { continue; }
+    const tickets = (Array.isArray(data && data.tickets) ? data.tickets : [])
+      .map((t) => ({ ...pick(t, ['key', 'status', 'category', 'type', 'parent', 'points', 'resolved', 'flagged', 'stale']),
+        ...(t.sprint ? { sprint: pick(t.sprint, ['id', 'name', 'state', 'start', 'end', 'completed']) } : {}),
+        ...(t.subtasks ? { subtasks: pick(t.subtasks, ['done', 'total']) } : {}) }))
+      .sort(byKey('key'));
+    out.push({ file: n.slice(0, -3), tickets });
+  }
+  return out.length ? hashOf(out) : null;
+}
+function mywork(runtime) {
+  const r = readJson(path.join(runtime, 'my-work', 'read.json'));
+  if (!r || !Array.isArray(r.items)) return null;
+  return hashOf(r.items.map((x) => pick(x, ['key', 'title', 'status', 'category', 'priority', 'due', 'estimate', 'blocks', 'from'])).sort(byKey('key')));
+}
+const TOOL_ITEM = ['id', 'link', 'who', 'at', 'where', 'due', 'mention', 'via', 'reply_needed', 'replied', 'broadcast', 'bot', 'conversation'];
+const MAX_KEYS = 600;   // 10 tools of at most 60 items each
+const keyOf = (v) => crypto.createHash('sha256').update(canon(v)).digest('hex').slice(0, 12);
+function tools(runtime) {
+  const dir = path.join(runtime, 'source-reads');
+  let names = [];
+  try { names = fs.readdirSync(dir).filter((n) => n.endsWith('.json')).sort(); } catch { return null; }
+  const out = []; const keys = new Set();
+  for (const n of names) {
+    const r = readJson(path.join(dir, n));
+    if (!isObj(r) || !r.source) continue;
+    out.push({ source: r.source, state: r.state,
+      items: (Array.isArray(r.items) ? r.items : []).map((x) => pick(x, TOOL_ITEM)).sort(byKey('id')),
+      digests: (Array.isArray(r.digests) ? r.digests : []).map((d) => pick(d, ['name', 'link'])).sort(byKey('name')),
+      places: (Array.isArray(r.places) ? r.places : []).map((p) => pick(p, ['name', 'link'])).sort(byKey('name')) });
+    const o = out[out.length - 1];
+    for (const x of o.items) keys.add(keyOf({ s: o.source, x }));
+    for (const d of o.digests) keys.add(keyOf({ s: o.source, d }));
+    keys.add(keyOf({ s: o.source, state: o.state }));
+  }
+  return out.length ? { ...hashOf(out), keys: [...keys].sort().slice(0, MAX_KEYS) } : null;
+}
+
+/** The fingerprint of what PMOS stores for `source` now, or null (nothing stored, or a source with no fingerprint). */
+function of(source, dirs = {}) {
+  try {
+    if (source === 'calendar') return dirs.runtime ? calendar(dirs.runtime) : null;
+    if (source === 'jira') return dirs.jira ? jira(dirs.jira) : null;
+    if (source === 'mywork') return dirs.runtime ? mywork(dirs.runtime) : null;
+    if (source === 'tools') return dirs.runtime ? tools(dirs.runtime) : null;
+  } catch { /* a store that cannot be read has no fingerprint */ }
+  return null;
+}
+/** 'first' when there was no fingerprint before, 'same' or 'changed' after; null when there is none now. */
+function compare(prev, fp) {
+  if (!fp || !fp.hash) return null;
+  const p = typeof prev === 'string' ? { hash: prev } : prev;
+  if (!p || !p.hash) return 'first';
+  if (p.hash === fp.hash) return 'same';
+  if (Array.isArray(fp.keys) && Array.isArray(p.keys)) { const had = new Set(p.keys); return fp.keys.some((k) => !had.has(k)) ? 'changed' : 'same'; }
+  return 'changed';
+}
+/** What the engine keeps between reads: the hash, and the item keys of a source that has them. */
+const keep = (fp) => (fp ? { hash: fp.hash, ...(Array.isArray(fp.keys) ? { keys: fp.keys } : {}) } : null);
+
+module.exports = { SOURCES, SHORT, of, compare, keep, canon };

package/workspace/lib/refresh-cli.js

@@ -0,0 +1,75 @@
+'use strict';
+/* refresh-cli.js — `pmos refresh …`: ask the tool first, read in full only when something changed (smart refresh, step 2).
+ *   pmos refresh since <source> [--json]                       ask first or read in full, and the time to ask "what changed since"
+ *   pmos refresh same <source> [--only <tool,…>] [--json]      the tool said nothing changed: keep the stored read, move its read time to now
+ * <source> is calendar, jira, mywork or tools. The read skills (calendar-sync, jira-sync, my-work-read, sources-read) run these.
+ * This command calls no tool. The rules are in lib/refresh-probe.js.
+ */
+const path = require('path');
+const { execFileSync } = require('child_process');
+const stateRoot = require('./state-root');
+const P = require('./refresh-probe.js');
+
+const COMMANDS = { refresh: ['since', 'same'] };
+const USAGE = [
+  'usage: pmos refresh since|same <source> — ask the tool first, read in full only when something changed',
+  '  pmos refresh since <source>                   says "ask" (ask the tool what changed since the last read) or "full" (read in full), and why',
+  '  pmos refresh same <source> [--only <tools>]   the tool said nothing changed: keep the stored read and move its read time to now',
+  '  <source>: ' + P.SOURCES.join(', ') + '. --only (tools only): the tools to confirm, comma-separated, for example slack,mail',
+  '  every command: [--json] [--root <dir>]',
+  'This command never calls a tool. A full read is due once a day, and `same` refuses then.',
+];
+
+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 (key === 'json' || key === 'help') out[key] = true;
+    else if (eq > 0) out[key] = t.slice(eq + 1);
+    else if (argv[i + 1] !== undefined) out[key] = argv[++i];
+    else out[key] = '';
+  }
+  return out;
+}
+function repoRoot(cwd) {
+  try { return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || cwd; }
+  catch { return cwd; }
+}
+
+function run(argv, { say = console.log, env = process.env, stateDir, cwd = process.cwd(), now = () => Date.now(), jiraDir } = {}) {
+  const a = parseArgs(argv.slice(1));
+  const sub = a._[0]; const source = a._[1];
+  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.refresh.includes(sub)) { say(`✗ pmos refresh ${sub} is not a command`); USAGE.forEach((l) => say(l)); return 2; }
+  if (!P.SOURCES.includes(source)) { out({ ok: false, error: `source must be one of ${P.SOURCES.join(', ')}` }, `✗ name the source: ${P.SOURCES.join(', ')}`); return 2; }
+  if (a.only !== undefined && source !== 'tools') { out({ ok: false, error: '--only is for tools' }, '✗ --only is for tools'); return 2; }
+  const rt = stateDir || stateRoot.defaultRoot({ env });
+  const dirs = {};
+  if (source === 'jira') {
+    if (jiraDir) dirs.jira = jiraDir;
+    else { const root = a.root ? path.resolve(cwd, String(a.root)) : repoRoot(cwd); dirs.jira = require('./jira-tickets.js').jiraDir(root); }
+  }
+  const t = now();
+
+  if (sub === 'since') {
+    const s = P.since(rt, source, dirs, t);
+    if (a.json) { say(JSON.stringify(s)); return 0; }
+    say(`${source} · ${s.verdict === 'ask' ? 'ask first' : 'read in full'}: ${s.why}`);
+    say(`  last read ${s.last_read_at || 'never'} · last full read ${s.full_at || 'none recorded'}`);
+    for (const [k, v] of Object.entries(s.tools || {})) say(`  ${k.padEnd(11)} ${v.state} ${v.read_at}`);
+    if (s.verdict === 'ask') say(`  Ask the tool what changed since ${s.last_read_at} (the last ${s.minutes} minutes). Nothing changed: run \`pmos refresh same ${source}\` and stop. Anything changed: read in full.`);
+    return 0;
+  }
+  // same
+  const only = a.only ? String(a.only).split(',').map((x) => x.trim()).filter(Boolean) : null;
+  const r = P.same(rt, source, dirs, t, { only });
+  if (!r.ok) { out(r, `✗ ${r.error}`); return 1; }
+  out(r, `kept the stored read of ${source} (${r.stamped.join(', ')}) as unchanged, checked at ${r.same_at}`);
+  return 0;
+}
+
+module.exports = { run, COMMANDS, USAGE };

package/workspace/lib/refresh-probe.js

@@ -0,0 +1,110 @@
+'use strict';
+/* refresh-probe.js — ask the tool first, read in full only when something changed (smart refresh, step 2).
+ *
+ *   since(runtime, source, dirs, now)        → { source, last_read_at, full_at, verdict: 'ask'|'full', why, minutes?, tools? }
+ *   same(runtime, source, dirs, now, {only}) → { ok, stamped: [what] } | { ok: false, error }
+ *   askedSince(runtime, source, ms)          → true when `same` confirmed this source at or after `ms`
+ *   SOURCES · FULL_MS · FILE
+ *     dirs { jira: <repository state>/tracker/jira }   (Jira only)
+ *
+ * THE FLOW. A read skill runs `pmos refresh since <source>` first. With verdict 'ask' it asks the tool one cheap question: what changed
+ * since `last_read_at` (an updated-since search, a newer-than filter). When the tool says nothing changed, the skill runs
+ * `pmos refresh same <source>` and stops: the stored read is kept as it is, and only its read time moves to now, so Sources, the
+ * Briefing and the freshness rows know it was checked. When anything changed, or the verdict is 'full', the skill does its full read.
+ *
+ * THE SAFETY RULE. A question about changes can miss something (a meeting that moved into the 14 days, a ticket that left a search).
+ * So a full read is due when the last full read is older than FULL_MS, or there is none, and `same` refuses then: the skill reads
+ * in full. The last full read is `full_at` in <runtime>/refresh-state.json, which lib/refresh-run.js writes when a read ends that was
+ * not confirmed with `same`.
+ *
+ * FILES. `same` writes the read time of the stored read (calendar-import/read.json, my-work/read.json, source-reads/<tool>.json, the
+ * modified time of the Jira snapshots) and one line per source in <runtime>/refresh-probe.json: { <source>: { same_at, only? } }.
+ * It never changes what a read holds.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const SOURCES = Object.freeze(['calendar', 'jira', 'mywork', 'tools']);
+const FULL_MS = 24 * 3600 * 1000;
+const FILE = 'refresh-probe.json';
+const TOOLS = Object.freeze(['mail', 'slack', 'wispr', 'jira', 'confluence', 'github', 'drive', 'figma', 'website', 'web']);
+
+const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
+function writeJson(f, v) {
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  const tmp = `${f}.${process.pid}.tmp`; fs.writeFileSync(tmp, JSON.stringify(v) + '\n'); fs.renameSync(tmp, f);
+}
+const iso = (ms) => (ms ? new Date(ms).toISOString() : null);
+const ms = (s) => { const t = Date.parse(s || ''); return Number.isFinite(t) ? t : 0; };
+
+const calFile = (rt) => path.join(rt, 'calendar-import', 'read.json');
+const workFile = (rt) => path.join(rt, 'my-work', 'read.json');
+const toolFile = (rt, t) => path.join(rt, 'source-reads', t + '.json');
+function jiraFiles(dir) {
+  try { return fs.readdirSync(dir).filter((n) => n.endsWith('.md') && !n.endsWith('-tickets.md')).map((n) => path.join(dir, n)); } catch { return []; }
+}
+const mtime = (f) => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } };
+
+/** When each stored read was last read (or confirmed), in ms. Tools answer per tool. */
+function lastRead(rt, source, dirs = {}) {
+  if (source === 'calendar') { const r = readJson(calFile(rt)); return { at: r ? ms(r.fetched_at) : 0 }; }
+  if (source === 'mywork') { const r = readJson(workFile(rt)); return { at: r ? ms(r.read_at) : 0 }; }
+  if (source === 'jira') { const fl = dirs.jira ? jiraFiles(dirs.jira) : []; return { at: fl.reduce((m, f) => Math.max(m, mtime(f)), 0), n: fl.length }; }
+  const per = {};
+  for (const t of TOOLS) { const r = readJson(toolFile(rt, t)); if (r && r.source === t && r.read_at) per[t] = { at: ms(r.read_at), state: r.state }; }
+  const ats = Object.values(per).map((x) => x.at).filter(Boolean);
+  return { at: ats.length ? Math.min(...ats) : 0, per };
+}
+const fullAt = (rt) => (source) => { const st = readJson(path.join(rt, 'refresh-state.json')) || {}; return Number(st[source] && st[source].full_at) || 0; };
+
+/** Should the skill ask the tool first, or read in full? */
+function since(rt, source, dirs = {}, now = Date.now()) {
+  if (!SOURCES.includes(source)) return { ok: false, error: `source must be one of ${SOURCES.join(', ')}` };
+  const last = lastRead(rt, source, dirs);
+  const full = fullAt(rt)(source);
+  let verdict = 'ask'; let why = 'the last full read is younger than 24 hours: ask the tool what changed since the last read';
+  if (!last.at) { verdict = 'full'; why = 'nothing is stored yet'; }
+  else if (!full) { verdict = 'full'; why = 'no full read is recorded yet'; }
+  else if (now - full > FULL_MS) { verdict = 'full'; why = 'the last full read is older than 24 hours'; }
+  // the question's window in whole minutes, with 5 minutes to spare, for a search that takes "updated in the last N minutes"
+  const out = { ok: true, source, last_read_at: iso(last.at), full_at: iso(full), verdict, why, ...(last.at ? { minutes: Math.max(1, Math.ceil((now - last.at) / 60000)) + 5 } : {}) };
+  if (last.per) out.tools = Object.fromEntries(Object.entries(last.per).map(([k, v]) => [k, { read_at: iso(v.at), state: v.state }]));
+  return out;
+}
+
+/** Confirm the stored read of `source` as unchanged: its read time moves to now, what it holds stays. */
+function same(rt, source, dirs = {}, now = Date.now(), { only } = {}) {
+  const s = since(rt, source, dirs, now);
+  if (!s.ok) return s;
+  if (s.verdict === 'full') return { ok: false, error: `a full read of ${source} is due: ${s.why}. Read it in full; nothing was changed` };
+  const at = new Date(now).toISOString();
+  const stamped = [];
+  if (source === 'calendar') {
+    const r = readJson(calFile(rt)); writeJson(calFile(rt), { ...r, fetched_at: at, confirmed: true }); stamped.push('calendar');
+  } else if (source === 'mywork') {
+    const r = readJson(workFile(rt)); writeJson(workFile(rt), { ...r, read_at: at }); stamped.push('work assigned to you');
+  } else if (source === 'jira') {
+    const t = new Date(now);
+    for (const f of jiraFiles(dirs.jira)) { try { fs.utimesSync(f, t, t); stamped.push(path.basename(f, '.md')); } catch { /* a file that went away is not stamped */ } }
+  } else {
+    const want = only && only.length ? only : Object.keys(s.tools || {});
+    const bad = want.filter((x) => !TOOLS.includes(x));
+    if (bad.length) return { ok: false, error: `--only takes tools from ${TOOLS.join(', ')}; not ${bad.join(', ')}` };
+    const missing = want.filter((x) => !(s.tools || {})[x]);
+    if (missing.length) return { ok: false, error: `${missing.join(', ')} ${missing.length === 1 ? 'has' : 'have'} no stored read yet: read ${missing.length === 1 ? 'it' : 'them'} in full` };
+    for (const x of want) { const r = readJson(toolFile(rt, x)); writeJson(toolFile(rt, x), { ...r, read_at: at }); stamped.push(x); }
+  }
+  if (!stamped.length) return { ok: false, error: `no stored read of ${source} to confirm: read it in full` };
+  const pf = path.join(rt, FILE); const cur = readJson(pf) || {};
+  cur[source] = { same_at: at, ...(source === 'tools' && only && only.length ? { only: stamped } : {}) };
+  writeJson(pf, cur);
+  return { ok: true, source, same_at: at, stamped };
+}
+
+/** `same` confirmed this source at or after `t` (ms): the run that ends now asked first and did no full read. */
+function askedSince(rt, source, t) {
+  const p = readJson(path.join(rt, FILE)) || {};
+  return !!(p[source] && ms(p[source].same_at) >= t);
+}
+
+module.exports = { SOURCES, FULL_MS, FILE, TOOLS, since, same, askedSince, lastRead };

package/workspace/lib/refresh-run.js

@@ -20,20 +20,40 @@
  *   { stateDir, now?, homeWs(), proactive() → { quiet, dayCheck: { start, end, every } }, schedules: { read, write },
  *     startSkill(wsId, skill, name, origin) → { ok, session?, error? }, jobs: { [id]: (ws) → { ok, error? } },
  *     freshRows(ws) → [freshness row], copyPaths(id, ws) → [path], tell({ source, label, error, ws }), sessionAlive(id) → bool,
- *     setDayCheckEvery(every), setRepoWatch(on), warn(what, e), leadsDue?(ws) → number of popup leads due }
+ *     setDayCheckEvery(every), setRepoWatch(on), warn(what, e), leadsDue?(ws) → number of popup leads due,
+ *     readDirs?(ws) → { runtime, jira }   where the stored reads are, for their fingerprint (smart refresh step 1); by default the
+ *                                         state folder and the Jira folder copyPaths('jira') names }
+ * startSkill takes a list of skills for a shared session (smart refresh step 2): one session that reads several due sources.
+ *
+ * SMART REFRESH (steps 1 and 2). Each done read of a stored source gets a fingerprint of its facts (lib/read-fingerprint.js); the end
+ * line says whether it brought anything new (`change`) and whether it was a full read or only asked the tool first (`how`). The
+ * fingerprint and the time of the last full read are kept in the source's state (`fp`, `full_at`). When two or more tool sources are
+ * due at the same minute, one shared session reads them one after another (startSkill with a list), instead of one session each. A source of a
+ * shared session is done when its stored read is newer than the session's start, and failed when it is not.
  * Nothing here calls out of this machine: a skill source's run is the PM's own agent session, with the PM's connections.
  */
 const fs = require('fs');
 const path = require('path');
 const R = require('./refresh.js');
 const H = require('./source-heal.js');
+const FP = require('./read-fingerprint.js');
+const P = require('./refresh-probe.js');
 
 const PRUNE_EVERY_MS = 24 * 3600 * 1000;
 const LOST_MS = 6 * 3600 * 1000;   // a run with no live session and no end after this long is written as interrupted
 const ALL_MS = 3 * 3600 * 1000;    // a Refresh all that has not ended after this long is over: a new press starts a new one
 const DERIVED = Object.freeze(['leads', 'brief']);   // what Refresh all writes again after the sources, in this order
 const DERIVED_LIST = Object.freeze(['scan', 'coredocs', 'leads', 'brief']);   // what Sources lists as derived content: built from stored reads, never a tool
-const AUTH_RETRY_MS = 2 * 60 * 1000;   // a run that failed on Claude's sign-in is tried once more after this (the token is usually refreshed by then)
+const AUTH_RETRY_MS = 2 * 60 * 1000;
+/* The sources a session reads, from its origin: one for most, several for a shared session (`refresh:<id>+<id>…`, step 2). */
+const SHARED_RE = /^refresh:([a-z]+(?:\+[a-z]+)+)$/;
+function sourcesOfOrigin(origin, opts) {
+  const m = SHARED_RE.exec(String(origin || ''));
+  if (m) return [...new Set(m[1].split('+'))].filter((x) => R.BY_ID.has(x) && R.BY_ID.get(x).run === 'skill');
+  const one = R.sourceOfOrigin(origin, opts);
+  return one ? [one] : [];
+}
+const sharedOrigin = (ids) => 'refresh:' + ids.join('+');   // a run that failed on Claude's sign-in is tried once more after this (the token is usually refreshed by then)
 
 function create(host) {
   const now = () => (host.now ? host.now() : Date.now());
@@ -92,7 +112,8 @@ function create(host) {
       return 'ok';
     };
   }
-  const runningCount = (state) => Object.values(state).reduce((n, st) => n + Object.keys(openOf(st)).length, 0);
+  // sessions, not sources: a shared session that reads three sources is one run against the run limit
+  const runningCount = (state) => { const ids = new Set(); for (const st of Object.values(state)) for (const k of Object.keys(openOf(st))) ids.add(k); return ids.size; };
   function snapshot(id, set, state, t) {
     const src = R.BY_ID.get(id); if (!src || !src.uses.length) return [];
     const f = log(); const is = inputStateFn(set, state, t);
@@ -103,8 +124,12 @@ function create(host) {
   const skillOfSchedule = (id) => { try { const x = host.schedules.read().find((y) => y.id === id); return x ? x.skill : null; } catch { return null; } };
   function started(s) {
     if (!s) return;
-    const id = R.sourceOfOrigin(s.origin, { skillOfSchedule });
-    if (!id) return;
+    const ids = sourcesOfOrigin(s.origin, { skillOfSchedule });
+    if (!ids.length) return;
+    for (const id of ids) startedOne(s, id, ids.length > 1 ? ids : null);
+    if (s.state === 'exited') ended(s);
+  }
+  function startedOne(s, id, shared) {
     const t = now();
     const set = settings(); const state = R.readState(dir);
     const ex = expect.get(id) || {}; expect.delete(id);
@@ -115,15 +140,37 @@ function create(host) {
     state[id] = { ...st, open: { ...openOf(st), [s.id]: { run, at: t, trigger } }, started_at: t, trigger, waiting_since: null, waiting_for: [], pending: null };
     if (ex.slot != null) state[id].last_slot = ex.slot;
     R.writeState(dir, state);
-    R.append(dir, { source: id, ws: s.ws || null, ev: 'start', run, trigger, session: s.id, inputs, ...(ex.note ? { note: ex.note } : {}) }, t);
-    if (s.state === 'exited') ended(s);
+    R.append(dir, { source: id, ws: s.ws || null, ev: 'start', run, trigger, session: s.id, inputs, ...(ex.note ? { note: ex.note } : {}), ...(shared ? { shared } : {}) }, t);
   }
   /** End the open run of session `s`. `over` sets the result for a run whose session has no outcome of its own. */
   function ended(s, over) {
     if (!s) return;
+    const now0 = R.readState(dir);
+    const ids = Object.keys(now0).filter((k) => openOf(now0[k])[s.id]);
+    if (!ids.length) return;
+    const shared = ids.length > 1;
+    let readAfter = false;
+    for (const id of ids) { if (endedOne(s, id, over, shared) && R.BY_ID.get(id).group === 'tools') readAfter = true; }
+    // popup context slice 3b: a read of the tools that ends well is followed by one leads session, once no other read is going
+    if (readAfter) afterRead(s.ws || null);
+  }
+  /** Where the stored reads are: the state folder, and the Jira folder of the workspace (the one copyPaths keeps a copy of). */
+  function readDirs(ws) {
+    if (host.readDirs) return host.readDirs(ws) || {};
+    let j = []; try { j = host.copyPaths('jira', ws) || []; } catch { j = []; }
+    return { runtime: dir, jira: j[0] || null };
+  }
+  /** The stored read of `id` is newer than `since` (ms): the shared session read it. From the source's lib/freshness.js row. */
+  function readSince(id, ws, since) {
+    const src = R.BY_ID.get(id); if (!src || !src.fresh) return false;
+    let rowsNow = []; try { rowsNow = host.freshRows(ws) || []; } catch { rowsNow = []; }
+    const r = rowsNow.find((x) => x.id === src.fresh);
+    const at = r && r.as_of ? Date.parse(r.as_of) || 0 : 0;
+    return at >= since - 1000;
+  }
+  /** End the open run of session `s` for source `id`. → true when the run is done. */
+  function endedOne(s, id, over, shared) {
     const state = R.readState(dir);
-    const id = Object.keys(state).find((k) => openOf(state[k])[s.id]);
-    if (!id) return;
     const t = now();
     const st = state[id]; const o = openOf(st)[s.id];
     let result; let got = null; let error = null;
@@ -131,6 +178,11 @@ function create(host) {
     else if (s.outcome) { result = s.outcome.ok ? 'done' : /Stopped by you/.test(s.outcome.why || '') ? 'interrupted' : 'failed'; got = s.outcome.headline || null; error = s.outcome.ok ? null : s.outcome.why; }
     else if (id === 'brief') { result = 'failed'; error = 'The session ended without submitting a brief' + (s.note ? ` (${s.note})` : '') + '.'; }
     else { result = /code 0\)$/.test(s.note || '') ? 'done' : 'failed'; error = result === 'failed' ? s.note || 'the session ended' : null; }
+    // a shared session has one outcome for several sources: each source is done only when its stored read is newer than the start
+    if (shared && !over && result !== 'interrupted') {
+      if (readSince(id, s.ws || null, o.at)) { result = 'done'; error = null; }
+      else { result = 'failed'; got = null; error = 'The shared refresh session did not save a new read of it' + (error ? ` (${error})` : '') + '.'; }
+    }
     const rest = { ...openOf(st) }; delete rest[s.id];
     const rules = settings().rules;
     let copy = null;
@@ -138,6 +190,19 @@ function create(host) {
     if (result === 'done' && src && src.copy) { try { copy = R.keepCopy(dir, id, host.copyPaths(id, s.ws), t); } catch (e) { warn('refresh copy', e); } }
     const next = { ...st, open: rest, last_end: t, last_result: result };
     if (result === 'done') { next.retry_at = null; next.retried = false; next.auth_retried = false; }
+    // smart refresh step 1: what this read brought, measured on the stored facts; no change shows on any page
+    let measured = null;
+    if (result === 'done' && src && FP.SOURCES.includes(id)) {
+      try {
+        const dirs = readDirs(s.ws || null);
+        const fp = FP.of(id, dirs);
+        const change = FP.compare(st.fp, fp);
+        const asked = P.askedSince(dirs.runtime || dir, id, o.at);
+        if (fp) { next.fp = FP.keep(fp); measured = { change, how: asked ? 'asked' : 'full', fp: fp.hash }; }
+        else measured = { how: asked ? 'asked' : 'full' };
+        if (!asked) next.full_at = t;
+      } catch (e) { warn('read fingerprint', e); }
+    }
     // harness-health: a failed sign-in is often a token being refreshed by another run at the same moment (2026-10-21 08:34,
     // four runs of Refresh all failed in 2 s, and Claude was signed in a minute later). Try once more, whatever started it.
     const authFail = result === 'failed' && !!(s.outcome && s.outcome.auth);
@@ -148,13 +213,12 @@ function create(host) {
     else if (result === 'failed' && o.trigger === 'retry') next.retry_at = null;
     state[id] = next;
     R.writeState(dir, state);
-    R.append(dir, { source: id, ws: s.ws || null, ev: 'end', run: o.run, result, took_ms: t - o.at, got, error, ...(copy ? { copy } : {}) }, t);
-    // popup context slice 3b: a read of the tools that ends well is followed by one leads session, once no other read is going
-    if (result === 'done' && src && src.group === 'tools') afterRead(s.ws || null);
+    R.append(dir, { source: id, ws: s.ws || null, ev: 'end', run: o.run, result, took_ms: t - o.at, got, error, ...(copy ? { copy } : {}), ...(measured || {}) }, t);
     // a source under repair is told once by the repair, when the PM must act (lib/source-heal.js), not on each failed read
     if (result === 'failed' && scheduled && rules.tell === 'brief' && !next.retry_at && !healing(id)) {
       try { host.tell({ source: id, label: src ? src.label : id, error: error || 'it failed', ws: s.ws || null }); } catch (e) { warn('refresh failure note', e); }
     }
+    return result === 'done';
   }
   /** One leads session after the reads (PM pick, 2026-10-21), when the leads are on and a popup's lead is due. It waits for the
    * reads still going (runNow), and a second read that ends joins the one that is waiting or running. */
@@ -201,6 +265,7 @@ function create(host) {
     }
     if (changed) R.writeState(dir, state);
     const first = !tick.seen; tick.seen = true;
+    shareDue(t, set, rules, first);
     for (const src of R.SOURCES.filter((x) => x.run === 'skill')) {
       const cur = R.readState(dir);
       const st = { ...(cur[src.id] || {}), running: running(cur[src.id]) };
@@ -226,7 +291,7 @@ function create(host) {
         const f = log();
         const lastDone = (id) => { const runs = f.runs(id, 20) || []; const l = runs.find((r) => r.result === 'done'); return l ? Date.parse(l.end_at || l.start_at) || 0 : 0; };
         const first = R.refreshFirst(src, { now: t, settings: set, inputState: inputStateFn(set, cur, t), lastDone });
-        const begun = first.filter((id) => { const x = R.BY_ID.get(id); return start(x, (set.sources[id] && set.sources[id].ws) || ws, { trigger: d.trigger, note: 'Refreshed first, before ' + src.label }).ok; });
+        const begun = startMany(first.map((id) => R.BY_ID.get(id)), (id) => (set.sources[id] && set.sources[id].ws) || ws, { trigger: d.trigger, note: 'Refreshed first, before ' + src.label });
         if (begun.length) {
           const nx = R.readState(dir);
           nx[src.id] = { ...(nx[src.id] || {}), waiting_since: t, waiting_for: begun, waiting_why: null };
@@ -268,6 +333,60 @@ function create(host) {
     }
     if (JSON.stringify(heal) !== before) writeHeal(heal);
   }
+  /* ── smart refresh step 2: due sources share one session ──
+   * The tool sources (calendar, Jira, work assigned to you, your tools) that are due at the same minute, on their schedule, a catch-up
+   * or a retry, start as ONE session per workspace: one Claude start instead of up to four. A press, a repair and Refresh all keep their
+   * own sessions. */
+  const AUTO = new Set(['schedule', 'catch-up', 'retry']);
+  function shareDue(t, set, rules, first) {
+    const cur = R.readState(dir);
+    if (runningCount(cur) >= Number(rules.max || 3)) return;
+    const due = [];
+    for (const src of R.SOURCES.filter((x) => x.run === 'skill' && x.group === 'tools')) {
+      const st = { ...(cur[src.id] || {}), running: running(cur[src.id]) };
+      const d = R.decide(src, st, { now: t, settings: set, rules, win: win(), quiet: quiet(), runningCount: runningCount(cur), inputState: inputStateFn(set, cur, t), first });
+      if (d.act === 'start' && AUTO.has(d.trigger) && !d.pressed) due.push({ src, d, ws: (set.sources[src.id] && set.sources[src.id].ws) || host.homeWs() });
+    }
+    const byWs = new Map();
+    for (const x of due) { const a = byWs.get(x.ws) || []; a.push(x); byWs.set(x.ws, a); }
+    for (const [ws, list] of byWs) {
+      if (list.length < 2) continue;   // one due source starts alone in the tick below
+      startTogether(list.map((x) => ({ src: x.src, trigger: x.d.trigger, slot: x.d.slot, note: x.d.note })), ws);
+    }
+  }
+  /** Start `srcs` (sources) for a scheduled run: in one shared session when two or more share a workspace and the host can, else each
+   *  alone. `wsOf(id)` names each one's workspace. → [id] that started */
+  function startMany(srcs, wsOf, opts) {
+    const list = srcs.filter(Boolean);
+    if (list.length < 2) return list.filter((x) => start(x, wsOf(x.id), opts).ok).map((x) => x.id);
+    const byWs = new Map();
+    for (const x of list) { const w = wsOf(x.id); const a = byWs.get(w) || []; a.push(x); byWs.set(w, a); }
+    const begun = [];
+    for (const [w, a] of byWs) {
+      if (a.length === 1) { if (start(a[0], w, opts).ok) begun.push(a[0].id); continue; }
+      if (startTogether(a.map((src) => ({ src, ...opts })), w).ok) begun.push(...a.map((x) => x.id));
+    }
+    return begun;
+  }
+  /** One shared session for `items` ([{ src, trigger, slot, note }]) in workspace `ws`. A session that does not start is written as a
+   *  failed run of each source, the same as start() does for one. */
+  function startTogether(items, ws) {
+    const ids = items.map((x) => x.src.id);
+    for (const x of items) expect.set(x.src.id, { trigger: x.trigger, slot: x.slot, note: x.note });
+    let r;
+    try { r = host.startSkill(ws, items.map((x) => x.src.skill), items.map((x) => x.src.label).join(', ') + ' · refresh', sharedOrigin(ids)); }
+    catch (e) { r = { ok: false, error: String((e && e.message) || e) }; }
+    for (const x of items) {
+      if (!expect.has(x.src.id)) continue;
+      expect.delete(x.src.id);
+      const t = now(); const run = R.newRun(x.src.id, t); const cur = R.readState(dir);
+      cur[x.src.id] = { ...(cur[x.src.id] || {}), last_slot: x.slot != null ? x.slot : (cur[x.src.id] || {}).last_slot, waiting_since: null, waiting_for: [], pending: null, last_result: 'failed' };
+      R.writeState(dir, cur);
+      R.append(dir, { source: x.src.id, ws, ev: 'start', run, trigger: x.trigger, shared: ids }, t);
+      R.append(dir, { source: x.src.id, ws, ev: 'end', run, result: 'failed', took_ms: 0, error: (r && r.error) || 'could not start' }, t);
+    }
+    return r || { ok: false, error: 'could not start' };
+  }
   /** What /api/sources shows per source: the repair view, keyed by the lib/freshness.js id. */
   const healView = () => H.viewAll(dir);
   function start(src, ws, { trigger, slot, note }) {
@@ -456,4 +575,4 @@ function create(host) {
   return { heal: healView, tick, started, ended, briefDone, codeRun, jobGate, runNow, refreshAll, allState, derived, setSource, setRules, ensureOn, rows, settings, log, scheduleOfSkill, managedSkill: (skill) => R.SKILL_OF.get(skill) || null };
 }
 
-module.exports = { create };
+module.exports = { create, sourcesOfOrigin, sharedOrigin };