create-pmos 0.241.0 → 0.243.0

package/workspace/lib/meeting-material.js

@@ -0,0 +1,151 @@
+'use strict';
+/* lib/meeting-material.js — the material the PM linked to a meeting (initiative meeting-material-replay, part 1).
+ *
+ *   keyOf(event)                          → 's:<series>' or 't:<normalized title>' (calendar-memory.js seriesKey), as lib/calendar-links.js
+ *   append(runtimeDir, body, by)          → { ok, items } | { ok: false, error }   op 'add' (the default) or 'remove'
+ *   forMeeting(runtimeDir, event)         → [item]   the series items of the meeting and the items for this one meeting, in the order they were added
+ *   read(runtimeDir)                      → Map<identity, row>   the rows that hold now (a removed item is gone)
+ *   check(body)                           → null | the reason the body is refused
+ *   classifyUrl(url)                      → { kind: slides|gdoc|conf|link, url } | null
+ *
+ * The calendar is read-only (PMOS never edits an invite), so the material lives beside it: <runtime>/meeting-material.jsonl, append-only.
+ * A row: { at, by, key, series, event?, scope: 'meeting'|'series', item: { kind, ref?, title, url?, ws? }, topic?, present, removed? }.
+ * An item is named by its key, its event ("this meeting"; empty for the series) and its kind and ref or url. The last row of a name wins,
+ * and a row with removed: true takes the item off. Nothing is ever rewritten.
+ *
+ * Kinds. PMOS items name a file of the repository by ref: pmos-doc (a document), pmos-deck (a report cycle that is a slide deck), report
+ * (any other report cycle). Links name an address: slides, gdoc, conf, link. The server decides a link's kind from its address. */
+const fs = require('fs');
+const path = require('path');
+const calMem = require('./calendar-memory.js');
+
+const FILE = 'meeting-material.jsonl';
+const PMOS_KINDS = ['pmos-deck', 'pmos-doc', 'report'];
+const LINK_KINDS = ['slides', 'gdoc', 'conf', 'link'];
+const KINDS = [...PMOS_KINDS, ...LINK_KINDS];
+const SCOPES = ['meeting', 'series'];
+const OPS = ['add', 'remove'];
+const MAX_ITEMS = 60;
+const str = (v) => (typeof v === 'string' ? v.trim() : '');
+
+const keyOf = (e) => calMem.seriesKey({ series: e && e.series ? String(e.series) : null, title: e && e.title });
+const fileOf = (runtimeDir) => path.join(runtimeDir, FILE);
+
+/** What an address is. Only https addresses are kept; the server and the page agree on the kind. */
+function classifyUrl(raw) {
+  const s = str(raw);
+  if (!s || s.length > 1000 || /\s/.test(s)) return null;
+  let u; try { u = new URL(/^[a-z][a-z0-9+.-]*:/i.test(s) ? s : 'https://' + s); } catch { return null; }
+  if (u.protocol !== 'https:' || !u.hostname.includes('.')) return null;
+  if (u.hostname === 'docs.google.com' && /^\/presentation\/d\//.test(u.pathname)) return { kind: 'slides', url: u.href };
+  if (u.hostname === 'docs.google.com' && /^\/document\/d\//.test(u.pathname)) return { kind: 'gdoc', url: u.href };
+  if (/\.atlassian\.net$/.test(u.hostname) && u.pathname.startsWith('/wiki')) return { kind: 'conf', url: u.href };
+  return { kind: 'link', url: u.href };
+}
+
+/** A repository-relative file path: no leading slash, no "..", no backslash, no control character. */
+const refOk = (r) => typeof r === 'string' && r.length > 0 && r.length <= 300 && !r.startsWith('/') && !r.includes('\\') && !/(^|\/)\.\.(\/|$)/.test(r) && !/[\u0000-\u001f]/.test(r);
+
+/** The name of an item inside one meeting or series. */
+const idOf = (item) => item.kind + '|' + (PMOS_KINDS.includes(item.kind) ? item.ref : item.url);
+const identity = (row) => [row.key, row.scope === 'series' ? '' : row.event || '', idOf(row.item)].join('\u0000');
+
+/** The reason a POST body is refused, or null.
+ *  body: { op?: 'add'|'remove', event: { id?, title, series? }, scope: 'meeting'|'series', item: { kind, ref | url, title?, ws? }, topic?, present? } */
+function check(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return 'the body must be a JSON object';
+  if (body.op != null && !OPS.includes(body.op)) return 'op is one of ' + OPS.join(', ');
+  const e = body.event;
+  if (!e || typeof e !== 'object' || !str(e.title) || str(e.title).length > 300) return 'event.title is required (one line, at most 300 characters)';
+  if (e.series != null && (typeof e.series !== 'string' || e.series.length > 300)) return 'event.series must be text';
+  if (e.id != null && (typeof e.id !== 'string' || e.id.length > 120)) return 'event.id must be text';
+  const scope = body.scope == null ? 'meeting' : body.scope;
+  if (!SCOPES.includes(scope)) return 'scope is one of ' + SCOPES.join(', ');
+  if (scope === 'meeting' && !str(e.id)) return 'a link for one meeting needs event.id';
+  const it = body.item;
+  if (!it || typeof it !== 'object') return 'item is required';
+  if (PMOS_KINDS.includes(it.kind)) { if (!refOk(it.ref)) return 'a PMOS item needs ref, the path of the file in the repository'; }
+  else if (it.kind == null || LINK_KINDS.includes(it.kind)) { if (!classifyUrl(it.url)) return 'a link must be an https address'; }
+  else return 'item.kind is one of ' + KINDS.join(', ');
+  if (it.title != null && (typeof it.title !== 'string' || it.title.length > 300 || /[\r\n]/.test(it.title))) return 'item.title is one line of at most 300 characters';
+  if (it.ws != null && (typeof it.ws !== 'string' || it.ws.length > 120)) return 'item.ws must be text';
+  if (body.topic != null && (typeof body.topic !== 'string' || body.topic.length > 160 || /[\r\n]/.test(body.topic))) return 'topic is one line of at most 160 characters';
+  if (body.present != null && typeof body.present !== 'boolean') return 'present must be true or false';
+  return null;
+}
+
+/** The item as it is kept: the kind a link has, its address in full, a title. */
+function cleanItem(it) {
+  if (PMOS_KINDS.includes(it.kind)) return { kind: it.kind, ref: it.ref, title: str(it.title) || it.ref, ...(str(it.ws) ? { ws: str(it.ws) } : {}) };
+  const c = classifyUrl(it.url);
+  return { kind: c.kind, url: c.url, title: str(it.title) || c.url };
+}
+
+function lines(runtimeDir) {
+  if (!runtimeDir) return [];
+  let text = '';
+  try { text = fs.readFileSync(fileOf(runtimeDir), 'utf8'); } catch { return []; }
+  const out = [];
+  for (const l of text.split('\n')) {
+    if (!l.trim()) continue;
+    let x; try { x = JSON.parse(l); } catch { continue; }
+    if (!x || typeof x.key !== 'string' || !SCOPES.includes(x.scope) || !x.item || !KINDS.includes(x.item.kind)) continue;
+    if (PMOS_KINDS.includes(x.item.kind) ? !refOk(x.item.ref) : !x.item.url) continue;
+    out.push(x);
+  }
+  return out;
+}
+
+/** The rows that hold now, in the order their items were first added (a changed item keeps its place). */
+function read(runtimeDir) {
+  const out = new Map();
+  for (const row of lines(runtimeDir)) {
+    const id = identity(row);
+    if (row.removed) { out.delete(id); continue; }
+    out.set(id, out.has(id) ? { ...row, firstAt: out.get(id).firstAt } : { ...row, firstAt: row.at || null });
+  }
+  return out;
+}
+
+const view = (row) => ({
+  id: crypto16(identity(row)), kind: row.item.kind, ref: row.item.ref || null, url: row.item.url || null, title: row.item.title || row.item.ref || row.item.url,
+  ws: row.item.ws || null, topic: row.topic || null, present: row.present === true, scope: row.scope, from: 'you', by: row.by || null, at: row.at || null,
+});
+/** A short stable id for a row, so the page can name an item without sending its path back and forth. */
+function crypto16(s) { return require('crypto').createHash('sha1').update(s).digest('hex').slice(0, 12); }
+
+/** The material of one meeting: its series items and its own, in the order they were added. event: { id?, title, series? } */
+function forMeeting(runtimeDir, event) {
+  if (!event || !str(event.title)) return [];
+  const key = keyOf(event);
+  const id = str(event.id);
+  const mine = [];
+  for (const row of read(runtimeDir).values()) {
+    if (row.key !== key) continue;
+    if (row.scope === 'meeting' && !(id && row.event === id)) continue;
+    mine.push(row);
+  }
+  return mine.sort((a, b) => String(a.firstAt).localeCompare(String(b.firstAt))).map(view);
+}
+
+function append(runtimeDir, body, by) {
+  const bad = check(body);
+  if (bad) return { ok: false, error: bad };
+  if (!runtimeDir) return { ok: false, error: 'this server has no runtime folder, so the material cannot be saved' };
+  const op = body.op || 'add';
+  const scope = body.scope || 'meeting';
+  const item = cleanItem(body.item);
+  const line = { at: new Date().toISOString(), by: by || null, key: keyOf(body.event), series: body.event.series ? String(body.event.series) : null, event_title: str(body.event.title), scope, item };
+  if (scope === 'meeting') line.event = str(body.event.id);
+  if (op === 'remove') line.removed = true;
+  else {
+    if (str(body.topic)) line.topic = str(body.topic);
+    line.present = body.present === true && ['pmos-deck', 'slides', 'report'].includes(item.kind);
+    if (forMeeting(runtimeDir, body.event).length >= MAX_ITEMS && !read(runtimeDir).has(identity(line))) return { ok: false, error: 'a meeting holds at most ' + MAX_ITEMS + ' items' };
+  }
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  fs.appendFileSync(fileOf(runtimeDir), JSON.stringify(line) + '\n');
+  return { ok: true, items: forMeeting(runtimeDir, body.event) };
+}
+
+module.exports = { keyOf, read, forMeeting, append, check, classifyUrl, KINDS, PMOS_KINDS, LINK_KINDS, FILE };

package/workspace/lib/meeting-replay.js

@@ -0,0 +1,184 @@
+'use strict';
+/* meeting-replay.js — the pure join behind the meeting replay page (initiative meeting-material-replay, part 2).
+ *
+ *   build({ note, event?, stateLines?, frames?, audio?, topics?, now? }) → the replay
+ *
+ * The replay is Focus played back, so it joins three records PMOS already keeps and invents nothing:
+ *   the note       transcript lines (with who said them), decisions, next steps and questions, the audio's length
+ *   the Focus file <runtime>/focus/<note or event id>.jsonl, folded by lib/meeting-focus.js: topics, the stretches of talk, PMOS's notes
+ *   the shots      lib/notes-screen.js frames; a frame with `aside` truthy was set aside (it looked like another app) and is NEVER in the replay
+ *
+ * Every time is MEETING time in ms: 0 is where the recording starts, the same clock the audio, the transcript and the shots use
+ * (the audio's currentTime * 1000). `start_ms` is the wall clock (epoch ms) of meeting time 0, so the page can show 11:18.
+ *
+ * A KEY POINT'S TIME is the time of the transcript line it was caught from: the item's own `t` (the final notes and the minute
+ * bullets keep it), else the line its quote (or, failing that, its text) is found in. When none is known `t` is null and the page
+ * shows no play button. Nothing here reads a file or starts a process; lib/routes-meeting-replay.js reads and calls build().
+ *
+ * Output:
+ *   { ok, note: { id, title, state, initiative, ws }, meeting: { title, at, end, attendees },
+ *     audio: { url, ms } | null, start_ms, length_ms,
+ *     lines:  [{ i, t, who, text, source, key: { k, id } | null }]            by t
+ *     keys:   [{ id, k: 'decision'|'action'|'question', text, t, owner, due, by, state: 'draft'|'owner'|'open'|'answered', warn }]
+ *     topics: [{ id, text, src, state, minutes, n, first_t, stretches, parked, by }]   visited ones first, in the order they came up
+ *     runs:   [{ topic, n, from_ms, to_ms }]
+ *     notes:  [{ id, t, cat, body, heard, why, src }]                          PMOS's notes with the time they were made
+ *     shots:  [{ t, w, h, why?, text? }]                                       kept shots only
+ *     recordings: how many times the recording was started (1 for most notes)
+ *     gaps:   [{ from_ms, to_ms }]                                            where the recording was off between two starts (empty when there was one)
+ *     aside_count }
+ */
+const N = require('./notes.js');
+const F = require('./meeting-focus.js');
+
+const SHOT_TEXT_MAX = 400;
+const NEAR_LINE_MS = 3000;       // a key point whose time is not exactly a line's belongs to the line this close
+const ANSWER_OVERLAP = 0.6;
+
+const str = (v, n) => (typeof v === 'string' ? v.replace(/\s+/g, ' ').trim().slice(0, n) : '');
+const finite = (v) => typeof v === 'number' && Number.isFinite(v);
+const words = (t) => String(t == null ? '' : t).toLowerCase().normalize('NFKD').replace(/[̀-ͯ]/g, '').match(/[\p{L}\p{N}]+/gu) || [];
+const share = (a, b) => {
+  const wa = words(a); const hb = new Set(words(b));
+  return wa.length ? wa.filter((w) => hb.has(w)).length / wa.length : 0;
+};
+
+/** The wall clock (epoch ms) of meeting time 0: a transcript line's `at` minus its `t`, else when recording began, else the meeting's start. */
+function startOf(note, event) {
+  for (const x of (note && note.transcript) || []) {
+    const at = Date.parse(x && x.at);
+    if (x && finite(x.t) && Number.isFinite(at)) return at - x.t;
+  }
+  const rec = Date.parse(note && note.recorded_from);
+  if (Number.isFinite(rec)) return rec;
+  const ev = Date.parse(event && event.at);
+  return Number.isFinite(ev) ? ev : null;
+}
+
+/** The lines of the talk with a time: the final pass's segments when there are some, else the live lines; by t. */
+function linesOf(note) {
+  let raw = [];
+  try { raw = N.transcriptLines(note); } catch { raw = []; }
+  return raw.filter((x) => x && finite(x.t) && typeof x.text === 'string' && x.text.trim())
+    .map((x) => ({ t: Math.round(x.t), who: str(x.who, 60), text: str(x.text, 600), source: x.source || 'speech' }))
+    .sort((a, b) => a.t - b.t)
+    .map((x, i) => ({ i, ...x, key: null }));
+}
+
+/** The decisions, next steps and questions of the note, as the Notes page shows them: the final notes when written, else the minute
+ *  bullets, else the local summary. → { decision: [item], action: [item], question: [item] }, item = { text, quote?, t?, owner?, due?, by? } */
+function caughtOf(note) {
+  const out = { decision: [], action: [], question: [] };
+  const f = note && note.final_notes;
+  const fromList = (kind, list) => {
+    for (const x of Array.isArray(list) ? list : []) {
+      const text = str(x && x.text, 300);
+      if (text) out[kind].push({ text, quote: str(x.quote, 400), t: finite(x.t) ? x.t : null, owner: str(x.owner, 60) || null, due: str(x.due, 40) || null, by: str(x.by, 120) || null });
+    }
+  };
+  if (f && ((f.decisions || []).length || (f.actions || []).length || (f.questions || []).length)) {
+    fromList('decision', f.decisions); fromList('action', f.actions); fromList('question', f.questions);
+    return out;
+  }
+  const bl = ((note && note.bullets) || []).filter((b) => b && b.text && !b.dropped && !b.open);
+  if (bl.length) {
+    for (const b of bl) if (out[b.cat]) out[b.cat].push({ text: str(b.text, 300), quote: '', t: finite(b.t) ? b.t : null, owner: str(b.owner, 60) || null, due: str(b.due, 40) || null, by: null });
+    if (out.decision.length || out.action.length || out.question.length) return out;
+  }
+  const sec = (note && note.summary && note.summary.sections) || {};
+  const at = (x) => { const m = /^\s*\[?(\d+:\d{2}(?::\d{2})?)\]?\s*$/.exec(String((x && x.at) || '')); return m ? N.parseTime(m[1]) : null; };
+  const fromSec = (kind, list) => { for (const x of Array.isArray(list) ? list : []) { const text = str(x && x.text, 300); if (text) out[kind].push({ text, quote: '', t: at(x), owner: str(x.owner, 60) || null, due: str(x.due, 40) || null, by: null }); } };
+  fromSec('decision', sec.decisions); fromSec('action', sec.actions); fromSec('question', sec.questions);
+  return out;
+}
+
+/** The time of the line a key point was caught from: its own t, else the line its quote (or its text) is in; null when unknown. */
+function timeOfKey(item, lines) {
+  if (finite(item.t)) return Math.max(0, Math.round(item.t));
+  const timed = lines.map((l) => ({ t: l.t, text: l.text }));
+  for (const probe of [item.quote, item.text]) {
+    if (!probe) continue;
+    let at = null;
+    try { at = N.groundQuote(timed, probe, null); } catch { at = null; }
+    if (finite(at)) return Math.max(0, Math.round(at));
+  }
+  return null;
+}
+
+/** Join the three records. */
+function build({ note, event = null, stateLines = [], frames = [], audio = null, topics = [], now = Date.now() } = {}) {
+  const n = note || {};
+  const lines = linesOf(n);
+  const start = startOf(n, event);
+  const shots = (frames || []).filter((f) => f && finite(f.t) && !f.aside).sort((a, b) => a.t - b.t)
+    .map((f) => ({ t: f.t, w: f.w || 0, h: f.h || 0, ...(f.why ? { why: f.why } : {}), ...(f.text ? { text: str(f.text, SHOT_TEXT_MAX) } : {}) }));
+  const asideCount = (frames || []).filter((f) => f && f.aside).length;
+
+  // Focus's state: topics, stretches, PMOS's notes. Stretches are measured from meeting time 0.
+  const fold = F.foldState(stateLines || [], { topics, startMs: start, nowMs: start == null ? now : start + 0 });
+  const pmos = start == null ? [] : fold.notes.filter((x) => x && x.body && finite(x.at)).map((x) => ({ id: x.id, t: Math.max(0, Math.round(x.at - start)), cat: str(x.cat, 30), body: str(x.body, 700), heard: str(x.heard, 300), why: str(x.why, 300), src: str(x.src, 80) }))
+    .sort((a, b) => a.t - b.t);
+
+  // length: the audio, the clock of the note, else the last thing that has a time
+  let heard = 0;
+  if (n.ended_at || n.paused_at) { try { heard = N.heardMs(n, now) || 0; } catch { heard = 0; } }   // a note still recording has no end to trust
+  const caught = caughtOf(n);
+  const keys = [];
+  for (const [kind, list] of [['decision', caught.decision], ['action', caught.action], ['question', caught.question]]) {
+    list.forEach((it, i) => {
+      const t = timeOfKey(it, lines);
+      const answered = kind === 'question' && t != null && pmos.some((p) => p.cat === 'Answer' && p.t >= t && share(it.text, p.heard || p.body) >= ANSWER_OVERLAP);
+      const state = kind === 'action' ? (it.owner ? 'draft' : 'owner') : kind === 'question' ? (answered ? 'answered' : 'open') : 'draft';
+      keys.push({ id: kind[0] + (i + 1), k: kind, text: it.text, t, owner: it.owner, due: it.due, by: it.by, state, warn: state === 'owner' || state === 'open' });
+    });
+  }
+  keys.sort((a, b) => (a.t == null) - (b.t == null) || (a.t || 0) - (b.t || 0));
+  // the line a key point was caught from carries its mark
+  for (const k of keys) {
+    if (k.t == null || !lines.length) continue;
+    let best = null;
+    for (const l of lines) if (!l.key && (best === null || Math.abs(l.t - k.t) < Math.abs(best.t - k.t))) best = l;
+    if (best && Math.abs(best.t - k.t) <= NEAR_LINE_MS) best.key = { k: k.k, id: k.id };
+  }
+
+  const lastT = (xs) => xs.reduce((m, x) => (finite(x.t) && x.t > m ? x.t : m), 0);
+  const length = Math.max(finite(audio && audio.ms) ? audio.ms : 0, heard, lastT(lines), lastT(shots), lastT(keys), lastT(pmos));
+
+  // stretches, in ms; a stretch still open runs to the end
+  const runs = fold.runs.map((r) => ({ topic: r.topic, from_ms: Math.round(r.from_min * 60000), to_ms: r.to_min == null ? length : Math.round(r.to_min * 60000) }))
+    .filter((r) => r.to_ms > r.from_ms || r.to_ms === length);
+  const firstOf = new Map();
+  for (const r of runs) if (!firstOf.has(r.topic)) firstOf.set(r.topic, r.from_ms);
+  const visited = fold.topics.filter((t) => firstOf.has(t.id)).sort((a, b) => firstOf.get(a.id) - firstOf.get(b.id));
+  const numOf = new Map(visited.map((t, i) => [t.id, i + 1]));
+  const stretches = (id) => runs.filter((r) => r.topic === id).length;
+  const minutesOf = (id) => Math.round(runs.filter((r) => r.topic === id).reduce((s, r) => s + (r.to_ms - r.from_ms), 0) / 60000);
+  const topicRows = [...visited, ...fold.topics.filter((t) => !firstOf.has(t.id))].map((t) => ({
+    id: t.id, text: t.text, src: t.src, state: t.state, minutes: minutesOf(t.id), n: numOf.get(t.id) || null, first_t: firstOf.has(t.id) ? firstOf.get(t.id) : null,
+    stretches: stretches(t.id), parked: t.state === 'parked', by: t.by || null }));
+  // A recording that was stopped and started again (a Pause then Listen, or a new Listen on the same meeting) has one stretch per start. The audio keeps one clock
+  // (lib/notes-audio.js places a late chunk at its own time and leaves the gap silent), so the replay needs only to show where the recording was off.
+  const sessions = (Array.isArray(n.sessions) ? n.sessions : []).filter((x) => x && Number.isFinite(Date.parse(x.from))).sort((a, b) => Date.parse(a.from) - Date.parse(b.from));
+  const gaps = [];
+  if (start != null) {
+    for (let i = 1; i < sessions.length; i++) {
+      const off = Date.parse(sessions[i - 1].to); const on = Date.parse(sessions[i].from);
+      if (!Number.isFinite(off) || !Number.isFinite(on) || on <= off) continue;
+      const from_ms = Math.max(0, Math.round(off - start)); const to_ms = Math.min(length, Math.round(on - start));
+      if (to_ms > from_ms) gaps.push({ from_ms, to_ms });
+    }
+  }
+  const ev = event || {};
+  const m = n.meeting || {};
+  return {
+    ok: true,
+    note: { id: n.id, title: n.title || m.title || ev.title || 'Untitled note', state: n.state || null, initiative: n.initiative || null, ws: n.ws || (n.initiative && n.initiative.ws) || null },
+    meeting: { title: ev.title || m.title || n.title || 'Untitled note', at: ev.at || m.start || n.recorded_from || n.created_at || null, end: ev.end || m.end || null,
+      attendees: [].concat(ev.attendees || ev.people || []).map((p) => (p && typeof p === 'object' ? p.name || p.id : p)).filter(Boolean).map(String) },
+    audio: audio && audio.url ? { url: audio.url, ms: finite(audio.ms) ? audio.ms : null } : null,
+    start_ms: start, length_ms: length, recordings: Math.max(1, sessions.length), gaps,
+    lines, keys, topics: topicRows, runs: runs.map((r) => ({ ...r, n: numOf.get(r.topic) || null })), notes: pmos, shots, aside_count: asideCount,
+  };
+}
+
+module.exports = { build, caughtOf, timeOfKey, linesOf, startOf };

package/workspace/lib/notes-screen.js

@@ -8,6 +8,10 @@
  *   getOn(runtimeDir) · setOn(runtimeDir, bool)   "Capture the shared screen", on by default, for this machine
  *   ocrDetect({ env? }) → { bin } | null      the tesseract the PM installed
  *   ocrIdle() → Promise                       resolves when the text queue is empty (tests)
+ *   classifyShot(text, { hints? }) → { aside, app, call }   does the text of a shot look like another app and not like the call? Pure.
+ *   listAside(runtimeDir, id) · asideCount(runtimeDir, id)   the shots set aside for review
+ *   keep(runtimeDir, id, t) · discard(runtimeDir, id, t) · discardAll(runtimeDir, id)   the PM's answer to a set-aside shot
+ *   sweepAside(runtimeDir, { now?, days? }) → n   delete the shots set aside for more than 7 days
  *
  * WHAT IT KEEPS. A folder next to the note's audio, `<runtime>/notes/recordings/<id>.screen/`: one image file per shot, named by
  * its meeting time in milliseconds (`000123456.jpg`), and `index.json`, an array of { t, file, w, h, bytes, why?, text? } sorted by t,
@@ -22,6 +26,13 @@
  * kept shot is read for its text, one at a time and in the background, and the text is added to that shot's row in the index.
  * A failed or timed-out read leaves the shot with no text and is not an error. Without tesseract nothing is read.
  *
+ * SET ASIDE. When the picture is the whole screen (the shot's `surface` is 'monitor'), every app the PM switches to is on it. After the
+ * text is read, a shot whose text looks like another app (Slack, a mailbox, a chat) and not like the call (Zoom's or Meet's controls) or
+ * what is shared in it is marked `aside: true` in the index. A set-aside shot is not listed and not served by default, so the note, the
+ * replay and the agent never see it. The PM reviews them (listAside) and answers each one: Keep it (the shot joins the note), Delete
+ * (file and row go) or Delete all. sweepAside deletes the shots set aside for more than 7 days. A shot with no text, a shot from a
+ * window or a tab, and every shot on a machine with no tesseract are kept, as before.
+ *
  * WHAT IT NEVER DOES. It sends nothing and opens no network module. The only program it runs is the tesseract the PM installed,
  * on a file in the note's own folder, with no shell and a time limit. The routes (lib/routes-notes.js) keep no shot for a private
  * note, for a note that is not listening, or when the PM switched capturing off, and delete the folder when a note is made
@@ -37,6 +48,8 @@ const MAX_BYTES = 500 * 1024 * 1024;
 const MAX_T = 999999999;                    // the file name holds nine digits of milliseconds
 const OCR_TIMEOUT_MS = 30000;
 const OCR_MAX_CHARS = 4000;
+const ASIDE_DAYS = 7;
+const SURFACES = ['window', 'browser', 'monitor'];
 const ID_RE = /^n-[0-9a-z]{4,16}-[0-9a-f]{4}$/;
 const FILE_RE = /^\d{9}\.(jpg|png|webp)$/;
 const TYPES = { jpg: 'image/jpeg', png: 'image/png', webp: 'image/webp' };
@@ -80,7 +93,7 @@ const writeIndex = (runtimeDir, id, rows) => writeAtomic(indexOf(runtimeDir, id)
 const dimension = (n) => (Number.isFinite(Number(n)) && Number(n) > 0 ? Math.min(20000, Math.round(Number(n))) : 0);
 
 /** Keep one shot. `t` is the meeting time in ms, `buf` the image bytes, `w` and `h` its size in pixels. */
-function add(runtimeDir, { id, t, buf, w, h, why } = {}) {
+function add(runtimeDir, { id, t, buf, w, h, why, surface } = {}) {
   if (!ID_RE.test(String(id || ''))) return { ok: false, status: 400, error: 'no such note' };
   const time = typeof t === 'number' ? t : NaN;
   if (!Number.isFinite(time) || time < 0 || time > MAX_T) return { ok: false, status: 400, error: 'a screenshot needs its meeting time' };
@@ -106,27 +119,36 @@ function add(runtimeDir, { id, t, buf, w, h, why } = {}) {
   // why the page kept it (the screen changed, a line pointed at it, a highlight): plain words, kept short
   const reason = typeof why === 'string' ? why.replace(/\s+/g, ' ').trim().slice(0, 120) : '';
   if (reason) frame.why = reason;
+  // what the picture shows: the meeting's window, a browser tab or the whole screen; only the whole screen is checked for other apps
+  if (SURFACES.includes(surface)) frame.surface = surface;
   writeIndex(runtimeDir, id, others.concat([frame]).sort((x, y) => x.t - y.t));
   queueOcr(runtimeDir, id, frame);
   return { ok: true, frame };
 }
 
-function list(runtimeDir, id) {
+/** The note's shots, by meeting time. A set-aside shot is not in this list. */
+function list(runtimeDir, id, { aside = false } = {}) {
+  if (!ID_RE.test(String(id || ''))) return [];
+  return readIndex(runtimeDir, id).filter((f) => !!f.aside === !!aside);   // { aside: true } lists the set-aside shots instead
+}
+/** The shots set aside for review, by meeting time. */
+function listAside(runtimeDir, id) {
   if (!ID_RE.test(String(id || ''))) return [];
-  return readIndex(runtimeDir, id);
+  return readIndex(runtimeDir, id).filter((f) => f.aside);
 }
+const asideCount = (runtimeDir, id) => listAside(runtimeDir, id).length;
 
 /** The shot at meeting time `t` as its image. A shot is never changed once kept, so the browser may keep it for good. */
-function serve(req, res, runtimeDir, id, t) {
+function serve(req, res, runtimeDir, id, t, { aside = false } = {}) {
   const miss = () => { res.writeHead(404, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ ok: false, error: 'this note has no screenshot at that time' })); };
   if (!ID_RE.test(String(id || '')) || t === null || t === undefined || t === '' || !Number.isFinite(Number(t))) return miss();
   const at = Math.round(Number(t));
-  const f = readIndex(runtimeDir, id).find((x) => x.t === at);
+  const f = readIndex(runtimeDir, id).find((x) => x.t === at && !!x.aside === !!aside);   // a set-aside shot is served only for the review
   if (!f) return miss();
   const file = path.join(dirOf(runtimeDir, id), f.file);
   let size;
   try { size = fs.statSync(file).size; } catch { return miss(); }
-  res.writeHead(200, { 'Content-Type': TYPES[path.extname(f.file).slice(1)] || 'application/octet-stream', 'Content-Length': size, 'Cache-Control': 'private, max-age=31536000, immutable' });
+  res.writeHead(200, { 'Content-Type': TYPES[path.extname(f.file).slice(1)] || 'application/octet-stream', 'Content-Length': size, 'Cache-Control': aside ? 'private, no-store' : 'private, max-age=31536000, immutable' });
   if (req.method === 'HEAD') { res.end(); return; }
   fs.createReadStream(file).on('error', () => res.end()).pipe(res);
 }
@@ -140,6 +162,95 @@ function remove(runtimeDir, id) {
   return had;
 }
 
+/* ── set aside: the PM's answer ──────────────────────────────────────────────────────────────────── */
+const rmFile = (runtimeDir, id, f) => { try { fs.unlinkSync(path.join(dirOf(runtimeDir, id), f.file)); } catch { /* none */ } };
+const asideRow = (rows, t) => rows.find((f) => f.t === Math.round(Number(t)) && f.aside);
+/** Keep it: the shot joins the note, and it is not checked again. */
+function keep(runtimeDir, id, t) {
+  if (!ID_RE.test(String(id || ''))) return { ok: false, status: 400, error: 'no such note' };
+  const rows = readIndex(runtimeDir, id);
+  const row = asideRow(rows, t);
+  if (!row) return { ok: false, status: 404, error: 'that shot is not set aside' };
+  delete row.aside; delete row.asideApp; delete row.asideAt;
+  row.kept = true;
+  writeIndex(runtimeDir, id, rows);
+  return { ok: true, frame: row };
+}
+/** Delete: the file and its row go. Only a set-aside shot can be deleted here. */
+function discard(runtimeDir, id, t) {
+  if (!ID_RE.test(String(id || ''))) return { ok: false, status: 400, error: 'no such note' };
+  const rows = readIndex(runtimeDir, id);
+  const row = asideRow(rows, t);
+  if (!row) return { ok: false, status: 404, error: 'that shot is not set aside' };
+  rmFile(runtimeDir, id, row);
+  writeIndex(runtimeDir, id, rows.filter((f) => f !== row));
+  return { ok: true, deleted: 1 };
+}
+/** Delete all: every set-aside shot of the note. The kept shots stay. */
+function discardAll(runtimeDir, id) {
+  if (!ID_RE.test(String(id || ''))) return { ok: false, status: 400, error: 'no such note' };
+  const rows = readIndex(runtimeDir, id);
+  const gone = rows.filter((f) => f.aside);
+  if (!gone.length) return { ok: true, deleted: 0 };
+  for (const f of gone) rmFile(runtimeDir, id, f);
+  writeIndex(runtimeDir, id, rows.filter((f) => !f.aside));
+  return { ok: true, deleted: gone.length };
+}
+/** Delete every shot set aside for more than `days` days, in every note. Returns how many went. */
+function sweepAside(runtimeDir, { now = Date.now(), days = ASIDE_DAYS } = {}) {
+  let names = [];
+  try { names = fs.readdirSync(path.join(runtimeDir, 'notes', 'recordings')); } catch { return 0; }
+  let n = 0;
+  for (const name of names) {
+    if (!name.endsWith('.screen')) continue;
+    const id = name.slice(0, -'.screen'.length);
+    if (!ID_RE.test(id)) continue;
+    const rows = readIndex(runtimeDir, id);
+    if (!rows.some((f) => f.aside)) continue;
+    const left = rows.filter((f) => {
+      if (!f.aside || !Number.isFinite(f.asideAt) || now - f.asideAt < days * 864e5) return true;
+      rmFile(runtimeDir, id, f); n++; return false;
+    });
+    if (left.length !== rows.length) { try { writeIndex(runtimeDir, id, left); } catch { /* the folder went away */ } }
+  }
+  return n;
+}
+
+/* ── what looks like another app ─────────────────────────────────────────────────────────────────── */
+// The call: the controls of Zoom, Meet and Teams, and what each says while someone shares. Any one of these keeps the shot.
+const CALL = /\b(unmute|mute|stop video|start video|participants?|share screen|stop share(?:ing)?|new share|you are screen sharing|you are viewing|you'?re presenting|stop presenting|present now|presenting|raise hand|lower hand|breakout rooms?|leave meeting|leave call|end meeting|meeting controls|zoom meeting|zoom workplace|meet\.google\.com|google meet|turn (?:on|off) camera|turn (?:on|off) microphone|live captions|waiting room|in this meeting|hide self view|gallery view|speaker view)\b/i;
+// Another app. `strong`: one is enough. `weak`: two different ones are needed.
+const OTHER = [
+  { app: 'Slack', strong: [/\bslack\b/i], weak: [/\bdirect messages\b/i, /\bchannels\b/i, /\bthreads\b/i, /\bhuddles?\b/i, /\bmentions (?:&|and) reactions\b/i, /\bmessage #[a-z0-9_-]+/i] },
+  { app: 'Gmail', strong: [/\bgmail\b/i, /\binbox\b/i], weak: [/\bcompose\b/i, /\bstarred\b/i, /\bsnoozed\b/i, /\bsent mail\b/i, /\bdrafts\b/i, /\bprimary\b/i, /\bpromotions\b/i] },
+  { app: 'Outlook', strong: [/\boutlook\b/i], weak: [/\bnew mail\b/i, /\bjunk email\b/i, /\bsent items\b/i, /\bfocused\b/i] },
+  { app: 'WhatsApp', strong: [/\bwhatsapp\b/i], weak: [] },
+  { app: 'Telegram', strong: [/\btelegram\b/i], weak: [] },
+  { app: 'Discord', strong: [/\bdiscord\b/i], weak: [] },
+  { app: 'Messages', strong: [/\bimessage\b/i, /\bmessenger\b/i], weak: [] },
+  { app: 'Social media', strong: [/\bfacebook\b/i, /\binstagram\b/i, /\btwitter\b/i, /\blinkedin\b/i, /\btiktok\b/i], weak: [] },
+  { app: 'Video or music', strong: [/\byoutube\b/i, /\bnetflix\b/i, /\bspotify\b/i], weak: [] },
+];
+
+/** Does the text of a shot look like another app and not like the call? Pure.
+ *  → { aside, app, call }. `hints` are words from what is shared in the meeting (a deck's title, say): a shot that names one is kept.
+ *  Text that is empty, or that names no app, is never set aside. */
+function classifyShot(text, { hints = [] } = {}) {
+  const t = String(text || '');
+  if (!t.trim()) return { aside: false, app: null, call: false };
+  if (CALL.test(t)) return { aside: false, app: null, call: true };
+  const low = t.toLowerCase();
+  for (const h of hints || []) { const w = String(h || '').trim().toLowerCase(); if (w.length >= 4 && low.includes(w)) return { aside: false, app: null, call: false }; }
+  for (const o of OTHER) {
+    if (o.strong.some((re) => re.test(t)) || o.weak.filter((re) => re.test(t)).length >= 2) return { aside: true, app: o.app, call: false };
+  }
+  return { aside: false, app: null, call: false };
+}
+// the words of what is shared in the meeting, for classifyShot: set by whoever knows them (the material of the meeting), else none
+let hintsOf = null;
+/** fn(runtimeDir, id) → [word]: what is shared in this note's meeting. Optional. */
+function setHints(fn) { hintsOf = typeof fn === 'function' ? fn : null; }
+
 /* ── on-screen text ──────────────────────────────────────────────────────────────────────────────── */
 const isExec = (f) => { try { fs.accessSync(f, fs.constants.X_OK); return fs.statSync(f).isFile(); } catch { return false; } };
 /** The tesseract on this machine: PMOS_TESSERACT, else the PATH, else where Homebrew puts it. */
@@ -168,7 +279,16 @@ function readText(bin, runtimeDir, id, frame) {
         // patch the row only if the same shot is still there (it may have been replaced or deleted while it was read)
         const rows = readIndex(runtimeDir, id);
         const row = rows.find((f) => f.t === frame.t && f.file === frame.file && f.bytes === frame.bytes);
-        if (row) { row.text = text; try { writeIndex(runtimeDir, id, rows); } catch { /* the folder went away */ } }
+        if (row) {
+          row.text = text;
+          // the whole screen was the picture: a shot that looks like another app is set aside, for the PM to keep or delete
+          if (row.surface === 'monitor' && !row.kept) {
+            let hints = []; try { hints = hintsOf ? hintsOf(runtimeDir, id) || [] : []; } catch { hints = []; }
+            const c = classifyShot(text, { hints });
+            if (c.aside) { row.aside = true; row.asideApp = c.app; row.asideAt = Date.now(); }
+          }
+          try { writeIndex(runtimeDir, id, rows); } catch { /* the folder went away */ }
+        }
       }
       resolve();
     });
@@ -177,4 +297,4 @@ function readText(bin, runtimeDir, id, frame) {
 /** Resolves when every text read queued so far has ended. */
 function ocrIdle() { return queue.then(() => (waiting > 0 ? ocrIdle() : undefined)); }
 
-module.exports = { add, list, serve, remove, getOn, setOn, ocrDetect, ocrIdle, kindOf, MAX_SHOT_BYTES, MAX_SHOTS, MAX_BYTES };
+module.exports = { add, list, listAside, asideCount, keep, discard, discardAll, sweepAside, classifyShot, setHints, ASIDE_DAYS, serve, remove, getOn, setOn, ocrDetect, ocrIdle, kindOf, MAX_SHOT_BYTES, MAX_SHOTS, MAX_BYTES };

package/workspace/lib/report-structure.js

@@ -36,7 +36,7 @@ const crypto = require('crypto');
 const RD = require('./report-draft.js');
 const CS = require('./charts-store.js');
 
-const EVENTS = Object.freeze(['describe', 'turn', 'version', 'accept', 'revert', 'source', 'remove', 'dry', 'check', 'error']);
+const EVENTS = Object.freeze(['describe', 'turn', 'version', 'accept', 'revert', 'source', 'remove', 'dry', 'pull', 'check', 'error']);
 const PMOS_KINDS = Object.freeze(['pmos-level', 'dashboard', 'chart', 'document', 'past-report']);
 const OUTSIDE_KINDS = Object.freeze(['connector', 'link', 'upload', 'person', 'chrome', 'computer']);
 const KINDS = Object.freeze([...PMOS_KINDS, ...OUTSIDE_KINDS]);
@@ -79,7 +79,7 @@ function paths(root, id) {
   const folder = path.join(abs, rel);
   const dir = path.join(folder, 'structure');
   return { abs, rel, folder, dir, relDir: `${rel}/structure`, events: path.join(dir, 'structure.jsonl'), versions: path.join(dir, 'versions'), pending: path.join(dir, 'pending'),
-    dry: path.join(dir, 'dry'), checks: path.join(dir, 'checks'), checksPending: path.join(dir, 'checks', 'pending'), brief: path.join(dir, 'brief.md'), briefRel: `${rel}/structure/brief.md` };
+    dry: path.join(dir, 'dry'), pull: path.join(dir, 'pull'), pullPending: path.join(dir, 'pull', 'pending'), checks: path.join(dir, 'checks'), checksPending: path.join(dir, 'checks', 'pending'), brief: path.join(dir, 'brief.md'), briefRel: `${rel}/structure/brief.md` };
 }
 
 // ── the one writer and the fold ───────────────────────────────────────────────────────────────────────────
@@ -440,6 +440,50 @@ function landVersion(root, id, plan, { turn, answer, questions, options, from, b
   return { ok: true, n, plan: v.plan };
 }
 
+// ── test pull (report-structure-gaps): ONE source read for the last complete period ──────────────────────────
+/** What a pull job wrote for one source of a plan. → { ok, pull } | refusal. `reached` false is a valid answer: the source returned nothing. */
+function validatePull(data, plan, sourceId) {
+  if (!isObj(data)) return refuse(422, 'the pull result must be a JSON object');
+  const src = listOf(plan && plan.sources).find((s) => s.id === sourceId);
+  if (!src) return refuse(422, 'the source is not in the plan');
+  const chartIds = new Set(listOf(plan.charts).filter((c) => c.source === sourceId).map((c) => c.id));
+  if (str(data.source) !== sourceId) return refuse(422, 'source must be the source that was pulled');
+  if (!Number.isInteger(data.n) || data.n < 1) return refuse(422, 'n must be the version number');
+  const per = badText(data.period, 'period', { max: 40 });
+  if (per || !data.period.trim()) return refuse(422, per || 'period is required');
+  if (typeof data.reached !== 'boolean') return refuse(422, 'reached must be true or false');
+  const rs = badText(data.reason === undefined ? '' : data.reason, 'reason', { max: 300, allowEmpty: true });
+  if (rs) return refuse(422, rs);
+  const values = data.values === undefined ? [] : data.values;
+  if (!Array.isArray(values) || values.length > LIMITS.charts) return refuse(422, `values is a list of at most ${LIMITS.charts}`);
+  const out = [];
+  for (const [i, v] of values.entries()) {
+    const w = `values[${i}]`;
+    if (!isObj(v)) return refuse(422, `${w} must be an object`);
+    if (!chartIds.has(str(v.chart))) return refuse(422, `${w}.chart ${JSON.stringify(str(v.chart)).slice(0, 40)} is not a chart of the plan that uses this source`);
+    const c = {};
+    for (const k of ['value', 'was', 'delta', 'note']) { const r = textField(v, k, w); if (r.error) return refuse(422, r.error); c[k] = r.v; }
+    if (v.flag !== undefined && typeof v.flag !== 'boolean') return refuse(422, `${w}.flag must be true or false`);
+    out.push({ chart: v.chart, value: c.value, was: c.was, delta: c.delta, flag: v.flag === true, note: c.note });
+  }
+  const reached = data.reached === true;
+  if (!reached && out.length) return refuse(422, 'a source that was not reached has no values');
+  const got = out.filter((v) => v.value).length;
+  const reason = str(data.reason).trim() || (reached && !got ? 'The source answered, but no chart returned a number.' : '');
+  return { ok: true, pull: { source: sourceId, n: data.n, period: data.period.trim(), reached, ok: reached && got > 0, reason, values: out, charts: chartIds.size, got } };
+}
+function writePull(root, id, pull) {
+  if (!SLUG_RE.test(String(pull.source))) throw new Error('report-structure: bad source id');
+  writeAtomic(path.join(paths(root, id).pull, `${pull.source}.json`), JSON.stringify(pull, null, 2) + '\n');
+}
+function readPull(root, id, source) { return SLUG_RE.test(String(source)) ? readJson(path.join(paths(root, id).pull, `${source}.json`)) : null; }
+function readPulls(root, id) {
+  const out = {};
+  let names = []; try { names = fs.readdirSync(paths(root, id).pull); } catch { return out; }
+  for (const f of names) { const m = /^([a-z0-9][a-z0-9-]*)\.json$/.exec(f); if (m && SLUG_RE.test(m[1])) { const o = readPull(root, id, m[1]); if (o) out[m[1]] = o; } }
+  return out;
+}
+
 // ── the GET answer ────────────────────────────────────────────────────────────────────────────────────────
 /** Chrome and computer sources show what their last check found: a passing check is Reached, a failing one Needs you. */
 function overlay(plan, checks) {
@@ -450,7 +494,7 @@ function overlay(plan, checks) {
     return { ...s, state: c.ok ? 'reached' : 'needs-you' };
   }) };
 }
-function structureAnswer(root, id, { running } = {}) {
+function structureAnswer(root, id, { running, pulling } = {}) {
   const st = stateOf(root, id);
   const checks = readChecks(root, id);
   const versions = [...st.versions.values()].sort((a, b) => a.n - b.n).map((v) => ({ n: v.n, at: v.at, turn: v.turn }));
@@ -458,7 +502,7 @@ function structureAnswer(root, id, { running } = {}) {
     running: !!running, job: running ? { since: running.since, turn: running.turn, kind: running.kind } : null,
     current: st.current, saved: st.saved ? st.saved.n : null, versions, log: st.log,
     plan: st.current != null ? overlay(readVersion(root, id, st.current), checks) : null,
-    dry: st.dry, checks, errors: st.errors.map((e) => ({ text: e.text, at: e.at })),
+    dry: st.dry, checks, pulls: readPulls(root, id), pulling: Array.isArray(pulling) ? pulling : [], errors: st.errors.map((e) => ({ text: e.text, at: e.at })),
   };
 }
 /** What the setups GET carries for one report: { saved, at, charts, sections } of the accepted version, else null. */
@@ -512,4 +556,4 @@ function writeBrief(root, id, setup, { now } = {}) {
 
 module.exports = { EVENTS, KINDS, PMOS_KINDS, OUTSIDE_KINDS, STATES, FIXED, LIMITS, CHECK_STEPS, CHECK_STATES, CADENCE_RE, SLUG_RE, RUN_RE,
   paths, append, readEvents, fold, stateOf, nextN, badText, validatePlan, validateSource, validateDry, validateCheck, cleanQuestions, cleanOptions, addSourceTo, removeFrom,
-  landVersion, readVersion, rewriteVersion, writeDry, readDry, writeCheck, readCheck, readChecks, writeBrief, structureAnswer, savedOf, overlay, defaultState, newRun };
+  landVersion, readVersion, rewriteVersion, writeDry, readDry, validatePull, writePull, readPull, readPulls, writeCheck, readCheck, readChecks, writeBrief, structureAnswer, savedOf, overlay, defaultState, newRun };