synabun 2.0.0-beta → 2.0.5

package/neural-interface/lib/greeting/facts.js

@@ -0,0 +1,320 @@
+// ═══════════════════════════════════════════
+// SynaBun — Greeting: the facts (pure)
+// ═══════════════════════════════════════════
+//
+// What a greeting may say, decided without a model: the records of one project
+// (sources.js reads them) become a short list of facts, a fingerprint that
+// changes only when there is something new to say, the decision whether this
+// opening is a return worth greeting, the deterministic line used when the
+// writer is not, and the rows the "Based on" disclosure shows.
+//
+// A fact is said whole or left out: a name may be shortened with an ellipsis,
+// a statement never is. Pure: no I/O, no clock of its own.
+
+import { createHash } from 'node:crypto';
+import { FACTS, RETURN, TEXT } from './budgets.js';
+
+const collapse = (value) => String(value ?? '').replace(/\s+/g, ' ').trim();
+const ms = (value) => { const at = typeof value === 'number' ? value : Date.parse(value ?? ''); return Number.isFinite(at) ? at : null; };
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** A name shortened at a word, with an ellipsis (names only: titles, a quoted ask). */
+export function clipLabel(value, max = TEXT.titleChars) {
+  const text = collapse(value);
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max - 1);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > max * 0.6 ? cut.slice(0, space) : cut).replace(/[\s,;:.(-]+$/, '')}…`;
+}
+
+/** The sentences of a text (terminal punctuation kept). */
+export function splitSentences(value) {
+  const text = collapse(value);
+  if (!text) return [];
+  return text.split(/(?<=[.!?…]["”’')\]]?)\s+/u).map((part) => part.trim()).filter(Boolean);
+}
+
+/** A statement said whole or not at all: the text when it fits, else its leading whole sentences, else ''. */
+export function wholeOrNothing(value, max) {
+  const text = collapse(value);
+  if (text.length <= max) return text;
+  let out = '';
+  for (const sentence of splitSentences(text)) {
+    const next = out ? `${out} ${sentence}` : sentence;
+    if (next.length > max) break;
+    out = next;
+  }
+  // One run-on "sentence" with no end in sight is not a whole statement.
+  return /[.!?…]["”’')\]]?$/u.test(out) ? out : '';
+}
+
+/** "40 minutes" · "3 hours" · "2 days" · "3 weeks" (English; the panels format their own). */
+export function awayText(gapMs) {
+  const minutes = Math.max(0, Math.round(Number(gapMs) / 60_000));
+  if (!Number.isFinite(minutes)) return '';
+  if (minutes < 60) return plural(Math.max(1, minutes), 'minute');
+  const hours = Math.round(minutes / 60);
+  if (hours < 36) return plural(hours, 'hour');
+  const days = Math.round(hours / 24);
+  if (days < 21) return plural(days, 'day');
+  if (days < 75) return plural(Math.round(days / 7), 'week');
+  return plural(Math.round(days / 30), 'month');
+}
+
+const PROBLEMS = new Set(['failed', 'blocked', 'needs_input', 'interrupted']);
+const STATUS_WORDS = Object.freeze({ done: 'finished', completed: 'finished', failed: 'failed', blocked: 'is blocked', needs_input: 'needs your input', interrupted: 'was interrupted', stopped: 'was stopped', running: 'is still running' });
+
+/** A dispatched run's outcome in one word: what its worker reported, else how the run ended. */
+export function runStatus(run = {}) {
+  if (run.active === true) return 'running';
+  const reported = String(run.outcome || '').toLowerCase();
+  if (reported === 'done' || PROBLEMS.has(reported)) return reported;
+  const state = String(run.state || '').toLowerCase();
+  if (state === 'completed') return 'done';
+  if (state === 'failed' || state === 'interrupted' || state === 'stopped') return state;
+  return reported || state || 'done';
+}
+
+/** An open item as the record holds it; one cut short upstream loses its unfinished tail. */
+function wholeItem(value) {
+  let text = collapse(value);
+  if (!text.endsWith('…')) return { text, cut: false };
+  // "blocked: Title (a note that was cut…" → "blocked: Title"
+  const paren = text.lastIndexOf(' (');
+  if (paren > 0 && !text.slice(paren).includes(')')) text = text.slice(0, paren).trim();
+  return { text, cut: text.endsWith('…') };
+}
+
+/**
+ * The facts of one project.
+ * raw: { project, label, now, since, threads[], sessions[], memories[], runs[], schedules[], elsewhere[], git, owner }
+ *   threads   [{ memoryId, sessionId, title, endedAt, asks[], open[] }]            newest first (assistant-threads)
+ *   sessions  [{ id, sessionId, title, summary, open[], at, agent, source }]      session summaries and captures
+ *   memories  [{ id, title, excerpt, category, importance, at }]                  significant, from the last working period
+ *   runs      [{ runId, title, state, outcome, active, finishedAt, provider }]    this project, since the person left
+ *   schedules [{ id, name, result, at }]                                          runs that did not complete
+ *   elsewhere [{ project, label, runs, schedules }]                               failures in other projects (counts only)
+ *   git       { branch, dirty } | null
+ *   owner     { notes[], noteIds[], words[] }
+ * `redact` removes credentials from any text before it is used.
+ */
+export function buildFacts(raw = {}, { redact = (text) => text } = {}) {
+  const clean = (value) => { try { return collapse(redact(collapse(value))); } catch { return ''; } };
+  const now = ms(raw.now) ?? Date.now();
+  const since = raw.since == null ? null : ms(raw.since);
+
+  const candidates = [];
+  for (const thread of Array.isArray(raw.threads) ? raw.threads : []) {
+    const at = ms(thread?.endedAt);
+    const title = clean(thread?.title);
+    if (at == null || !title) continue;
+    const asks = (Array.isArray(thread.asks) ? thread.asks : []).map(clean).filter(Boolean);
+    candidates.push({
+      kind: 'thread', agent: 'assistant', at, title: clipLabel(title), asks: asks.slice(-2),
+      ids: [thread.memoryId].filter(Boolean).map(String), key: `thread:${thread.sessionId || thread.memoryId || title}`,
+      open: (Array.isArray(thread.open) ? thread.open : []).map((item) => wholeItem(clean(item))).filter((item) => item.text),
+    });
+  }
+  for (const session of Array.isArray(raw.sessions) ? raw.sessions : []) {
+    const at = ms(session?.at);
+    const title = clean(session?.title);
+    if (at == null || !title) continue;
+    candidates.push({
+      kind: 'session', agent: session.agent || null, at, title: clipLabel(title), source: session.source || 'summary',
+      detail: wholeOrNothing(clean(session.summary), FACTS.excerptChars), quoted: session.source === 'capture',
+      ids: [session.id].filter(Boolean).map(String), key: `session:${session.sessionId || session.id || title}`,
+      // What a session summary lists as open: each said whole (its leading sentences) or left out.
+      open: (Array.isArray(session.open) ? session.open : []).map((item) => ({ text: wholeOrNothing(clean(item), FACTS.excerptChars), cut: false })).filter((item) => item.text),
+    });
+  }
+  candidates.sort((a, b) => b.at - a.at);
+  const last = candidates[0] || null;
+
+  const open = [];
+  const seenOpen = new Set();
+  for (const candidate of candidates) {
+    for (const item of candidate.open) {
+      const key = item.text.toLowerCase();
+      if (seenOpen.has(key) || open.length >= FACTS.openItems) continue;
+      seenOpen.add(key);
+      open.push({ text: item.text, cut: item.cut, ids: candidate.ids });
+    }
+  }
+
+  const memories = (Array.isArray(raw.memories) ? raw.memories : []).map((memory) => {
+    const title = clean(memory?.title);
+    if (!memory?.id || !title) return null;
+    return { id: String(memory.id), title: clipLabel(title), excerpt: wholeOrNothing(clean(memory.excerpt), FACTS.excerptChars), category: memory.category || null, at: ms(memory.at) };
+  }).filter(Boolean).slice(0, FACTS.memories);
+
+  const rank = (status) => (PROBLEMS.has(status) ? 0 : status === 'running' ? 1 : status === 'stopped' ? 3 : 2);
+  const allRuns = (Array.isArray(raw.runs) ? raw.runs : []).map((run) => {
+    const title = clean(run?.title);
+    if (!run?.runId || !title) return null;
+    return { runId: String(run.runId), title: clipLabel(title), status: runStatus(run), provider: run.provider || null, at: ms(run.finishedAt) };
+  }).filter(Boolean).sort((a, b) => rank(a.status) - rank(b.status) || (b.at ?? 0) - (a.at ?? 0));
+  const runCounts = {
+    total: allRuns.length,
+    done: allRuns.filter((run) => run.status === 'done').length,
+    problems: allRuns.filter((run) => PROBLEMS.has(run.status)).length,
+    running: allRuns.filter((run) => run.status === 'running').length,
+    stopped: allRuns.filter((run) => run.status === 'stopped').length,
+  };
+
+  const schedules = (Array.isArray(raw.schedules) ? raw.schedules : []).map((schedule) => {
+    const name = clean(schedule?.name);
+    if (!name) return null;
+    return { id: String(schedule.id || name), name: clipLabel(name), result: clipLabel(clean(schedule.result) || 'did not complete', 80), at: ms(schedule.at) };
+  }).filter(Boolean).slice(0, FACTS.schedules);
+
+  const elsewhere = (Array.isArray(raw.elsewhere) ? raw.elsewhere : []).map((item) => {
+    const label = clean(item?.label || item?.project);
+    const runs = Math.max(0, Math.round(Number(item?.runs) || 0));
+    const failedSchedules = Math.max(0, Math.round(Number(item?.schedules) || 0));
+    if (!label || runs + failedSchedules === 0) return null;
+    return { project: String(item.project || label), label, runs, schedules: failedSchedules };
+  }).filter(Boolean).slice(0, FACTS.elsewhere);
+
+  // `known` false: the branch was read but `git status` gave no answer in time (nothing is claimed about changes).
+  const branch = clean(raw.git?.branch);
+  const git = branch ? { branch, dirty: Math.max(0, Math.round(Number(raw.git.dirty) || 0)), known: raw.git.dirty != null } : null;
+
+  const owner = {
+    notes: (Array.isArray(raw.owner?.notes) ? raw.owner.notes : []).map(clean).filter(Boolean).slice(0, FACTS.ownerNotes),
+    noteIds: (Array.isArray(raw.owner?.noteIds) ? raw.owner.noteIds : []).map(String).slice(0, FACTS.ownerNotes),
+    words: (Array.isArray(raw.owner?.words) ? raw.owner.words : []).map((text) => clipLabel(clean(text), TEXT.quoteChars)).filter(Boolean).slice(-FACTS.ownerWords),
+  };
+
+  const runs = allRuns.slice(0, FACTS.runs);
+  const substantive = !!last || open.length > 0 || allRuns.length > 0 || schedules.length > 0 || elsewhere.length > 0;
+  return {
+    project: String(raw.project || 'global'), label: clean(raw.label) || String(raw.project || 'global'),
+    now, since, lastAt: last?.at ?? null,
+    last, open, memories, runs, runCounts, schedules, elsewhere, git, owner, substantive,
+  };
+}
+
+/**
+ * Changes only when there is something new to say: the last work, what is open, runs and their
+ * outcomes, schedules that did not complete, failures elsewhere. The working tree is not news
+ * (gitKey): a commit made in a terminal must not greet a person twice.
+ */
+export function fingerprint(facts) {
+  if (!facts) return '';
+  const parts = {
+    last: facts.last ? `${facts.last.key}@${Math.floor(facts.last.at / 60_000)}` : null,
+    open: facts.open.map((item) => item.text),
+    runs: facts.runs.map((run) => `${run.runId}:${run.status}`),
+    counts: facts.runCounts,
+    schedules: facts.schedules.map((schedule) => `${schedule.id}:${schedule.at ?? ''}:${schedule.result}`),
+    elsewhere: facts.elsewhere.map((item) => `${item.project}:${item.runs}:${item.schedules}`),
+  };
+  return createHash('sha1').update(JSON.stringify(parts)).digest('hex').slice(0, 16);
+}
+
+/**
+ * The working tree a prepared sentence may have described: branch and whether anything is
+ * uncommitted. null when unknown (no repository, or `git status` did not answer in time).
+ */
+export function gitKey(facts) {
+  if (!facts?.git) return 'none';
+  if (!facts.git.known) return null;
+  return `${facts.git.branch}:${facts.git.dirty > 0 ? 'dirty' : 'clean'}`;
+}
+
+/**
+ * Is this opening a return worth a greeting?
+ * → { greet, reason }: 'off' | 'first-session' | 'recent' | 'nothing-to-say' | 'nothing-new' | 'return' | 'forced'
+ */
+export function decide({ enabled = true, facts = null, now = Date.now(), since = null, shownFingerprint = null, forced = false, gapMs = RETURN.gapMs } = {}) {
+  if (!enabled) return { greet: false, reason: 'off' };
+  if (!facts || !facts.substantive) return { greet: false, reason: since == null ? 'first-session' : 'nothing-to-say' };
+  if (forced) return { greet: true, reason: 'forced' };
+  if (since == null) return { greet: false, reason: 'first-session' };
+  if (now - since < gapMs) return { greet: false, reason: 'recent' };
+  if (shownFingerprint && shownFingerprint === fingerprint(facts)) return { greet: false, reason: 'nothing-new' };
+  return { greet: true, reason: 'return' };
+}
+
+/** "blocked: Title (note)" → "Still blocked: Title (note)."; anything else → "Still open: …". */
+function openSentence(text) {
+  const item = String(text).replace(/[.]+$/, '');
+  const status = /^(blocked|failed|interrupted|needs input):\s*(.+)$/i.exec(item);
+  return status ? `Still ${status[1].toLowerCase()}: ${status[2]}.` : `Still open: ${item}.`;
+}
+
+function lastSentence(last) {
+  if (!last) return '';
+  if (last.kind === 'thread') return `Last conversation here: “${last.title}”.`;
+  if (last.quoted) return `Last asked here: “${last.title}”.`;
+  return `Last session here: ${last.title.replace(/[.!?…]+$/, '')}.`;
+}
+
+/**
+ * The line used when the writer is not (no Claude login, a timeout, an unusable reply, a preparation
+ * that is out of date): at most two short sentences from the same facts, in English. What needs the
+ * person comes first; a sentence that does not fit is left out, never cut.
+ */
+export function fallbackLine(facts, { maxChars = TEXT.maxChars, maxSentences = TEXT.maxSentences } = {}) {
+  if (!facts?.substantive) return '';
+  const candidates = []; // { order, priority, text }
+  const problems = facts.runs.filter((run) => PROBLEMS.has(run.status));
+  const news = [];
+  if (problems.length === 1) news.push(`“${problems[0].title}” ${STATUS_WORDS[problems[0].status]}`);
+  else if (facts.runCounts.problems > 1) news.push(`${plural(facts.runCounts.problems, 'run')} need a look`);
+  for (const schedule of facts.schedules.slice(0, 1)) news.push(`the schedule “${schedule.name}” did not complete`);
+  if (facts.schedules.length > 1) news.push(`${plural(facts.schedules.length - 1, 'other schedule')} did not complete`);
+  if (news.length) candidates.push({ order: 2, priority: 0, text: `While you were away: ${news.join('; ')}.` });
+
+  const open = facts.open.filter((item) => !item.cut);
+  if (open.length) candidates.push({ order: 1, priority: 1, text: openSentence(open[0].text) });
+  if (facts.last) candidates.push({ order: 0, priority: 3, text: lastSentence(facts.last) });
+
+  if (!news.length && facts.runCounts.done + facts.runCounts.running > 0) {
+    const bits = [];
+    if (facts.runCounts.done) bits.push(`${plural(facts.runCounts.done, 'run')} finished`);
+    if (facts.runCounts.running) bits.push(`${plural(facts.runCounts.running, 'run')} still going`);
+    // What happened while they were away is the news; where they left off is the context for it.
+    candidates.push({ order: 2, priority: 2, text: `While you were away: ${bits.join(', ')}.` });
+  }
+  if (facts.elsewhere.length) {
+    const item = facts.elsewhere[0];
+    const what = [item.runs ? plural(item.runs, 'failed run') : null, item.schedules ? plural(item.schedules, 'schedule that did not complete', 'schedules that did not complete') : null].filter(Boolean).join(' and ');
+    candidates.push({ order: 3, priority: 4, text: `Elsewhere: ${what} in ${item.label}.` });
+  }
+  if (facts.git?.known && facts.git.dirty > 0) candidates.push({ order: 4, priority: 5, text: `${plural(facts.git.dirty, 'uncommitted file')} on ${facts.git.branch}.` });
+
+  const picked = [];
+  for (const candidate of [...candidates].sort((a, b) => a.priority - b.priority)) {
+    if (picked.length >= maxSentences) break;
+    const length = [...picked, candidate].reduce((total, item) => total + item.text.length + 1, -1);
+    if (length > maxChars) continue;
+    picked.push(candidate);
+  }
+  return picked.sort((a, b) => a.order - b.order).map((item) => item.text).join(' ');
+}
+
+/** The rows of the "Based on" disclosure: which records a greeting was built from. */
+export function basisOf(facts) {
+  if (!facts) return [];
+  const rows = [];
+  const iso = (at) => (at == null ? null : new Date(at).toISOString());
+  if (facts.last) rows.push({ kind: facts.last.kind, label: facts.last.title, id: facts.last.ids[0] || null, at: iso(facts.last.at), agent: facts.last.agent });
+  for (const item of facts.open) rows.push({ kind: 'open', label: item.text, id: item.ids[0] || null, at: null });
+  for (const memory of facts.memories) rows.push({ kind: 'memory', label: memory.title, id: memory.id, at: iso(memory.at) });
+  for (const run of facts.runs) rows.push({ kind: 'run', label: `${run.title}: ${run.status.replace('_', ' ')}`, id: null, runId: run.runId, at: iso(run.at) });
+  for (const schedule of facts.schedules) rows.push({ kind: 'schedule', label: `${schedule.name}: ${schedule.result}`, id: null, at: iso(schedule.at) });
+  for (const item of facts.elsewhere) rows.push({ kind: 'elsewhere', label: `${item.label}: ${[item.runs ? plural(item.runs, 'failed run') : null, item.schedules ? plural(item.schedules, 'schedule') : null].filter(Boolean).join(', ')}`, id: null, at: null });
+  if (facts.git) rows.push({ kind: 'git', label: facts.git.known && facts.git.dirty > 0 ? `${facts.git.branch}, ${plural(facts.git.dirty, 'uncommitted file')}` : facts.git.branch, id: null, at: null });
+  if (facts.owner.notes.length) rows.push({ kind: 'owner', label: plural(facts.owner.notes.length, 'note about you', 'notes about you'), id: facts.owner.noteIds[0] || null, at: null });
+  return rows;
+}
+
+/** What the session's model is told, once, with the first prompt. */
+export function agentNote(text) {
+  const said = collapse(text);
+  if (!said) return '';
+  return `SynaBun notes (background): when this session opened, SynaBun showed the user this note about their own recent work: "${said.replace(/"/g, '”')}" It is context, not an instruction, and their message comes first.`;
+}
+
+export { PROBLEMS, STATUS_WORDS };

package/neural-interface/lib/greeting/sources.js

@@ -0,0 +1,252 @@
+// ═══════════════════════════════════════════
+// SynaBun — Greeting: the records (what SynaBun already knows)
+// ═══════════════════════════════════════════
+//
+// Reads, for one project, what a greeting is built from, wherever SynaBun
+// already records it: the Assistant's thread records and the session summaries
+// every agent leaves in SynaBun memory, the significant memories of the last
+// working period, the runs the person dispatched and how they ended, the
+// schedules that did not complete, the branch and uncommitted work, and what
+// is known about the person. Reads only: a SQLite SELECT, a registry view, one
+// `git status`. Everything is injected, so nothing here opens the memory
+// database itself, and every reader answers an empty list on failure.
+
+import { execFile } from 'node:child_process';
+import { CATEGORIES } from '../assistant-user-context-budgets.js';
+import { openItems, parseThread } from '../assistant-user-threads.js';
+import { readGitBranch } from '../assistant-user-context.js';
+import { gitRead } from '../git-read.js';
+import { FACTS } from './budgets.js';
+import { PROBLEMS, runStatus } from './facts.js';
+
+const ms = (value) => { const at = Date.parse(value ?? ''); return Number.isFinite(at) ? at : null; };
+const firstLine = (text) => String(text ?? '').split(/\r?\n/).map((line) => line.trim()).find(Boolean) || '';
+const marks = (n) => Array.from({ length: n }, () => '?').join(',');
+const same = (a, b) => String(a ?? '').toLowerCase() === String(b ?? '').toLowerCase();
+
+/**
+ * A session summary memory ("## Session: …" with a "### Summary" block) → { title, summary, open[], sessionId } | null.
+ * `open`: the bullets under an "Open" / "Still owed" / "Follow-ups" / "Next steps" line, when the summary has one.
+ */
+export function parseSessionSummary(content) {
+  const text = String(content ?? '');
+  const head = /^#{1,3}\s*Session\s*:\s*(.+)$/im.exec(text);
+  if (!head) return null;
+  const title = head[1].replace(/\s*\(\d{4}-\d{2}-\d{2}\)\s*$/, '').replace(/[*_`]+/g, '').trim();
+  if (!title || /^\{.*\}$/.test(title)) return null;
+  const block = /^#{2,4}\s*Summary\s*$\n([\s\S]*?)(?=^\s*#{2,4}\s|\s*$(?![\s\S]))/im.exec(text);
+  const summary = block ? block[1].replace(/\s+/g, ' ').replace(/[*_`]+/g, '').trim() : '';
+  const session = /\*\*Session ID\*\*\s*:\s*([A-Za-z0-9_-]{6,})/.exec(text);
+  const owed = /^(?:#{2,4}\s*)?(?:open(?:\s+(?:at|items?)\b[^\n:]*)?|still\s+(?:open|owed)[^\n:]*|follow[- ]?ups?|next\s+steps?|pending)\s*:?\s*$\n((?:[ \t]*[-*][ \t]+.+(?:\n|$))+)/im.exec(text);
+  const open = owed ? owed[1].split('\n').map((line) => line.replace(/^[ \t]*[-*][ \t]+/, '').replace(/\s+/g, ' ').replace(/[*_`]+/g, '').trim()).filter(Boolean).slice(0, 4) : [];
+  return { title, summary, open, sessionId: session ? session[1] : null };
+}
+
+/**
+ * `git status --porcelain` → the number of changed and untracked paths, or null (not a repository, too slow).
+ * Run as lib/git-read.js runs a read: nothing the project's own git configuration names is started for it.
+ */
+export function gitDirtyCount(cwd, { timeoutMs = 1500, run = execFile } = {}) {
+  return new Promise((done) => {
+    if (!cwd) return done(null);
+    gitRead(cwd, ['status', '--porcelain']).then((read) => {
+      run('git', read.args, { cwd, env: read.env, timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024, windowsHide: true }, (error, stdout) => {
+        if (error) return done(null);
+        done(String(stdout || '').split('\n').filter((line) => line.trim()).length);
+      });
+    }).catch(() => done(null));
+  });
+}
+
+/**
+ * @param {object} deps
+ * @param {() => object} deps.getDb                       node:sqlite handle of the memory database
+ * @param {() => object[]} [deps.listRuns]                the dispatcher's run views (assistant-dispatch.js list())
+ * @param {() => object[]} [deps.listSchedules]           loop schedules ({ id, name, enabled, lastRun, lastRunResult })
+ * @param {() => {path:string,label:string}[]} [deps.projects]   the project registry
+ * @param {(cwd:string) => string} [deps.detectProject]   a directory's memory project
+ * @param {() => string[]} [deps.sessionCategories]       where session summaries are filed ("conversations" and its children)
+ * @param {(project:string) => {id:string,statement:string}[]} [deps.knowledge]  what is known about the person, ranked
+ * @param {() => object[]} [deps.workingThreads]          the user-context engine's working threads (newer than their memory)
+ * @param {(cwd:string) => Promise<number|null>} [deps.gitDirty]
+ */
+export function createGreetingSources({
+  getDb, listRuns = () => [], listSchedules = () => [], projects = () => [], detectProject = () => 'global',
+  sessionCategories = () => ['conversations'], knowledge = () => [], workingThreads = () => [],
+  gitDirty = gitDirtyCount, readBranch = readGitBranch, log = () => {},
+} = {}) {
+  const safe = (fn, fallback) => { try { const value = fn(); return value == null ? fallback : value; } catch (error) { log('greeting:source-error', error?.message || String(error)); return fallback; } };
+  const normalize = (label) => String(label || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+  /** The registry entry of a project key: { key, label, path } (label and path null when unregistered). */
+  function projectInfo(project) {
+    const key = String(project || 'global');
+    for (const entry of safe(() => projects(), [])) {
+      if (!entry?.path) continue;
+      const detected = safe(() => detectProject(entry.path), null);
+      if (same(detected, key) || same(normalize(entry.label), key)) return { key, label: String(entry.label || key), path: String(entry.path) };
+    }
+    return { key, label: key, path: null };
+  }
+  function projectOf(cwd) {
+    const key = cwd ? safe(() => detectProject(String(cwd)), 'global') : 'global';
+    return String(key || 'global');
+  }
+
+  function threadRows(project) {
+    const out = [];
+    const seen = new Set();
+    // A working thread is newer than its own memory (which is written 45 s after a turn).
+    for (const thread of safe(() => workingThreads(), [])) {
+      if (!thread?.sessionId || !(Number(thread.prompts) > 0) || !same(thread.project || 'global', project)) continue;
+      seen.add(String(thread.sessionId));
+      out.push({
+        memoryId: thread.memoryId || null, sessionId: String(thread.sessionId), title: thread.title || 'Untitled', endedAt: thread.lastAt || thread.startedAt,
+        asks: (thread.asks || []).map((ask) => ask?.text || '').filter(Boolean),
+        open: safe(() => openItems(thread).map((item) => item.text), []),
+      });
+    }
+    const rows = safe(() => getDb().prepare(`SELECT id, content, project, updated_at FROM memories
+      WHERE trashed_at IS NULL AND category = ? AND lower(project) = lower(?) ORDER BY updated_at DESC LIMIT ?`).all(CATEGORIES.threads, project, FACTS.threads + 2), []);
+    for (const row of rows) {
+      const parsed = safe(() => parseThread(row.content, { updatedAt: row.updated_at }), null);
+      if (!parsed || !(parsed.prompts > 0) || (parsed.sessionId && seen.has(parsed.sessionId))) continue;
+      out.push({ memoryId: String(row.id), sessionId: parsed.sessionId, title: parsed.title, endedAt: parsed.endedAt || row.updated_at, asks: parsed.asks, open: parsed.open });
+    }
+    return out.sort((a, b) => (ms(b.endedAt) ?? 0) - (ms(a.endedAt) ?? 0)).slice(0, FACTS.threads);
+  }
+
+  function summaryRows(project) {
+    const categories = [...new Set(safe(() => sessionCategories(), ['conversations']).map(String).filter((name) => name && name !== CATEGORIES.threads))];
+    if (!categories.length) return [];
+    const rows = safe(() => getDb().prepare(`SELECT id, content, created_at FROM memories
+      WHERE trashed_at IS NULL AND category IN (${marks(categories.length)}) AND lower(project) = lower(?) ORDER BY created_at DESC LIMIT ?`).all(...categories, project, FACTS.sessions * 3), []);
+    const out = [];
+    for (const row of rows) {
+      const parsed = parseSessionSummary(row.content);
+      if (!parsed) continue;
+      out.push({ id: String(row.id), sessionId: parsed.sessionId, title: parsed.title, summary: parsed.summary, open: parsed.open, at: row.created_at, agent: null, source: 'summary' });
+      if (out.length >= FACTS.sessions) break;
+    }
+    return out;
+  }
+
+  /** Significant memories written around the last working period (not the knowledge or thread records themselves). */
+  function memoryRows(project, { from, to, exclude = [] }) {
+    if (from == null) return [];
+    const skip = [...new Set([CATEGORIES.threads, CATEGORIES.knowledge, CATEGORIES.knowledgeParent, ...exclude])];
+    const rows = safe(() => getDb().prepare(`SELECT id, content, category, importance, created_at FROM memories
+      WHERE trashed_at IS NULL AND lower(project) = lower(?) AND importance >= ? AND created_at >= ? AND created_at <= ?
+        AND category NOT IN (${marks(skip.length)}) ORDER BY importance DESC, created_at DESC LIMIT ?`)
+      .all(project, FACTS.memoryImportance, new Date(from).toISOString(), new Date(to).toISOString(), ...skip, FACTS.memories), []);
+    return rows.map((row) => ({ id: String(row.id), title: firstLine(row.content).replace(/^#+\s*/, ''), excerpt: String(row.content || '').replace(/^#+\s*/gm, ''), category: row.category, importance: row.importance, at: row.created_at }));
+  }
+
+  function runRows(project, { since, now }) {
+    const floor = Math.max(since ?? 0, now - FACTS.newsWindowMs);
+    const here = [];
+    for (const run of safe(() => listRuns(), [])) {
+      if (!run?.runId || run.removed || !same(run.project || 'global', project)) continue;
+      const finished = ms(run.finishedAt || run.completedAt);
+      if (run.active === true) { if ((ms(run.createdAt) ?? 0) >= floor) here.push(run); continue; }
+      if (finished != null && finished > floor && finished <= now) here.push(run);
+    }
+    return here.map((run) => ({ runId: run.runId, title: run.title || run.task || 'Untitled run', state: run.state, outcome: run.outcome, active: run.active === true, finishedAt: run.finishedAt || run.completedAt || null, provider: run.provider || null }));
+  }
+
+  /** Failures in other projects since the person was last anywhere: counts per project, never a detail. */
+  function elsewhereRows(project, { globalSince, now, told = new Set() }) {
+    const floor = Math.max(globalSince ?? 0, now - FACTS.newsWindowMs);
+    const byProject = new Map();
+    const keys = [];
+    for (const run of safe(() => listRuns(), [])) {
+      if (!run?.runId || run.removed || run.active === true || same(run.project || 'global', project)) continue;
+      const finished = ms(run.finishedAt || run.completedAt);
+      if (finished == null || finished <= floor || finished > now) continue;
+      const status = runStatus(run);
+      if (status !== 'failed' && status !== 'interrupted' && !PROBLEMS.has(status)) continue;
+      const key = `run:${run.runId}`;
+      if (told.has(key)) continue;
+      const name = String(run.project || 'global');
+      const entry = byProject.get(name.toLowerCase()) || { project: name, label: projectInfo(name).label, runs: 0, schedules: 0 };
+      entry.runs += 1;
+      byProject.set(name.toLowerCase(), entry);
+      keys.push(key);
+    }
+    return { rows: [...byProject.values()].sort((a, b) => b.runs - a.runs), keys };
+  }
+
+  /** Enabled schedules whose last run, since the person was last anywhere, did not complete. */
+  function scheduleRows({ globalSince, now, told = new Set() }) {
+    const floor = Math.max(globalSince ?? 0, now - FACTS.newsWindowMs);
+    const rows = [];
+    for (const schedule of safe(() => listSchedules(), [])) {
+      if (!schedule?.id || schedule.enabled === false) continue;
+      const at = ms(schedule.lastRun);
+      const result = String(schedule.lastRunResult ?? '').trim();
+      if (at == null || at <= floor || at > now || !result || result === 'completed' || result === 'launched') continue;
+      const key = `schedule:${schedule.id}:${schedule.lastRun}`;
+      if (told.has(key)) continue;
+      rows.push({ id: String(schedule.id), name: schedule.name || String(schedule.id), result: firstLine(result), at: schedule.lastRun, key });
+    }
+    return rows.sort((a, b) => (ms(b.at) ?? 0) - (ms(a.at) ?? 0));
+  }
+
+  /**
+   * Everything facts.js needs for one project.
+   * `since`: the person's last message in the project (ms) or null; `globalSince`: anywhere.
+   * `activity`: the engine's own record of their last prompts per surface ([{ surface, at, words }]).
+   * → the raw input of buildFacts, plus `toldKeys` (the unscoped news in it, said once).
+   */
+  async function collect(project, { since = null, globalSince = null, now = Date.now(), activity = [], told = new Set(), gitTimeoutMs = 1500 } = {}) {
+    const info = projectInfo(project);
+    const threads = threadRows(info.key);
+    const sessions = summaryRows(info.key);
+    for (const entry of Array.isArray(activity) ? activity : []) {
+      // The person's own last words on a surface that leaves no thread record of its own.
+      if (!entry?.words || entry.surface === 'assistant' || ms(entry.at) == null) continue;
+      sessions.push({ id: null, sessionId: `${entry.surface}:${entry.at}`, title: entry.words, summary: '', at: entry.at, agent: entry.agent || null, source: 'capture' });
+    }
+    const lastAt = Math.max(...[...threads.map((thread) => ms(thread.endedAt)), ...sessions.map((session) => ms(session.at))].filter((at) => at != null), 0) || null;
+    const anchor = since ?? lastAt;
+    const memories = anchor == null ? [] : memoryRows(info.key, { from: anchor - FACTS.memoryWindowMs, to: now, exclude: safe(() => sessionCategories(), []) });
+    const runs = anchor == null ? [] : runRows(info.key, { since: anchor, now });
+    const schedules = scheduleRows({ globalSince: globalSince ?? anchor, now, told });
+    const elsewhere = elsewhereRows(info.key, { globalSince: globalSince ?? anchor, now, told });
+    let git = null;
+    if (info.path) {
+      const branch = safe(() => readBranch(info.path), null);
+      // dirty null: `git status` gave no answer in time, so nothing is claimed about changes.
+      if (branch) git = { branch, dirty: await Promise.resolve(gitDirty(info.path, { timeoutMs: gitTimeoutMs })).catch(() => null) };
+    }
+    const known = safe(() => knowledge(info.key), []).filter((row) => row?.statement).slice(0, FACTS.ownerNotes);
+    const words = threads[0]?.asks?.length ? threads[0].asks.slice(-FACTS.ownerWords) : sessions.filter((session) => session.source === 'capture').map((session) => session.title).slice(0, FACTS.ownerWords);
+    return {
+      project: info.key, label: info.label, now, since: since ?? null,
+      threads, sessions, memories, runs,
+      schedules: schedules.map(({ key: _key, ...rest }) => rest),
+      elsewhere: elsewhere.rows,
+      git,
+      owner: { notes: known.map((row) => row.statement), noteIds: known.map((row) => String(row.id)), words },
+      toldKeys: [...schedules.map((row) => row.key), ...elsewhere.keys],
+      lastAt,
+    };
+  }
+
+  /** When the person last worked in a project, from the records alone (an engine with no activity of its own yet). */
+  function lastWorkAt(project) {
+    const info = projectInfo(project);
+    const times = [...threadRows(info.key).map((thread) => ms(thread.endedAt)), ...summaryRows(info.key).map((session) => ms(session.at))].filter((at) => at != null);
+    return times.length ? Math.max(...times) : null;
+  }
+
+  /** The projects with the newest thread records and session summaries (boot: what to prepare first). */
+  function recentProjects({ limit = 6 } = {}) {
+    const categories = [...new Set([CATEGORIES.threads, ...safe(() => sessionCategories(), ['conversations'])])];
+    const rows = safe(() => getDb().prepare(`SELECT lower(project) AS project, MAX(updated_at) AS at FROM memories
+      WHERE trashed_at IS NULL AND category IN (${marks(categories.length)}) GROUP BY lower(project) ORDER BY at DESC LIMIT ?`).all(...categories, limit), []);
+    return rows.map((row) => String(row.project || 'global')).filter(Boolean);
+  }
+
+  return { projectInfo, projectOf, collect, lastWorkAt, recentProjects };
+}