honestweek 0.0.0-stage → 0.2.0

package/lib/view/facts.mjs

@@ -0,0 +1,306 @@
+// lib/view/facts.mjs: plain facts about each session, the ones Claude Code's /insights writes to
+// its session-meta files, computed by honestweek itself from the logs it already read, for
+// Claude Code and Codex alike. No model is asked and nothing is read again: every fact comes
+// from the work history's events and token counts.
+//
+// Each fact says how it's known:
+//   recorded      a record holds it as it stands (a start time, a prompt's time)
+//   derived       counted or computed from recorded values only (a count, a sum, a gap)
+//   inferred      a named pattern produced it and could be wrong (a "risky" command)
+//   not-recorded  this agent's logs, as honestweek reads them, don't carry it; never shown as 0
+//   hidden        recorded, but not shown: the folder of a session outside the configured repos
+//
+// Every fact carries its receipt: the ids of the steps it was read or counted from (`basis`),
+// or, for token counts, the log lines they came from (`refs`), and an inferred one names its rule.
+// Facts are numbers, names and times, plus two strings (the first prompt and the folder),
+// which the caller passes through the page's redactor before they're shown.
+
+import { mcpServer } from '../replay/classify.mjs';
+import { editedFileKeys } from '../replay/metrics.mjs';
+
+/** The facts, in the order /insights writes them, with the short label a page shows. */
+export const FACTS = Object.freeze([
+  ['session_id', 'Session id'],
+  ['project_path', 'Folder'],
+  ['start_time', 'Started'],
+  ['duration_minutes', 'Minutes'],
+  ['user_message_count', 'Your messages'],
+  ['assistant_message_count', 'Agent messages'],
+  ['tool_counts', 'Tools'],
+  ['languages', 'Languages'],
+  ['git_commits', 'Commits run'],
+  ['git_pushes', 'Pushes run'],
+  ['input_tokens', 'Input tokens'],
+  ['output_tokens', 'Output tokens'],
+  ['first_prompt', 'First prompt'],
+  ['user_interruptions', 'Interruptions'],
+  ['user_response_times', 'Your reply time'],
+  ['tool_errors', 'Tool errors'],
+  ['tool_error_categories', 'Errors by tool'],
+  ['uses_task_agent', 'Sub-agents'],
+  ['uses_mcp', 'MCP tools'],
+  ['uses_web_search', 'Web search'],
+  ['uses_web_fetch', 'Web fetch'],
+  ['lines_added', 'Lines added'],
+  ['lines_removed', 'Lines removed'],
+  ['files_modified', 'Files changed'],
+  ['message_hours', 'Hours you wrote'],
+  ['user_message_timestamps', 'Message times'],
+  ['bash_would_prompt_count', 'Would prompt'],
+  ['file_edit_tool_count', 'Edits'],
+  ['destructive_command_count', 'Risky commands'],
+]);
+export const FACT_NAMES = Object.freeze(FACTS.map(([n]) => n));
+
+/**
+ * What an agent's logs don't carry, as honestweek reads them. Neither log says whether a
+ * command would have asked for permission. Codex has no web fetch tool, and the engine doesn't
+ * read Codex's web search records.
+ */
+const NOT_RECORDED = Object.freeze({
+  'claude-code': new Set(['bash_would_prompt_count']),
+  codex: new Set(['bash_would_prompt_count', 'uses_web_search', 'uses_web_fetch']),
+});
+
+/** The pattern behind destructive_command_count: commands that delete or rewrite. */
+export const DESTRUCTIVE_RULE = 'facts.destructive-command';
+/** The rule behind git_commits and git_pushes: a git commit or push in a command's text. */
+export const GIT_RULE = 'facts.git-command';
+/** The rule behind a Codex interruption count: a turn Codex records as interrupted. */
+export const INTERRUPT_RULE = 'facts.codex-interrupted';
+const DESTRUCTIVE = [
+  /\brm\s+(?:-[a-zA-Z]*[rf][a-zA-Z]*\s+)+/,
+  /\bgit\s+reset\s+--hard\b/,
+  /\bgit\s+push\b[^;&|\n]*\s(?:--force(?:-with-lease)?|-f)\b/,
+  /\bgit\s+clean\s+-[a-zA-Z]*f/,
+  /\bgit\s+branch\s+-D\b/,
+  /\bgit\s+checkout\s+--\s+\./,
+  /\bRemove-Item\b[^;&|\n]*-Recurse/i,
+  /\b(?:rmdir|rd|del)\s+\/[sq]\b/i,
+  /\bdrop\s+(?:table|database)\b/i,
+];
+const GIT_COMMIT = /\bgit\s+(?:-[cC]\s+\S+\s+)*commit\b/;
+const GIT_PUSH = /\bgit\s+(?:-[cC]\s+\S+\s+)*push\b/;
+const DID_NOT_RUN = new Set(['rejected', 'refused', 'interrupted']);
+
+const LANGUAGE = Object.freeze({
+  js: 'JavaScript', mjs: 'JavaScript', cjs: 'JavaScript', jsx: 'JavaScript', ts: 'TypeScript', tsx: 'TypeScript', mts: 'TypeScript',
+  py: 'Python', rb: 'Ruby', go: 'Go', rs: 'Rust', java: 'Java', kt: 'Kotlin', swift: 'Swift', cs: 'C#', c: 'C', h: 'C',
+  cpp: 'C++', cc: 'C++', hpp: 'C++', php: 'PHP', sh: 'Shell', bash: 'Shell', ps1: 'PowerShell', sql: 'SQL',
+  md: 'Markdown', json: 'JSON', yml: 'YAML', yaml: 'YAML', toml: 'TOML', html: 'HTML', css: 'CSS', scss: 'CSS',
+});
+const languageOf = (file) => {
+  const m = typeof file === 'string' ? file.match(/\.([A-Za-z0-9]+)$/) : null;
+  return m ? LANGUAGE[m[1].toLowerCase()] ?? null : null;
+};
+
+/** The most step ids kept as one fact's receipt. */
+export const MAX_BASIS = 200;
+/** A fact: its value, how it's known, the steps it was read or counted from (its receipt),
+ *  and, when inferred, the rule that decided it. */
+const fact = (value, how, basis = [], rule = null) => ({ value, how, basis: basis.slice(0, MAX_BASIS), ...(rule ? { rule } : {}) });
+const median = (xs) => {
+  if (!xs.length) return null;
+  const s = [...xs].sort((a, b) => a - b);
+  const mid = s.length >> 1;
+  return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
+};
+const bump = (obj, k, n = 1) => {
+  obj[k] = (obj[k] ?? 0) + n;
+};
+
+/** The hour of day, 0 to 23, of an instant in `timezone`. */
+function hourIn(t, timezone) {
+  const h = Number(new Intl.DateTimeFormat('en-US', { timeZone: timezone, hour: 'numeric', hourCycle: 'h23' }).format(new Date(t)));
+  return h === 24 ? 0 : h;
+}
+
+/**
+ * sessionFacts(h, session, { timezone, usage, id, cwd, hidden, events }) -> { key, agent, facts }
+ * `h` is a work history, `session` one of its sessions. `usage` is the token-count list
+ * (h.usage.calls, possibly from another build of the same window), `id` the session's own id
+ * (Claude Code's file id or Codex's thread id) or null, `cwd` its working folder or null, and
+ * `hidden` true for a session outside the configured repos, whose folder isn't shown. The
+ * two text facts, first_prompt and project_path, are returned as they are: the caller redacts.
+ */
+export function sessionFacts(h, session, { timezone = 'UTC', usage = null, id = null, cwd = null, hidden = false, events = null } = {}) {
+  const agent = session.tool === 'codex' ? 'codex' : 'claude-code';
+  const mine = (events ?? h.events.filter((e) => e.session === session.key)).slice().sort((a, b) => a.t - b.t || (a.id < b.id ? -1 : 1));
+  const main = `${session.key}:main`;
+  const ids = (list) => list.map((e) => e.id);
+  const prompts = mine.filter((e) => e.kind === 'prompt');
+  const promptHow = prompts.some((e) => (e.inferred ?? []).some((x) => x.key === 'authorship')) ? 'inferred' : 'derived';
+  const messages = mine.filter((e) => e.kind === 'message' && e.agent === main);
+  const actions = mine.filter((e) => e.kind === 'action');
+  const tools = {};
+  const errorsByTool = {};
+  const languages = {};
+  const langSteps = [];
+  const errors = [];
+  const commits = [];
+  const pushes = [];
+  const destructive = [];
+  const edits = [];
+  const okEdits = [];
+  let added = 0;
+  let removed = 0;
+  const files = new Set();
+  for (const e of actions) {
+    const f = e.facts;
+    bump(tools, f.tool ?? 'other');
+    if (f.result === 'error') {
+      bump(errorsByTool, f.tool ?? 'other');
+      errors.push(e);
+    }
+    const lang = languageOf(f.file);
+    if (lang && (f.category === 'edit' || f.category === 'read')) {
+      bump(languages, lang);
+      langSteps.push(e);
+    }
+    if (f.category === 'edit') {
+      edits.push(e);
+      if (f.result === 'ok') {
+        okEdits.push(e);
+        const p = e.derived?.patch;
+        if (p) {
+          added += p.added ?? 0;
+          removed += p.removed ?? 0;
+        }
+        // A whole-file write records the lines it wrote, not a patch against the old file.
+        if (Number.isInteger(e.derived?.linesWritten) && !(p?.added || p?.removed)) added += e.derived.linesWritten;
+        for (const k of editedFileKeys(e)) files.add(k);
+      }
+    }
+    if (f.category === 'shell' && typeof f.command === 'string' && !DID_NOT_RUN.has(f.result)) {
+      if (GIT_COMMIT.test(f.command)) commits.push(e);
+      if (GIT_PUSH.test(f.command)) pushes.push(e);
+      if (DESTRUCTIVE.some((re) => re.test(f.command))) destructive.push(e);
+    }
+  }
+  // The person's interruptions: Claude Code records who stopped a run; Codex records that a
+  // turn was interrupted, not by whom, so its count is an inference.
+  const interrupts = mine.filter((e) => e.kind === 'interrupt');
+  const byPerson = interrupts.filter((e) => e.facts.by === 'person');
+  const codexInterrupted = interrupts.filter((e) => e.facts.by === 'harness-reported' && e.facts.reason === 'interrupted');
+  // Reply time: from the main agent's last recorded step to the person's next prompt.
+  const replies = [];
+  const replied = [];
+  let lastAgentT = null;
+  for (const e of mine) {
+    if (e.kind === 'prompt' && e.agent === main) {
+      if (lastAgentT != null && e.t >= lastAgentT) {
+        replies.push(Math.round((e.t - lastAgentT) / 1000));
+        replied.push(e);
+      }
+      lastAgentT = null;
+    } else if (e.agent === main && (e.kind === 'message' || e.kind === 'action' || e.kind === 'turn-end')) {
+      lastAgentT = Math.max(lastAgentT ?? 0, e.end?.t ?? e.t);
+    }
+  }
+  const hours = {};
+  for (const e of prompts) bump(hours, String(hourIn(e.t, timezone)));
+  const calls = (usage ?? []).filter((c) => c.session === session.key);
+  const first = prompts.find((e) => typeof e.facts.text === 'string');
+  const firstT = Date.parse(session.firstAt);
+  const lastT = Date.parse(session.lastAt);
+  const ends = mine.length ? [mine[0], mine[mine.length - 1]] : [];
+  // A count matched by a pattern on the command's text is inferred: the text says a git commit
+  // or an rm -rf was asked for, not that it did what the pattern names.
+  const matched = (list, rule) => (list.length ? fact(list.length, 'inferred', ids(list), rule) : fact(0, 'derived'));
+  const some = (pred) => {
+    const hit = actions.find(pred);
+    return fact(!!hit, 'derived', hit ? [hit.id] : []);
+  };
+
+  const out = {
+    session_id: id ? fact(id, 'recorded', ids(mine.slice(0, 1))) : fact(null, 'not-recorded'),
+    project_path: hidden ? fact(null, 'hidden') : cwd ? fact(cwd, 'recorded', ids(mine.slice(0, 1))) : fact(null, 'not-recorded'),
+    start_time: fact(session.firstAt ?? null, 'recorded', ids(mine.slice(0, 1))),
+    duration_minutes: fact(Number.isFinite(firstT) && Number.isFinite(lastT) ? Math.round((lastT - firstT) / 60000) : null, 'derived', ids(ends)),
+    user_message_count: fact(prompts.length, promptHow, ids(prompts), promptHow === 'inferred' ? 'authorship' : null),
+    assistant_message_count: fact(messages.length, 'derived', ids(messages)),
+    tool_counts: fact(tools, 'derived', ids(actions)),
+    languages: fact(languages, 'derived', ids(langSteps)),
+    git_commits: matched(commits, GIT_RULE),
+    git_pushes: matched(pushes, GIT_RULE),
+    input_tokens: calls.length ? { ...fact(calls.reduce((n, c) => n + (c.input ?? 0), 0), 'derived'), refs: calls.slice(0, MAX_BASIS).map((c) => ({ src: c.source, lines: c.lines })) } : fact(null, 'not-recorded'),
+    output_tokens: calls.length ? { ...fact(calls.reduce((n, c) => n + (c.output ?? 0), 0), 'derived'), refs: calls.slice(0, MAX_BASIS).map((c) => ({ src: c.source, lines: c.lines })) } : fact(null, 'not-recorded'),
+    first_prompt: fact(first ? first.facts.text : null, 'recorded', first ? [first.id] : []),
+    user_interruptions: agent === 'codex' ? (codexInterrupted.length ? fact(codexInterrupted.length, 'inferred', ids(codexInterrupted), INTERRUPT_RULE) : fact(0, 'derived')) : fact(byPerson.length, 'derived', ids(byPerson)),
+    user_response_times: fact(replies, 'derived', ids(replied)),
+    tool_errors: fact(errors.length, 'derived', ids(errors)),
+    tool_error_categories: fact(errorsByTool, 'derived', ids(errors)),
+    uses_task_agent: some((e) => e.facts.category === 'delegate'),
+    uses_mcp: some((e) => mcpServer(e.facts.tool) != null),
+    uses_web_search: some((e) => e.facts.tool === 'WebSearch'),
+    uses_web_fetch: some((e) => e.facts.tool === 'WebFetch'),
+    lines_added: fact(added, 'derived', ids(okEdits)),
+    lines_removed: fact(removed, 'derived', ids(okEdits)),
+    files_modified: fact(files.size, 'derived', ids(okEdits)),
+    message_hours: fact(hours, 'derived', ids(prompts)),
+    user_message_timestamps: fact(prompts.map((e) => e.at).filter((x) => typeof x === 'string'), 'recorded', ids(prompts)),
+    bash_would_prompt_count: fact(null, 'not-recorded'),
+    file_edit_tool_count: fact(edits.length, 'derived', ids(edits)),
+    destructive_command_count: matched(destructive, DESTRUCTIVE_RULE),
+  };
+  for (const name of NOT_RECORDED[agent]) out[name] = fact(null, 'not-recorded');
+  return { key: session.key, agent, facts: out };
+}
+
+/** The median reply time in seconds, the one figure a page shows for user_response_times. */
+export const medianReply = (secs) => median(secs);
+
+/**
+ * windowTotals(list) -> { all, 'claude-code', codex }
+ * Totals over sessions' facts: counts and sums added, true facts counted as sessions, maps
+ * merged. Each total says how many sessions it's known for, and which (`basis`, session keys); a fact no session records stays
+ * not-recorded, never 0. A total is inferred when any part of it is.
+ */
+export function windowTotals(list) {
+  const empty = () => ({ sessions: 0, facts: {} });
+  const out = { all: empty(), 'claude-code': empty(), codex: empty() };
+  for (const s of list) {
+    for (const t of [out.all, out[s.agent]]) {
+      t.sessions++;
+      for (const name of FACT_NAMES) {
+        if (name === 'session_id' || name === 'project_path' || name === 'first_prompt' || name === 'start_time') continue;
+        const f = s.facts[name];
+        const cur = (t.facts[name] ??= { value: null, how: 'not-recorded', known: 0, basis: [] });
+        if (f.how === 'not-recorded' || f.value == null) continue;
+        cur.known++;
+        // The total's receipt: the sessions it adds up.
+        cur.basis.push(s.key);
+        if (cur.how === 'not-recorded') cur.how = 'derived';
+        if (f.how === 'inferred') cur.how = 'inferred';
+        const v = f.value;
+        if (typeof v === 'boolean') cur.value = (cur.value ?? 0) + (v ? 1 : 0);
+        else if (typeof v === 'number') cur.value = (cur.value ?? 0) + v;
+        else if (Array.isArray(v)) cur.value = [...(cur.value ?? []), ...v];
+        else if (v && typeof v === 'object') {
+          cur.value ??= {};
+          for (const [k, n] of Object.entries(v)) bump(cur.value, k, n);
+        }
+      }
+    }
+  }
+  // The window keeps one figure per reply-time list and per timestamp list: the median, and the count.
+  for (const t of Object.values(out)) {
+    if (Array.isArray(t.facts.user_response_times?.value)) t.facts.user_response_times.value = median(t.facts.user_response_times.value);
+    if (Array.isArray(t.facts.user_message_timestamps?.value)) t.facts.user_message_timestamps.value = t.facts.user_message_timestamps.value.length;
+  }
+  return out;
+}
+
+/**
+ * coverage(list) -> { [agent]: { sessions, facts: { [name]: known count } } }
+ * How many of each agent's sessions each fact is known for: the figure the pull request quotes.
+ */
+export function coverage(list) {
+  const out = {};
+  for (const s of list) {
+    const c = (out[s.agent] ??= { sessions: 0, facts: Object.fromEntries(FACT_NAMES.map((n) => [n, 0])) });
+    c.sessions++;
+    for (const n of FACT_NAMES) if (s.facts[n].how !== 'not-recorded') c.facts[n]++;
+  }
+  return out;
+}

package/lib/view/insights.mjs

@@ -0,0 +1,309 @@
+// lib/view/insights.mjs: the optional "Include /insights" group on the Problems page, and the
+// "Run /insights" button.
+//
+// Claude Code's own /insights command has the model on the person's account read their sessions
+// and writes what it concluded to <claude folder>/usage-data/: facets/<session id>.json (the
+// model's reading of one session: its friction, a summary) and session-meta/<session id>.json
+// (counts about it). Their shapes aren't documented and may change, so they're read defensively:
+// only files for sessions this window already loaded, by id, never a folder listing beyond
+// whether any facets file exists; a file that's too large, doesn't parse, isn't an object or
+// whose session_id isn't its own id counts as skipped; unknown fields are ignored. Nothing here
+// runs git, and nothing is written.
+//
+// What /insights wrote is the model's words, so it's never mixed into honestweek's own counts,
+// levels or ranking: the caller shows it as its own group, labelled AI-written, each item tied
+// to a whole session rather than to steps, and every string passes the redactor first.
+//
+// The button runs the local `claude -p /insights`, found on the PATH (absolute folders only, so
+// a claude file sitting in the current folder is never picked), one run at a time, only while
+// the toggle is on, stopped after RUN_TIMEOUT_MS. claude gets only the environment variables on
+// CLAUDE_ENV (claudeEnv below), not other tools' tokens. Its output is discarded: the page reads
+// only the files it leaves behind. honestweek makes no network call itself; claude does, on the
+// person's own plan.
+
+import { spawn } from 'node:child_process';
+import { accessSync, constants, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { systemProgram } from '../windows-root.mjs';
+
+/** The largest /insights file read; a bigger one is skipped. */
+export const MAX_INSIGHTS_FILE = 1024 * 1024;
+/** How long one run may take before it's stopped. */
+export const RUN_TIMEOUT_MS = 15 * 60 * 1000;
+/** The longest text kept from one /insights field, after redaction. */
+export const INSIGHTS_TEXT = 400;
+/** The most friction categories kept per session. */
+const MAX_CATEGORIES = 20;
+
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const isObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * The environment variables any program the page starts keeps: what it needs to start, find its
+ * home, config and temporary folders, and reach its service through a proxy or a company
+ * certificate. Each program adds its own sign-in variables.
+ */
+export const SYSTEM_ENV = Object.freeze(['PATH', 'PATHEXT', 'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'SYSTEMDRIVE', 'OS', 'USERNAME', 'USERDOMAIN', 'COMPUTERNAME', 'PROCESSOR_ARCHITECTURE', 'NUMBER_OF_PROCESSORS', 'PROGRAMFILES', 'PROGRAMFILES(X86)', 'PROGRAMW6432', 'COMMONPROGRAMFILES', 'USER', 'LOGNAME', 'SHELL', 'TERM', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'APPDATA', 'LOCALAPPDATA', 'PROGRAMDATA', 'TEMP', 'TMP', 'TMPDIR', 'LANG', 'LC_ALL', 'TZ', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'XDG_RUNTIME_DIR', 'HTTPS_PROXY', 'HTTP_PROXY', 'NO_PROXY', 'ALL_PROXY', 'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS']);
+
+/** `env` with only the string variables named in `names` (a Set of capitals) or starting with one of `prefixes`, matched in capitals. */
+export function keepEnv(env, names, prefixes = []) {
+  return Object.fromEntries(
+    Object.entries(env ?? {}).filter(([k, v]) => {
+      const up = k.toUpperCase();
+      return typeof v === 'string' && (names.has(up) || prefixes.some((p) => up.startsWith(p)));
+    }),
+  );
+}
+
+/**
+ * What claude keeps besides SYSTEM_ENV. CLAUDE_CONFIG_DIR and the home folder find its sign-in
+ * file (on macOS, the login keychain, which needs no variable); ANTHROPIC_ and CLAUDE_CODE_ hold an
+ * API key, a sign-in token, a gateway address and its own settings; AWS_ and the Google Cloud names
+ * sign in through Amazon Bedrock or Google Vertex AI; DISABLE_ and DO_NOT_TRACK keep the person's
+ * opt-outs; the version managers' homes let a claude installed with npm find its node. Everything
+ * else this process holds (GitHub, npm or OpenAI tokens, honestweek's own settings) is left out,
+ * so a session that talks claude into printing its environment finds little there.
+ */
+const CLAUDE_ENV = new Set([...SYSTEM_ENV, 'CLAUDE_CONFIG_DIR', 'GOOGLE_APPLICATION_CREDENTIALS', 'GOOGLE_CLOUD_PROJECT', 'CLOUD_ML_REGION', 'CLOUDSDK_CONFIG', 'DO_NOT_TRACK', 'NVM_DIR', 'VOLTA_HOME', 'ASDF_DIR', 'ASDF_DATA_DIR']);
+const CLAUDE_PREFIXES = Object.freeze(['ANTHROPIC_', 'CLAUDE_CODE_', 'AWS_', 'VERTEX_REGION_', 'DISABLE_']);
+export const claudeEnv = (env) => keepEnv(env, CLAUDE_ENV, CLAUDE_PREFIXES);
+
+/** Where /insights writes, beside Claude Code's projects folder: <claude folder>/usage-data. */
+export function insightsDir(roots) {
+  const projects = roots?.claude?.[0];
+  return typeof projects === 'string' && projects ? join(dirname(projects), 'usage-data') : null;
+}
+
+/** Whether any facets file exists. Only names are listed; no file is read. */
+export function hasInsightsData(dir) {
+  if (!dir) return false;
+  try {
+    return readdirSync(join(dir, 'facets')).some((n) => n.toLowerCase().endsWith('.json'));
+  } catch {
+    return false;
+  }
+}
+
+/** One /insights file for one session: { state: 'absent' } | { state: 'skipped' } | { state: 'ok', value }. */
+function readOne(dir, folder, id) {
+  const file = join(dir, folder, `${id}.json`);
+  let st;
+  try {
+    st = statSync(file);
+  } catch {
+    return { state: 'absent' };
+  }
+  if (!st.isFile() || st.size > MAX_INSIGHTS_FILE) return { state: 'skipped' };
+  let value;
+  try {
+    value = JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return { state: 'skipped' };
+  }
+  if (!isObject(value) || typeof value.session_id !== 'string' || value.session_id.toLowerCase() !== id) return { state: 'skipped' };
+  return { state: 'ok', value };
+}
+
+/** A text field as one string: a string, or a list of strings joined; anything else is null. */
+function textOf(v) {
+  if (typeof v === 'string') return v.trim() || null;
+  if (Array.isArray(v)) {
+    const parts = v.filter((x) => typeof x === 'string' && x.trim());
+    return parts.length ? parts.join(' ') : null;
+  }
+  return null;
+}
+
+/** friction_counts as [{ category, count }]: whole counts of 1 or more, largest first. */
+function frictionsOf(v) {
+  if (!isObject(v)) return [];
+  return Object.entries(v)
+    .filter(([k, n]) => k.trim() && k.length <= 200 && Number.isInteger(n) && n >= 1)
+    .map(([category, count]) => ({ category, count }))
+    .sort((a, b) => b.count - a.count || (a.category < b.category ? -1 : 1))
+    .slice(0, MAX_CATEGORIES);
+}
+
+/**
+ * readInsights({ dir, sessions }) -> { exists, sessions, matched, skipped, items }
+ * `sessions` are [{ key, id }]: an engine session key and its Claude Code session id. Only
+ * those sessions' files are read. `matched` counts sessions with a readable facets file,
+ * `skipped` the files left out, and `items` one entry per matched session with friction.
+ * The strings aren't redacted yet.
+ */
+export function readInsights({ dir, sessions }) {
+  const out = { exists: hasInsightsData(dir), sessions: 0, matched: 0, skipped: 0, items: [] };
+  if (!dir) return out;
+  const seen = new Set();
+  for (const s of sessions ?? []) {
+    const id = typeof s?.id === 'string' ? s.id.toLowerCase() : '';
+    if (!SESSION_ID.test(id) || seen.has(id)) continue;
+    seen.add(id);
+    out.sessions++;
+    const facets = readOne(dir, 'facets', id);
+    const meta = readOne(dir, 'session-meta', id);
+    if (facets.state === 'skipped') out.skipped++;
+    if (meta.state === 'skipped') out.skipped++;
+    if (facets.state !== 'ok') continue;
+    out.matched++;
+    const f = facets.value;
+    const frictions = frictionsOf(f.friction_counts);
+    if (!frictions.length) continue;
+    const minutes = meta.state === 'ok' && Number.isFinite(meta.value.duration_minutes) && meta.value.duration_minutes >= 0 ? Math.round(meta.value.duration_minutes) : null;
+    out.items.push({ session: s.key, frictions, detail: textOf(f.friction_detail), summary: textOf(f.brief_summary), outcome: textOf(f.outcome), minutes });
+  }
+  return out;
+}
+
+/**
+ * The absolute path of `name` on the PATH, or null. Relative PATH entries are passed over, so a
+ * file in the current folder is never run. On Windows it tries each PATHEXT extension.
+ */
+export function findOnPath(name, env = process.env, platform = process.platform) {
+  const get = (k) => {
+    const hit = Object.keys(env ?? {}).find((x) => x.toUpperCase() === k);
+    return hit ? env[hit] : undefined;
+  };
+  const win = platform === 'win32';
+  const dirs = String(get('PATH') ?? '').split(win ? ';' : ':').filter((d) => d && isAbsolute(d));
+  const exts = win ? String(get('PATHEXT') || '.COM;.EXE;.BAT;.CMD').split(';').filter((e) => /^\.[A-Za-z0-9]+$/.test(e)) : [''];
+  for (const d of dirs) {
+    for (const ext of exts) {
+      const file = join(d, `${name}${ext}`);
+      try {
+        if (!statSync(file).isFile()) continue;
+        if (!win) accessSync(file, constants.X_OK);
+        return file;
+      } catch {
+        /* not here */
+      }
+    }
+  }
+  return null;
+}
+
+/** Start `file -p /insights` with claudeEnv. A .cmd or .bat file runs through cmd.exe, quoted, with fixed arguments. */
+function startClaude(file, { env, cwd, platform, spawnFn }) {
+  const opts = { cwd, env: claudeEnv(env), stdio: 'ignore', windowsHide: true };
+  if (platform === 'win32' && /\.(cmd|bat)$/i.test(file)) {
+    return spawnFn(opts.env.ComSpec || opts.env.COMSPEC || systemProgram('cmd.exe', env), ['/d', '/s', '/c', `""${file}" -p /insights"`], { ...opts, windowsVerbatimArguments: true });
+  }
+  return spawnFn(file, ['-p', '/insights'], { ...opts, detached: platform !== 'win32' });
+}
+
+/** Stop a run and everything it started. On Windows that's taskkill, from the system folder. */
+export function stopTree(child, { platform, env, spawnFn }) {
+  if (!child?.pid) return;
+  try {
+    if (platform === 'win32') {
+      spawnFn(systemProgram('taskkill.exe', env), ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }).on('error', () => child.kill());
+    } else process.kill(-child.pid, 'SIGKILL');
+  } catch {
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      /* already gone */
+    }
+  }
+}
+
+const json = (status, body) => ({ status, body });
+
+/**
+ * createInsights({ dir, on, demo, persist, env, platform, cwd, timeoutMs, now, spawnFn })
+ *   -> { info, read, toggle, run, stop, setOn, isOn }
+ * `persist(on)` remembers the toggle in the config; it answers { remembered: true } or
+ * { remembered: false, note } and throws with a plain message when the write fails.
+ */
+export function createInsights({ dir = null, on = false, demo = false, persist = async () => ({ remembered: false }), env = process.env, platform = process.platform, cwd = process.cwd(), timeoutMs = RUN_TIMEOUT_MS, now = () => Date.now(), spawnFn = spawn } = {}) {
+  let isOn = on === true;
+  let remembered = null; // null until a toggle answers; then whether it reached the config
+  let child = null;
+  let timer = null;
+  const run = { state: 'idle', startedAt: null, endedAt: null, code: null, runs: 0 };
+
+  function runState() {
+    const end = run.endedAt ?? now();
+    return { state: run.state, runs: run.runs, elapsedMs: run.startedAt == null ? null : end - run.startedAt, code: run.code, timeoutMs };
+  }
+
+  function info() {
+    return { on: isOn, remembered, demo, hasData: hasInsightsData(dir), claude: demo ? null : !!findOnPath('claude', env, platform), run: runState() };
+  }
+
+  function finish(state, code = null) {
+    if (run.state !== 'running') return;
+    clearTimeout(timer);
+    timer = null;
+    run.state = state;
+    run.code = code;
+    run.endedAt = now();
+    child = null;
+  }
+
+  return {
+    info,
+    isOn: () => isOn,
+    setOn(v) {
+      isOn = v === true;
+    },
+    /** The window's /insights, or null while the toggle is off. */
+    read(sessions) {
+      return isOn ? readInsights({ dir, sessions }) : null;
+    },
+    /** POST body { "on": true | false }. */
+    async toggle(body) {
+      let raw;
+      try {
+        raw = JSON.parse(String(body));
+      } catch {
+        raw = null;
+      }
+      if (!isObject(raw) || typeof raw.on !== 'boolean' || Object.keys(raw).length !== 1) return json(400, { error: 'bad-body', message: 'Send { "on": true } or { "on": false }.' });
+      let saved;
+      try {
+        saved = await persist(raw.on);
+      } catch (err) {
+        return json(500, { error: 'not-saved', message: `The setting couldn't be saved, so it wasn't changed (${String(err?.message ?? err).split('\n')[0]}).` });
+      }
+      isOn = raw.on;
+      remembered = saved?.remembered === true;
+      return json(200, { ...info(), note: saved?.note ?? null });
+    },
+    /** POST: start `claude -p /insights`, unless the toggle is off, it's the demo, one is running, or claude isn't found. */
+    async run() {
+      // The page shows the button only while the toggle is on; the server holds to that too.
+      if (!isOn) return json(409, { error: 'off', message: "Include /insights is off, so /insights didn't run. Turn it on first.", ...info() });
+      if (demo) return json(409, { error: 'demo', message: "Not in the demo: /insights reads your own sessions, not the made-up ones.", ...info() });
+      if (run.state === 'running') return json(409, { error: 'running', message: '/insights is already running.', ...info() });
+      const file = findOnPath('claude', env, platform);
+      if (!file) return json(409, { error: 'no-claude', message: "claude isn't on your PATH.", ...info() });
+      if (/["%]/.test(file)) return json(409, { error: 'no-claude', message: "claude's path has a character this page won't pass to a shell.", ...info() });
+      let c;
+      try {
+        c = startClaude(file, { env, cwd, platform, spawnFn });
+      } catch (err) {
+        return json(500, { error: 'not-started', message: `claude couldn't be started (${String(err?.code ?? err?.message ?? err)}).`, ...info() });
+      }
+      child = c;
+      Object.assign(run, { state: 'running', startedAt: now(), endedAt: null, code: null, runs: run.runs + 1 });
+      // An earlier run stopped for time can still exit later; only this run's own end counts.
+      c.once('error', () => child === c && finish('failed'));
+      c.once('exit', (code) => child === c && finish(code === 0 ? 'done' : 'failed', Number.isInteger(code) ? code : null));
+      timer = setTimeout(() => {
+        const was = child;
+        finish('timeout');
+        stopTree(was, { platform, env, spawnFn });
+      }, timeoutMs);
+      timer.unref?.();
+      return json(200, info());
+    },
+    /** Stop a run in progress (honestweek view is stopping). */
+    stop() {
+      if (run.state !== 'running') return;
+      const was = child;
+      finish('stopped');
+      stopTree(was, { platform, env, spawnFn });
+    },
+  };
+}