honestweek 0.2.0 → 0.3.0

package/lib/saved/checks.mjs

@@ -0,0 +1,381 @@
+// lib/saved/checks.mjs: the Problems checks' results, saved day by day (issue 151, first part).
+//
+// When "saveResults" is on, `honestweek view` saves what the checks found once the whole window
+// has loaded: one file per day, checks/<day>.json in the saved folder (lib/saved/store.mjs),
+// holding the sessions that started that day in the config's timezone. A session belongs to the
+// day it started, whole, even when it runs past midnight. Each session says whether the checks
+// read it (only sessions in configured repositories are), and each finding keeps the evidence
+// word it had. A session in a display-only repository or a folder outside the config keeps only
+// its id, its times and that it wasn't checked: no title, no repository, no finding.
+//
+// A later run replaces each day it covers, keeping any saved session it didn't read: that
+// session's log is gone, or was moved, and what was saved is all there is of it. Days older than
+// "keepDays" are deleted as it saves.
+//
+// Nothing saved is raw: every string passed the full redactor before it was written, and passes
+// it again, with the reading run's settings, every time it's read, so a private word added later
+// is hidden in old days too. A log's own session id is kept only as a hash (idHashOf), and a log
+// file only as the hash of its path (pathKey), which is enough to tell whether it's still on disk.
+//
+// `honestweek problems --session <id>` reads these for a session that isn't in its window,
+// through findSaved and savedSessionAnswer.
+//
+// Zero runtime dependencies: Node built-ins only.
+
+import { createRedactor } from '../redact.mjs';
+import { letterHash, pathKey as pathKeyOf } from '../replay/ids.mjs';
+import { fileFingerprint } from '../replay/saved-sessions.mjs';
+import { localDay } from '../replay/views.mjs';
+import { RULES as ENGINE_RULES } from '../replay/classify.mjs';
+import { LAUNCH_RULES } from '../replay/launch.mjs';
+import { isSure, RULES as CHECK_RULES, weakest } from '../problems/index.mjs';
+import { redactAnswer } from '../view/problems-route.mjs';
+import { sessionGroup } from '../view/replay-export.mjs';
+import { localDateRangeInstants } from '../resolve-week.mjs';
+import { THRESHOLDS } from '../problems/context.mjs';
+import { honestweekVersion, idHashOf, keptFrom, logKeys, logPaths, pruneSaved, readSaved, redactionPrint, savedDays, SAVED_SCHEMA, writeSaved } from './store.mjs';
+
+/** A fingerprint of the config settings the checks read (the long-session limit): findings saved
+ *  under other settings aren't taken back for sessions whose logs are still on disk. */
+export function checksPrint(config) {
+  return letterHash(`checks\u0000${JSON.stringify({ longSessionTokens: Number.isInteger(config?.longSessionTokens) ? config.longSessionTokens : null })}`, 16);
+}
+
+/** Whether a saved session had been quiet for THRESHOLDS.stillRunningMs when its checks ran, so
+ *  none of its findings was softened for a session that may still be running. */
+export const settledWhenChecked = (s, last) => Number.isFinite(s?.checkedAt) && Number.isFinite(last) && s.checkedAt - last >= THRESHOLDS.stillRunningMs;
+
+/** The sub-folder of the saved folder that holds the check results. */
+export const CHECKS_SUB = 'checks';
+/** The shortest start of a session's key a saved lookup reads as that key (as in view's data). */
+export const SAVED_PREFIX_MIN = 8;
+
+/** Saved fields whose value is honestweek's own id, hash, time, date or word: kept when it has
+ *  that shape, and redacted like any other string when it doesn't. */
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+const SHAPES = {
+  idHash: /^[a-p]{24}$/,
+  files: /^f-[a-p]{12}$/,
+  file: /^f-[a-p]{12}$/,
+  head: /^[a-p]{16}$/,
+  redaction: /^[a-p]{16}$/,
+  checks: /^[a-p]{16}$/,
+  days: DAY,
+  day: DAY,
+  savedAt: ISO,
+  firstAt: ISO,
+  version: /^[0-9A-Za-z][0-9A-Za-z.+-]{0,39}$/,
+  tool: /^(?:claude-code|codex)$/,
+  group: /^(?:configured|display|outside)$/,
+  status: /^(?:found|clear|unchecked|undetectable)$/,
+  ran: /^[a-z0-9][a-z0-9-]{0,63}$/,
+  severity: /^(?:look|note)$/,
+  verdictEvidence: /^(?:recorded|derived|inferred|missing|ambiguous)$/,
+  level: /^(?:recorded|derived|inferred|missing|ambiguous)$/,
+};
+
+/**
+ * Every string in a saved value through `redact`, except one under a key above with that key's
+ * shape, and the ids, times and dates redactAnswer keeps (lib/view/problems-route.mjs). Keys are
+ * this file's own names, never log text, so they stay as they are.
+ */
+export function redactSaved(value, redact, key = null, depth = 0) {
+  if (depth > 40) return null;
+  if (typeof value === 'string' && SHAPES[key]?.test(value)) return value;
+  if (Array.isArray(value)) return value.map((v) => redactSaved(v, redact, key, depth + 1));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = redactSaved(v, redact, k, depth + 1);
+    return out;
+  }
+  return redactAnswer(value, redact, key, depth);
+}
+
+const ALL_RULES = new Map([...ENGINE_RULES, ...LAUNCH_RULES, ...Object.entries(CHECK_RULES)]);
+const ruleIdsIn = (text) => (typeof text === 'string' ? text.split(/[^A-Za-z0-9._-]+/).filter((id) => ALL_RULES.has(id)) : []);
+
+/** A finding as it's saved: every field its check recorded, its step described from this build. */
+function savedFinding(f, key, describeStep) {
+  // Every field the check recorded, so a saved finding answers as the live one did, plus its key and
+  // its step as this build described it.
+  const out = {};
+  for (const [k, v] of Object.entries(f)) if (!k.startsWith('_') && v !== undefined) out[k] = v;
+  return { ...out, key: key ?? null, text: f.event ? describeStep(f.event) : null };
+}
+
+/**
+ * saveChecks({ dir, configDir, config, h, result, keys, describeStep, keepDays, now }) ->
+ *   { days, sessions, findings, pruned }
+ *   h             the window's redacted history (the build the checks read)
+ *   result, keys  runProblems(h) and each finding's key (lib/view/problems-route.mjs)
+ *   describeStep  event id -> the step's description in this build, or null
+ * Saves each day of h's window, from its first day to its last. Throws only when the folder
+ * can't be written; the caller says so and the page goes on.
+ */
+export function saveChecks({ dir, config, h, result, keys = new Map(), describeStep = () => null, keepDays, builtT = null, now = Date.now() }) {
+  const tz = h.window.timezone;
+  const { from, to } = h.window;
+  const redactor = createRedactor(config);
+  const redact = (s) => redactor.redact(String(s));
+  const savedAt = new Date(now).toISOString();
+  const version = honestweekVersion();
+  const redaction = redactionPrint(config);
+  const ownIds = new Map([...(h.claudeIds ?? new Map()), ...(h.codexIds ?? new Map())]);
+  const filesOf = new Map();
+  for (const [src, file] of h.sourceFiles ?? new Map()) {
+    const s = h.sourceSession?.get(src);
+    if (!s) continue;
+    if (!filesOf.has(s)) filesOf.set(s, new Set());
+    filesOf.get(s).add(file);
+  }
+  // The days each session has a step on, for the per-day counts a later trend reads.
+  const daysOf = new Map();
+  for (const e of h.events) {
+    if (!e.session || !Number.isFinite(e.t) || e.t < h.window.startT || e.t >= h.window.endT) continue;
+    if (!daysOf.has(e.session)) daysOf.set(e.session, new Set());
+    daysOf.get(e.session).add(localDay(e.t, tz));
+  }
+  // Each pattern's state in this window: found, clear, unchecked or undetectable.
+  // Each pattern's state in this window, and for one whose check counts tokens, how it counts them,
+  // so a later run that takes these sessions back unread can say the same.
+  const status = result.patterns.map((p) => ({ id: p.id, status: p.status, ran: p.measures.filter((m) => m.ran).map((m) => m.check), level: weakest(p.measures.filter((m) => m.ran).map((m) => m.evidence)), ...(p.tokens ? { tokens: { waste: p.tokens.waste, label: p.tokens.label, evidence: p.tokens.evidence } } : {}) }));
+  const findingsOf = new Map();
+  for (const p of result.patterns) {
+    for (const f of p.findings) {
+      if (!f.session) continue;
+      if (!findingsOf.has(f.session)) findingsOf.set(f.session, []);
+      findingsOf.get(f.session).push(savedFinding(f, keys.get(f) ?? null, describeStep));
+    }
+  }
+
+  const byDay = new Map();
+  for (const s of h.sessions) {
+    // A session that came back as saved, or unread because its logs hadn't changed, keeps the entry
+    // it was saved with.
+    if (!s.firstAt || s.saved || h.reusedSessions?.has(s.key)) continue;
+    const day = localDay(Date.parse(s.firstAt), tz);
+    if (day < from || day > to) continue;
+    const group = sessionGroup(s);
+    const checked = group === 'configured';
+    const id = ownIds.get(s.key);
+    const findings = checked ? findingsOf.get(s.key) ?? [] : [];
+    const entry = {
+      key: s.key,
+      idHash: idHashOf(id),
+      tool: s.tool ?? null,
+      group,
+      checked,
+      ...(checked ? { title: s.title ?? null, repo: typeof s.repo === 'string' ? s.repo : null } : {}),
+      firstAt: s.firstAt,
+      lastAt: s.lastAt ?? null,
+      days: [...(daysOf.get(s.key) ?? [])].sort(),
+      // The stretch of time the checks covered (this run's window), so a later run takes the session
+      // back unread only when its findings covered the whole session.
+      checks: checksPrint(config),
+      // When the checks ran: a session that wrote a record within THRESHOLDS.stillRunningMs of then
+      // had its last turn's findings softened to notes, which a later read wouldn't do.
+      checkedAt: Number.isFinite(builtT) ? builtT : null,
+      checkedFrom: h.window.startT,
+      checkedTo: h.window.endT,
+      files: [...(filesOf.get(s.key) ?? [])].map((f) => pathKeyOf(f)).filter(Boolean).sort(),
+      // Each of those files' fingerprint as the build read it, so a later trend can tell it hasn't changed.
+      prints: [...(filesOf.get(s.key) ?? [])].map((f) => ({ file: pathKeyOf(f), ...(h.sourcePrints?.get(f) ?? {}) })).filter((x) => x.file && Number.isFinite(x.size)).sort((a, b) => (a.file < b.file ? -1 : 1)),
+      findings: findings.length,
+      look: findings.filter((f) => f.severity === 'look').length,
+    };
+    if (!byDay.has(day)) byDay.set(day, { sessions: [], findings: [] });
+    byDay.get(day).sessions.push(entry);
+    byDay.get(day).findings.push(...findings);
+  }
+
+  let sessions = 0;
+  let findings = 0;
+  const days = [];
+  // A day already past keepDays isn't written: it would be deleted as soon as it was saved.
+  const today = localDay(now, tz);
+  const oldest = keptFrom(today, keepDays);
+  for (let day = from; day <= to; day = nextDay(day)) {
+    if (oldest && day < oldest) continue;
+    const fresh = byDay.get(day) ?? { sessions: [], findings: [] };
+    const had = readDay(dir, day);
+    // A session saved with a log file this run didn't read keeps its fuller saved entry (as in
+    // lib/saved/history.mjs), findings and all. Files are counted, not matched by path: a Codex
+    // log that was archived has moved, not shrunk, and its fresh entry replaces the saved one.
+    const oldFiles = new Map((had?.sessions ?? []).filter((s) => s && typeof s.key === 'string').map((s) => [s.key, Array.isArray(s.files) ? s.files : []]));
+    const partial = new Set(fresh.sessions.filter((s) => oldFiles.has(s.key) && oldFiles.get(s.key).length > s.files.length).map((s) => s.key));
+    if (partial.size) {
+      fresh.sessions = fresh.sessions.filter((s) => !partial.has(s.key));
+      fresh.findings = fresh.findings.filter((f) => !partial.has(f.session));
+    }
+    const freshKeys = new Set(fresh.sessions.map((s) => s.key));
+    // A session saved before that this run didn't read stays, with its findings, as it was saved.
+    const keptSessions = (had?.sessions ?? []).filter((s) => s && typeof s.key === 'string' && !freshKeys.has(s.key));
+    const keptKeys = new Set(keptSessions.map((s) => s.key));
+    const keptFindings = (had?.findings ?? []).filter((f) => keptKeys.has(f?.session));
+    const all = [...fresh.sessions.map((s) => ({ ...s, savedAt, version, ...(s.checked ? { status } : {}) })), ...keptSessions].sort((a, b) => String(a.firstAt).localeCompare(String(b.firstAt)) || (a.key < b.key ? -1 : 1));
+    const allFindings = [...fresh.findings, ...keptFindings];
+    // The text of each rule a finding names, as this version states it; a rule a kept finding names
+    // that this version no longer has keeps the text it was saved with.
+    const named = new Set(allFindings.flatMap((f) => ruleIdsIn(f.rule)));
+    const rules = [...named].sort().map((id) => ({ id, text: ALL_RULES.get(id) }));
+    for (const r of had?.rules ?? []) if (r && typeof r.id === 'string' && !ALL_RULES.has(r.id) && keptFindings.some((f) => String(f.rule ?? '').split(/[^A-Za-z0-9._-]+/).includes(r.id))) rules.push({ id: r.id, text: r.text });
+    const value = redactSaved({ schema: SAVED_SCHEMA, day, timezone: tz, savedAt, version, redaction, window: { from, to }, status, rules, sessions: all, findings: allFindings }, redact);
+    writeSaved(dir, [CHECKS_SUB, `${day}.json`], value);
+    days.push(day);
+    sessions += all.length;
+    findings += allFindings.length;
+  }
+  const pruned = pruneSaved(dir, CHECKS_SUB, { keepDays, today });
+  return { days, sessions, findings, pruned };
+}
+
+const nextDay = (day) => new Date(Date.parse(`${day}T00:00:00Z`) + 86400000).toISOString().slice(0, 10);
+
+
+/** One saved day, or null when it's missing or not the shape this file writes: a day that isn't
+ *  is replaced whole by the next save rather than stopping it. */
+function readDay(dir, day) {
+  const f = readSaved(dir, [CHECKS_SUB, `${day}.json`]);
+  return f && Array.isArray(f.sessions) && Array.isArray(f.findings) ? f : null;
+}
+
+/** Every saved session, newest day first: [{ day, session }]. */
+function savedSessions(dir) {
+  const out = [];
+  for (const day of savedDays(dir, CHECKS_SUB).reverse()) {
+    const f = readDay(dir, day);
+    for (const s of f?.sessions ?? []) if (s && typeof s.key === 'string') out.push({ day, session: s });
+  }
+  return out;
+}
+
+/**
+ * findSaved(dir, text) -> { key, day } | { matches: [key...] } | { none: true }
+ * A saved session by its key, the start of its key (SAVED_PREFIX_MIN characters or more), or
+ * its log's own full id (matched by hash, since the id itself is never saved).
+ */
+export function findSaved(dir, text) {
+  const want = String(text ?? '').trim().toLowerCase();
+  if (!want || want.length > 200) return { none: true };
+  const all = savedSessions(dir);
+  const byKey = new Map();
+  for (const x of all) if (!byKey.has(x.session.key)) byKey.set(x.session.key, x.day);
+  if (byKey.has(want)) return { key: want, day: byKey.get(want) };
+  const hash = idHashOf(want);
+  const byId = all.find((x) => x.session.idHash === hash);
+  if (byId) return { key: byId.session.key, day: byId.day };
+  if (want.length < SAVED_PREFIX_MIN) return { none: true };
+  const keys = [...byKey.keys()].filter((k) => k.startsWith(want)).sort();
+  if (keys.length === 1) return { key: keys[0], day: byKey.get(keys[0]) };
+  return keys.length ? { matches: keys } : { none: true };
+}
+
+/**
+ * savedSessionAnswer({ dir, config, roots, key, day }) -> the saved session and its findings,
+ * every string redacted again with `config`'s settings, or null when it's no longer saved:
+ *   { session, findings, rules, status, savedAt, version, logOnDisk }
+ * `status` is each pattern's state in the run that checked this session, or null when that run
+ * saved none (a session the checks didn't read).
+ * `logOnDisk` is true when one of its log files is still under `roots`, false when none is, and
+ * null when it named none.
+ */
+export function savedSessionAnswer({ dir, config, roots, key, day, onDisk: given = null }) {
+  const f = readDay(dir, day);
+  const s = f?.sessions.find((x) => x?.key === key);
+  if (!s) return null;
+  const redactor = createRedactor(config);
+  const redact = (x) => redactor.redact(String(x));
+  const files = Array.isArray(s.files) ? s.files : [];
+  const onDisk = given ?? (files.length ? logKeys(roots) : null);
+  const answer = redactSaved({
+    session: s,
+    findings: (f.findings ?? []).filter((x) => x?.session === key),
+    rules: Array.isArray(f.rules) ? f.rules : [],
+    status: Array.isArray(s.status) ? s.status : null,
+    savedAt: s.savedAt ?? f.savedAt ?? null,
+    version: s.version ?? f.version ?? null,
+  }, redact);
+  return { ...answer, logOnDisk: files.length ? files.some((k) => onDisk.has(k)) : null };
+}
+
+
+/**
+ * countsFromSaved({ dir, from, to, timezone, roots, version }) -> trend counts, or null
+ * What trendCounts (lib/problems/index.mjs) gives for a window, worked out from the check results
+ * saved for it instead of reading its logs again: the sessions the checks read with a step in it,
+ * and each pattern's findings worth a look whose moment is in it, split into worked out from the
+ * log and possible, each with its weakest evidence word. Null, so the window is read instead, when
+ * a day of it was never saved or was saved before it ended, a session in it ran past the window
+ * its checks covered, or a session in it whose log is still on disk was saved by another
+ * honestweek version (its log is read with this one's rules) or written to since it was saved.
+ */
+export function countsFromSaved({ dir, from, to, timezone, roots, version, config = null }) {
+  const settings = config ? checksPrint(config) : null;
+  const days = [];
+  for (let day = from; day <= to; day = nextDay(day)) days.push(day);
+  // Every day saved after it ended, so no session that started later in it is missing.
+  if (!days.every((day) => {
+    const f = readDay(dir, day);
+    return f && Date.parse(f.savedAt ?? '') >= localDateRangeInstants(day, day, timezone).endExclusive.getTime();
+  })) return null;
+  const { start, endExclusive } = localDateRangeInstants(from, to, timezone);
+  const inRange = (day) => day >= from && day <= to;
+  const sessions = new Map();
+  const findings = [];
+  // A session that started up to a week before can still have steps in the window.
+  for (let day = nextDayBy(from, -7); day <= to; day = nextDay(day)) {
+    const f = readDay(dir, day);
+    if (!f) continue;
+    for (const s of f.sessions) {
+      if (!s?.checked || sessions.has(s.key) || !(Array.isArray(s.days) && s.days.some(inRange))) continue;
+      sessions.set(s.key, s);
+    }
+    for (const x of f.findings) if (x && sessions.has(x.session)) findings.push(x);
+  }
+  let onDisk = null;
+  for (const s of sessions.values()) {
+    // The checks that saved it covered its part of this window.
+    const first = Date.parse(s.firstAt ?? '');
+    const last = Date.parse(s.lastAt ?? s.firstAt ?? '');
+    if (!Number.isFinite(s.checkedFrom) || !Number.isFinite(s.checkedTo) || s.checkedFrom > Math.max(first, start.getTime()) || s.checkedTo < Math.min(last, endExclusive.getTime())) return null;
+    onDisk ??= logPaths(roots);
+    const present = (s.files ?? []).filter((k) => onDisk.has(k));
+    if (s.version !== version && present.length) return null;
+    // Checked under other settings (another long-session limit) with its log still there: read it.
+    if (present.length && settings && s.checks !== settings) return null;
+    // Checked while it may still have been running, its last turn's findings were notes: read it.
+    if (present.length && !settledWhenChecked(s, last)) return null;
+    // A log changed since the session was saved holds steps its saved results don't.
+    const prints = new Map((Array.isArray(s.prints) ? s.prints : []).map((x) => [x?.file, x]));
+    if (present.some((k) => {
+      const was = prints.get(k);
+      const fp = fileFingerprint(onDisk.get(k));
+      return !was || !fp || fp.size !== was.size || fp.mtimeMs !== was.mtimeMs || fp.head !== was.head;
+    })) return null;
+  }
+  const ranOf = new Map();
+  for (const s of sessions.values()) {
+    for (const x of Array.isArray(s.status) ? s.status : []) {
+      const r = ranOf.get(x.id) ?? { ran: false, levels: [] };
+      if (x.status === 'found' || x.status === 'clear') r.ran = true;
+      if (x.level) r.levels.push(x.level);
+      ranOf.set(x.id, r);
+    }
+  }
+  const looks = findings.filter((x) => x.severity === 'look' && x.at && inRange(localDay(Date.parse(x.at), timezone)));
+  const patterns = {};
+  for (const [id, r] of ranOf) {
+    const mine = looks.filter((x) => x.pattern === id);
+    const sure = mine.filter(isSure);
+    const possible = mine.filter((x) => !isSure(x));
+    patterns[id] = {
+      ran: r.ran,
+      sure: { value: sure.length, evidence: sure.length ? weakest(sure.map((x) => x.verdictEvidence)) : 'derived' },
+      possible: { value: possible.length, evidence: possible.length ? weakest(possible.map((x) => x.verdictEvidence)) : weakest(r.levels) },
+    };
+  }
+  return { sessions: sessions.size, patterns };
+}
+
+const nextDayBy = (day, n) => new Date(Date.parse(`${day}T00:00:00Z`) + n * 86400000).toISOString().slice(0, 10);

package/lib/saved/history.mjs

@@ -0,0 +1,235 @@
+// lib/saved/history.mjs: each day's history, saved day by day (issue 151, second part).
+//
+// With "saveResults" on and its "history" not turned off, `honestweek view` saves, beside the
+// check results (lib/saved/checks.mjs), what the engine built for each session that started that
+// day: its steps, agents, links, token counts, and the joins that tie it to other sessions, goals
+// and git (lib/replay/saved-sessions.mjs says exactly what, and what's left out). One gzipped file
+// per day, days/<day>.json.gz in the saved folder, compressed with Node's own zlib.
+//
+// A later run gives the engine back each saved session whose log is gone, so it stays replayable,
+// on the sessions list, in Replay, on Problems with the findings saved with it, in goals and in
+// pull-request and commit lookups. Each one says when it was saved, by which honestweek version,
+// and that its log is gone. A session whose log is still on disk is read from the log, as always.
+//
+// What's written is the redacted build's output, never the private build's, and it's redacted
+// again with the reading run's settings when it comes back (in the engine). A later run replaces
+// each day it read, keeping any saved session it didn't read.
+//
+// Zero runtime dependencies: Node built-ins only.
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { gunzipSync, gzipSync } from 'node:zlib';
+
+import { localDateRangeInstants } from '../resolve-week.mjs';
+import { localDay } from '../replay/views.mjs';
+import { fileFingerprint, SAVED_SESSION_SCHEMA } from '../replay/saved-sessions.mjs';
+import { CHECKS_SUB, checksPrint, settledWhenChecked } from './checks.mjs';
+import { honestweekVersion, keptFrom, logPaths, MAX_SAVED_FILE, pruneSaved, readSaved, redactionPrint, SAVED_SCHEMA, savedDays, writeSavedBytes } from './store.mjs';
+
+/** The sub-folder of the saved folder that holds each day's history. */
+export const DAYS_SUB = 'days';
+/** The largest a saved day may be once unzipped; a larger one is read as missing. */
+export const MAX_DAY_BYTES = 512 * 1024 * 1024;
+/** How many days before a window a session that runs into it may have started, and still be
+ *  found in its start day's file. */
+export const LOOKBACK_DAYS = 7;
+/** A session that wrote a record this recently is read again even when its log hasn't changed:
+ *  the checks say a finding near the end of one that may still be running is only a note. */
+export const RECENT_MS = 24 * 60 * 60 * 1000;
+
+const shift = (day, n) => new Date(Date.parse(`${day}T00:00:00Z`) + n * 86400000).toISOString().slice(0, 10);
+const dayFile = (day) => `${day}.json.gz`;
+
+/** One saved day's history, or null when it's missing, too big, unreadable or of another shape. */
+export function readHistoryDay(dir, day) {
+  const path = join(dir, DAYS_SUB, dayFile(day));
+  try {
+    const st = statSync(path);
+    if (!st.isFile() || st.size > MAX_SAVED_FILE) return null;
+    const text = gunzipSync(readFileSync(path), { maxOutputLength: MAX_DAY_BYTES }).toString('utf8');
+    const value = JSON.parse(text);
+    return value && value.schema === SAVED_SCHEMA && Array.isArray(value.sessions) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * saveHistory({ dir, config, h, keepDays, others, now }) -> { days, sessions }
+ * Each day of h's window, from its first day to its last: the sessions h read from logs that
+ * started that day, as the engine exports them, and any saved session of that day h didn't read.
+ * A day already past keepDays isn't written. h must be the redacted build, made with `saving`.
+ */
+export function saveHistory({ dir, config, h, keepDays, others = false, now = Date.now() }) {
+  if (typeof h.exportSession !== 'function') return { days: [], sessions: 0 };
+  const tz = h.window.timezone;
+  const { from, to } = h.window;
+  const savedAt = new Date(now).toISOString();
+  const version = honestweekVersion();
+  const redaction = redactionPrint(config);
+  const today = localDay(now, tz);
+  const oldest = keptFrom(today, keepDays);
+  const byDay = new Map();
+  for (const s of h.sessions) {
+    if (!s.firstAt || s.saved || h.reusedSessions?.has(s.key)) continue;
+    // A session from a display-only repository or a folder outside the config is saved only when
+    // the config says so ("otherSessions"): by default only configured repositories' history is.
+    if (s.private && !others) continue;
+    const day = localDay(Date.parse(s.firstAt), tz);
+    if (day < from || day > to || (oldest && day < oldest)) continue;
+    const x = h.exportSession(s.key);
+    if (!x) continue;
+    if (!byDay.has(day)) byDay.set(day, []);
+    byDay.get(day).push({ ...x, savedAt, version, redaction });
+  }
+  const days = [];
+  let sessions = 0;
+  for (let day = from; day <= to; day = shift(day, 1)) {
+    if (oldest && day < oldest) continue;
+    const fresh = byDay.get(day) ?? [];
+    const had = readHistoryDay(dir, day);
+    // A day file that's there but can't be read (damaged, too big, or of a newer shape) may hold
+    // the only copy of sessions whose logs are gone: it's left as it is, not written over.
+    if (!had && existsSync(join(dir, DAYS_SUB, dayFile(day)))) continue;
+    // A saved session that named a log file this run didn't read (a sub-agent's log deleted before
+    // the session's own) keeps its fuller saved copy rather than the part read now.
+    const fuller = new Map((had?.sessions ?? []).filter((x) => x && typeof x.key === 'string').map((x) => [x.key, x]));
+    const keepsOld = (x) => {
+      const old = fuller.get(x.key);
+      if (!old) return false;
+      const now = new Set((x.sources ?? []).map((s) => s.key));
+      return (old.sources ?? []).some((s) => !now.has(s.key));
+    };
+    const freshUsed = fresh.filter((x) => !keepsOld(x));
+    // A day this run read nothing new for is left as it is (unless "otherSessions" was turned off
+    // and it holds one of those to drop).
+    if (had && !freshUsed.length && (others || !had.sessions.some((x) => x?.record?.private === true))) continue;
+    const freshKeys = new Set(freshUsed.map((x) => x.key));
+    // With otherSessions off, a display-only or outside session saved while it was on goes too.
+    const kept = (had?.sessions ?? []).filter((x) => x && typeof x.key === 'string' && !freshKeys.has(x.key) && (others || x.record?.private !== true));
+    const all = [...freshUsed, ...kept].sort((a, b) => String(a.record?.firstAt).localeCompare(String(b.record?.firstAt)) || (a.key < b.key ? -1 : 1));
+    const value = { schema: SAVED_SCHEMA, day, timezone: tz, savedAt, version, redaction, sessions: all };
+    writeSavedBytes(dir, [DAYS_SUB, dayFile(day)], gzipSync(Buffer.from(JSON.stringify(value), 'utf8')));
+    days.push(day);
+    sessions += all.length;
+  }
+  const pruned = pruneSaved(dir, DAYS_SUB, { keepDays, today });
+  return { days, sessions, pruned };
+}
+
+/** With history off, the days saved while it was on are still deleted once past keepDays. */
+export function pruneHistory({ dir, h, keepDays, now = Date.now() }) {
+  return pruneSaved(dir, DAYS_SUB, { keepDays, today: localDay(now, h.window.timezone) });
+}
+
+/**
+ * loadSaved({ dir, from, to, timezone, roots, config, others, now }) -> { sessions, findings, reuse }
+ * The saved sessions whose span overlaps from..to (read in `timezone`) that a build can take back
+ * instead of reading a log, for buildWorkHistory's `saved` and `reuse`:
+ *   - each one none of whose log files is on disk any more, marked log: 'gone';
+ *   - each one whose log files are all on disk, unchanged since it was saved (size, last change
+ *     and a hash of their first bytes), saved by this honestweek version with these private-word
+ *     settings, that ended more than RECENT_MS before `now`, and whose check results were saved
+ *     too, from checks that covered all of it, marked log: 'on-disk' and named in `reuse`.
+ * Any other saved session is left to the log, read again. `findings` holds the findings the checks
+ * saved with each session taken back (an empty list for one with none), for runProblems' `saved`,
+ * and `statuses` each one's pattern states when it was checked, for its `savedStatus`. With
+ * `others` false, a display-only or outside session saved while "otherSessions" was on stays
+ * out.
+ */
+export function loadSaved({ dir, from, to, timezone, roots, config = null, others = true, now = Date.now() }) {
+  const { start, endExclusive } = localDateRangeInstants(from, to, timezone);
+  const startT = start.getTime();
+  const endT = endExclusive.getTime();
+  const version = honestweekVersion();
+  const print = config ? redactionPrint(config) : null;
+  const sessions = [];
+  const findings = new Map();
+  const statuses = new Map();
+  const reuse = new Set();
+  let onDisk = null;
+  const seen = new Set();
+  const checksOf = new Map();
+  const checksDay = (day) => {
+    if (!checksOf.has(day)) {
+      const c = readSaved(dir, [CHECKS_SUB, `${day}.json`]);
+      checksOf.set(day, c && Array.isArray(c.sessions) && Array.isArray(c.findings) ? c : null);
+    }
+    return checksOf.get(day);
+  };
+  // A finding counts only when its moment is in the window, as the checks would find it now.
+  const inWindow = (y) => {
+    const t = Date.parse(y?.at ?? '');
+    return !Number.isFinite(t) || (t >= startT && t < endT);
+  };
+  for (let day = shift(from, -LOOKBACK_DAYS); day <= to; day = shift(day, 1)) {
+    const f = readHistoryDay(dir, day);
+    if (!f) continue;
+    for (const x of f.sessions) {
+      if (!x || x.schema !== SAVED_SESSION_SCHEMA || typeof x.key !== 'string' || seen.has(x.key) || (!others && x.record?.private === true)) continue;
+      const first = Date.parse(x.record?.firstAt ?? '');
+      const last = Date.parse(x.record?.lastAt ?? x.record?.firstAt ?? '');
+      if (!Number.isFinite(first) || first >= endT || (Number.isFinite(last) ? last : first) < startT) continue;
+      const files = (x.sources ?? []).map((s) => s.file).filter(Boolean);
+      onDisk ??= logPaths(roots);
+      const present = (x.sources ?? []).filter((s) => s.file && onDisk.has(s.file));
+      // The day it was saved under holds its check results, whatever the timezone is now.
+      const c = checksDay(f.day);
+      const checked = c?.sessions.find((s) => s?.key === x.key) ?? null;
+      const own = c ? c.findings.filter((y) => y?.session === x.key && inWindow(y)) : [];
+      if (files.length && !present.length) {
+        seen.add(x.key);
+        sessions.push({ ...x, log: 'gone', redaction: typeof x.redaction === 'string' ? x.redaction : null });
+        findings.set(x.key, own);
+        if (Array.isArray(checked?.status)) statuses.set(x.key, checked.status);
+        continue;
+      }
+      const unchanged = present.length === (x.sources ?? []).length && present.every((s) => {
+        const fp = fileFingerprint(onDisk.get(s.file));
+        return fp && fp.size === s.size && fp.mtimeMs === s.mtimeMs && fp.head === s.head;
+      });
+      const settled = Number.isFinite(last) && now - last > RECENT_MS;
+      // The checks that saved its findings covered all of it: a session that ran past the end of the
+      // window it was checked in has steps no check looked at.
+      const covered = Number.isFinite(checked?.checkedFrom) && Number.isFinite(checked?.checkedTo) && checked.checkedFrom <= first && last < checked.checkedTo;
+      // And under the settings the checks read now (the long-session limit).
+      const sameChecks = !config || checked?.checks === checksPrint(config);
+      // And checked once it had been quiet long enough that no finding was softened to a note.
+      if (!unchanged || !settled || !checked || !covered || !sameChecks || !settledWhenChecked(checked, last) || x.version !== version || (print && x.redaction !== print)) continue;
+      seen.add(x.key);
+      sessions.push({ ...x, log: 'on-disk', redaction: x.redaction });
+      findings.set(x.key, own);
+      if (Array.isArray(checked.status)) statuses.set(x.key, checked.status);
+      reuse.add(x.key);
+    }
+  }
+  return { sessions, findings, statuses, reuse };
+}
+
+/** How many bytes of logs a byte of a saved day stands for, in memory once it's loaded: on the
+ *  made-up demo week, 6.1 MB of logs saved as 194 KB of gzipped days (about 31 to 1). An estimate. */
+export const SAVED_LOG_RATIO = 30;
+
+/**
+ * savedDayFiles(dir, logs) -> [{ day, size }]
+ * The saved days with no log file of their own (in `logs`, as logFiles lists them), each sized as
+ * the logs it stands for (SAVED_LOG_RATIO), so the window's plan and its memory check count the
+ * sessions a saved day brings back. Empty when nothing's saved.
+ */
+export function savedDayFiles(dir, logs = []) {
+  const withLogs = new Set(logs.map((f) => f.day));
+  const out = [];
+  for (const day of savedDays(dir, DAYS_SUB)) {
+    if (withLogs.has(day)) continue;
+    try {
+      out.push({ day, size: statSync(join(dir, DAYS_SUB, dayFile(day))).size * SAVED_LOG_RATIO });
+    } catch {
+      /* gone since the listing */
+    }
+  }
+  return out;
+}
+
+/** The log files and the saved days with no log of their own, as one list (savedDayFiles). */
+export const withSavedDays = (logs, dir) => [...logs, ...savedDayFiles(dir, logs)];