honestweek 0.2.0 → 0.3.0

package/lib/replay/saved-sessions.mjs

@@ -0,0 +1,315 @@
+// lib/replay/saved-sessions.mjs: sessions the engine didn't read from a log this run, given to it
+// as they were saved by an earlier run (issue 151).
+//
+// `honestweek view` can keep each day's history between runs (lib/saved/). A session saved that
+// way comes back into a later build, as if its log had been read, once its log is gone (Claude
+// Code deletes logs after 30 days by default). The engine takes such a session through
+// `buildWorkHistory({ saved })`, and everything downstream (threads, goals, lookups, git
+// outcomes, timelines, the checks' context) works on it as on any other. This module turns a
+// built session into what's saved, and what's saved back into the engine's own shapes.
+//
+// What's saved is the redacted build's own output for the session: its steps, agents, links,
+// token counts, and the joins that connect it to other sessions and to goals and git (pull
+// requests, commits, branches). Nothing raw: fields the engine keeps in memory only (an event's
+// `_raw`, `_command`, `_workdir`, `_lineCwd`) are dropped; record ids, message ids and token call
+// ids are kept only as hashes; a goal id found in its text is kept as a hash; a log file only as
+// the hash of its path. Git outcomes and quiet intervals aren't saved: the build works them out
+// again. When saved sessions come back, every string passes the current redactor again.
+//
+// Ids a saved session shares with another session (record ids a resumed copy repeats, a message's
+// id) are compared as hashes, so with `saved` in play the engine hashes the fresh sessions' ids
+// the same way before it joins them. Without `saved`, nothing here runs.
+
+import { closeSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
+
+import { prRefsInCommand } from './classify.mjs';
+import { pathKey, letterHash } from './ids.mjs';
+
+/** The shape of a saved session; one of another is left out of a build. */
+export const SAVED_SESSION_SCHEMA = 1;
+
+/** An id as saved and as compared once saved sessions are in a build. */
+export const idHash = (s) => letterHash(`id\u0000${String(s)}`, 24);
+/** A log's own session id (a Claude Code file id, a Codex thread id), as saved. */
+export const logIdHash = (id) => (typeof id === 'string' && id ? letterHash(`log-id\u0000${id.toLowerCase()}`, 24) : null);
+let VERSION = null;
+/** honestweek's own version, from its package.json, which says which version saved a session. */
+export function honestweekVersion() {
+  if (VERSION === null) {
+    try {
+      VERSION = String(JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version ?? 'unknown');
+    } catch {
+      VERSION = 'unknown';
+    }
+  }
+  return VERSION;
+}
+
+/** A fingerprint of the private-word settings a session was saved with: a hash, never the words. */
+export function redactionPrint(config) {
+  return letterHash(`redaction\u0000${JSON.stringify(config?.redaction ?? null)}`, 16);
+}
+
+/** How many bytes from a log's start its fingerprint reads. */
+export const HEAD_BYTES = 4096;
+
+/**
+ * A log file's fingerprint: { size, mtimeMs, head }, `head` a hash of its first HEAD_BYTES bytes,
+ * so a file replaced by another of the same size and time still reads as changed. Null when it
+ * can't be read.
+ */
+export function fileFingerprint(path) {
+  if (typeof path !== 'string' || !path) return null;
+  let fd;
+  try {
+    const st = statSync(path);
+    if (!st.isFile()) return null;
+    const buf = Buffer.alloc(Math.min(HEAD_BYTES, st.size));
+    fd = openSync(path, 'r');
+    const n = buf.length ? readSync(fd, buf, 0, buf.length, 0) : 0;
+    return { size: st.size, mtimeMs: st.mtimeMs, head: letterHash(buf.subarray(0, n), 16) };
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* already closed */
+      }
+    }
+  }
+}
+
+/** A repository label, as saved: the config's label is matched to it on the way back. */
+export const labelHash = (label) => (typeof label === 'string' ? letterHash(`repo-label\u0000${label}`, 16) : null);
+/** A goal id or goal-event id found in a session's text, as saved. */
+export const tokenHash = (token) => letterHash(`goal-token\u0000${String(token)}`, 24);
+
+/** The links the engine makes from one session's own records, which a saved session brings back
+ *  as saved, since the joins behind them aren't saved. */
+const OWN_LINKS = new Set(['spawned', 'completion-notice', 'stopped', 'handback', 'program-launch']);
+/** Links between sessions a saved session also brings back: a resumed copy's records were let go
+ *  when it was saved, and a message's two ends may not both be in this build. The engine makes
+ *  them again too, where both sessions are here; each is kept once. */
+const SHARED_LINKS = new Set(['continuation', 'message-delivered', 'handoff']);
+/** A pull request's repository as it's matched on the way back, without its name on disk. */
+export const repoNameHash = (repo) => (typeof repo === 'string' && repo ? letterHash(`repo\u0000${repo.toLowerCase()}`, 24) : null);
+
+/** A pull-request, commit or branch join as saved: every field but its step, which is named by id,
+ *  each string redacted except a commit id. */
+function joinOut(x, redact) {
+  const out = {};
+  for (const [k, v] of Object.entries(x)) {
+    if (k === 'event' || k.startsWith('_')) continue;
+    out[k] = typeof v === 'string' && k !== 'sha' ? redact(v) : v;
+  }
+  if (typeof x.repo === 'string' && x.repo) out.repoHash = repoNameHash(x.repo);
+  out.event = x.event.id;
+  return out;
+}
+
+/** What git says about a step, which every build asks git again rather than keeping. */
+const GIT_MISSING = new Set(['readable-session-repository', 'commit-in-session-repository', 'default-branch']);
+
+const ownFields = (e) => {
+  const out = {};
+  for (const [k, v] of Object.entries(e)) if (!k.startsWith('_')) out[k] = v;
+  if (Array.isArray(out.missing)) out.missing = out.missing.filter((m) => !GIT_MISSING.has(m));
+  return out;
+};
+
+/**
+ * exportSession({ key, parsed, a, sessions, links, usage, redact, fileStat }) -> a saved session
+ * The redacted build's own parts for one session, ready to write. `a` is the assembled history,
+ * `sessions` the history's session records, `usage` its token calls. Null for a session the
+ * build doesn't hold. `hashed` says the build already hashed the shared ids (it had saved sessions).
+ */
+export function exportSession({ key, parsed, a, sessions, links, usage, redact, fileStat = () => null, ranOutside = () => false, hashed = false }) {
+  const record = sessions.find((s) => s.key === key);
+  if (!record) return null;
+  // With saved sessions in the build, the engine has already hashed these ids for the join.
+  const hashOnce = hashed ? (x) => x : idHash;
+  const mine = parsed.filter((p) => p.source.sessionKey === key);
+  const main = mine.find((p) => p.source.role === 'session') ?? null;
+  const sourceKeys = new Set(mine.map((p) => p.source.key));
+  const events = a.events.filter((e) => e.session === key && sourceKeys.has(e.source) && e.kind !== 'quiet').map(ownFields);
+  const eventIds = new Set(events.map((e) => e.id));
+  const agents = [...a.agents.values()].filter((x) => x.session === key);
+  const agentKeys = new Set(agents.map((x) => x.key));
+  const touches = (v) => typeof v === 'string' && (eventIds.has(v) || agentKeys.has(v) || sourceKeys.has(v) || v === key);
+  const ownLinks = links.filter((l) => touches(l.from) || touches(l.to) || (Array.isArray(l.sessions) && l.sessions.includes(key)));
+  const live = (x) => x?.event && eventIds.has(x.event.id);
+  // A join is kept once across files, so one on this session's step can sit in another file's
+  // list (a resumed copy's): every file's joins are looked through.
+  const j = (k) => parsed.flatMap((p) => p.result.joins?.[k] ?? []).filter(live);
+  const repo = a.sessionsByKey.get(key)?.repo ?? null;
+  const id = main ? (main.source.tool === 'codex' ? main.source.threadId : main.source.fileId) : null;
+  return {
+    schema: SAVED_SESSION_SCHEMA,
+    key,
+    tool: record.tool,
+    record,
+    repo: repo ? { label: labelHash(repo.label), role: repo.role ?? null } : null,
+    logId: logIdHash(id),
+    sources: mine.map((p) => {
+      const st = fileStat(p.source.file);
+      return {
+        key: p.source.key,
+        tool: p.source.tool,
+        role: p.source.role,
+        agent: p.ctx.agentKey,
+        file: pathKey(p.source.file),
+        size: st?.size ?? p.source.size ?? null,
+        mtimeMs: st?.mtimeMs ?? null,
+        head: st?.head ?? null,
+        firstAt: p.result.stats.firstAt ?? p.source.firstAt ?? null,
+        lastAt: p.result.stats.lastAt ?? p.source.lastAt ?? null,
+        records: p.result.stats.records ?? 0,
+        unparsable: p.result.stats.unparsable ?? 0,
+        oversized: p.result.stats.oversized ?? 0,
+        models: p.result.stats.models ?? [],
+        entrypoint: p.result.stats.entrypoint ?? null,
+        origin: p.result.stats.origin ? { kind: p.result.stats.origin.kind ?? null } : null,
+        // How each record type in the file was handled, and what reading it noticed.
+        coverage: [...(p.result.coverage ?? new Map())].map(([k, v]) => [redact(k), { count: v.count, handling: redact(v.handling) }]),
+        anomalies: p.result.anomalies ?? [],
+      };
+    }),
+    events,
+    agents,
+    links: ownLinks,
+    // What assembly noticed about its steps (a result stamped before its call, say).
+    anomalies: a.anomalies.filter((x) => eventIds.has(x.event)),
+    usage: usage.filter((c) => c.session === key).map((c) => ({ ...c, id: c.idHash ?? null })),
+    joins: {
+      uuids: mine.flatMap((p) => p.result.joins?.uuids ?? []).map((u) => ({ uuid: hashOnce(u.uuid), eventIds: u.eventIds })),
+      // A record this session's file repeats from another (a resumed copy) was let go in favour of
+      // the original; its id, kind and place are kept, so the original can still say it was copied.
+      copies: mine.flatMap((p) => p.result.events).filter((e) => !eventIds.has(e.id) && e.kind !== 'quiet').map((e) => ({ id: e.id, source: e.source, kind: e.kind, refs: e.refs ?? [] })),
+      sentMessages: j('sentMessages').map((m) => ({ msgId: hashOnce(m.msgId), event: m.event.id })),
+      receivedMessages: j('receivedMessages').map((m) => ({ msgId: hashOnce(m.msgId), event: m.event.id })),
+      chips: j('chips').map((c) => ({ digest: c.digest, event: c.event.id })),
+      prs: j('prs').map((x) => joinOut(x, redact)),
+      commits: j('commits').map((x) => joinOut(x, redact)),
+      branches: j('branches').map((x) => joinOut(x, redact)),
+      watched: j('watched').map((x) => ({ token: tokenHash(x.token), where: x.where, event: x.event.id })),
+      // The pull requests a gh command names, read from the command when it was saved, since the
+      // command's own text isn't kept: each repository redacted, with a hash to match it back.
+      commandPrs: a.events
+        .filter((e) => e.session === key && eventIds.has(e.id) && e.kind === 'action' && e.facts?.category === 'shell' && typeof e._command === 'string')
+        .map((e) => ({ event: e.id, ranOutside: ranOutside(e), refs: prRefsInCommand(e._command).map((r) => ({ number: r.number, via: r.via, repoKnown: r.repoKnown, repo: typeof r.repo === 'string' ? redact(r.repo) : r.repo ?? null, ...(typeof r.repo === 'string' && r.repo ? { repoHash: repoNameHash(r.repo) } : {}) })) }))
+        .filter((x) => x.refs.length),
+      firstPromptDigest: main?.result.joins?.firstPromptDigest ?? null,
+      firstPromptEvent: main && eventIds.has(main.result.joins?.firstPromptEvent) ? main.result.joins.firstPromptEvent : null,
+    },
+  };
+}
+
+/**
+ * The engine's parsed entries for one saved session, as if its sources had been read: each with
+ * the saved steps, the joins the engine matches across sessions, and its token calls. `ctxOf(source)`
+ * gives each source the build's context (its repository and whether it's private, from the config
+ * as it is now). `resolve(token hash)` is the goal id or goal-event id it stands for, or null.
+ */
+export function savedAsParsed(saved, { ctxOf, resolveToken = () => null, repoSlug = () => null }) {
+  // A pull request's repository comes back as the name the session's repository has now, when it
+  // was that one; otherwise it stays as saved, redacted, and matches nothing.
+  const slugBack = (x) => {
+    if (!x.repoHash) return x;
+    const slug = repoSlug();
+    const { repoHash, ...rest } = x;
+    return slug && repoNameHash(slug) === repoHash ? { ...rest, repo: slug } : rest;
+  };
+  const events = saved.events.map((e) => ({ ...e, refs: e.refs ?? [], facts: e.facts ?? {}, derived: e.derived ?? {}, inferred: e.inferred ?? [], missing: [...(e.missing ?? [])] }));
+  // Marked, in memory only, so assembly says nothing twice that a saved step already says.
+  for (const e of events) Object.defineProperty(e, '_saved', { value: true, enumerable: false });
+  const byId = new Map(events.map((e) => [e.id, e]));
+  // A gh command's pull requests, kept in memory beside its step for the reverse lookup, as the
+  // command's own text is for a step read from a log.
+  for (const c of saved.joins?.commandPrs ?? []) {
+    const e = byId.get(c.event);
+    if (!e) continue;
+    Object.defineProperty(e, '_prRefs', { value: (c.refs ?? []).map((r) => slugBack({ ...r })), enumerable: false });
+    Object.defineProperty(e, '_ranOutside', { value: c.ranOutside === true, enumerable: false });
+  }
+  const ev = (id) => byId.get(id) ?? null;
+  const withEvent = (list, map) => (list ?? []).map((x) => ({ ...map(x), event: ev(x.event) })).filter((x) => x.event);
+  const joins = saved.joins ?? {};
+  const out = [];
+  for (const s of saved.sources) {
+    const source = { key: s.key, tool: s.tool, role: s.role, sessionKey: saved.key, file: null, cwd: null, firstAt: s.firstAt, lastAt: s.lastAt, size: s.size, saved: true };
+    const ctx = ctxOf(source, s);
+    const isMain = s.role === 'session';
+    const own = events.filter((e) => e.source === s.key);
+    const ownIds = new Set(own.map((e) => e.id));
+    const onlyOwn = (list) => list.filter((x) => ownIds.has(x.event.id));
+    out.push({
+      source,
+      ctx,
+      result: {
+        events: own,
+        joins: {
+          calls: new Map(),
+          uuids: (joins.uuids ?? []).filter((u) => u.eventIds?.some((x) => String(x).startsWith(`${s.key}.`))),
+          sentMessages: onlyOwn(withEvent(joins.sentMessages, (m) => ({ msgId: m.msgId }))),
+          receivedMessages: onlyOwn(withEvent(joins.receivedMessages, (m) => ({ msgId: m.msgId }))),
+          chips: onlyOwn(withEvent(joins.chips, (c) => ({ digest: c.digest }))),
+          prs: onlyOwn(withEvent(joins.prs, (x) => slugBack({ ...x }))),
+          commits: onlyOwn(withEvent(joins.commits, (x) => slugBack({ ...x }))),
+          branches: onlyOwn(withEvent(joins.branches, (x) => ({ ...x }))),
+          watched: onlyOwn(withEvent(joins.watched, (x) => ({ token: resolveToken(x.token), where: x.where }))).filter((x) => x.token != null),
+          firstPromptDigest: isMain ? joins.firstPromptDigest ?? null : null,
+          firstPromptEvent: isMain ? joins.firstPromptEvent ?? null : null,
+          programStart: null,
+          hookLaunches: [],
+        },
+        coverage: new Map(Array.isArray(s.coverage) ? s.coverage : []),
+        anomalies: Array.isArray(s.anomalies) ? s.anomalies : [],
+        copyStubs: (joins.copies ?? []).filter((c) => c.source === s.key).map((c) => ({ id: c.id, kind: c.kind, refs: c.refs ?? [], facts: {}, derived: {}, inferred: [], missing: [] })),
+        stats: { records: s.records ?? 0, unparsable: s.unparsable ?? 0, oversized: s.oversized ?? 0, firstAt: s.firstAt, lastAt: s.lastAt, models: s.models ?? [], titles: [], entrypoint: s.entrypoint ?? null, origin: s.origin ?? null },
+        usage: (saved.usage ?? []).filter((c) => c.source === s.key).map((c) => ({ id: c.id, agent: c.agent, t: c.t, lines: c.lines ?? [], input: c.input, cacheWrite: c.cacheWrite, cacheRead: c.cacheRead, output: c.output, ...(c.ttl ? { ttl: c.ttl } : {}), hashed: true })),
+      },
+    });
+  }
+  return out;
+}
+
+/**
+ * After assembly: each saved session's own agents and the links its own records made come back as
+ * saved, replacing what assembly could make without the joins behind them; anomalies about its
+ * steps are left out (they weren't saved). Links between sessions that assembly made (a resumed
+ * copy, a message delivered, a hand-off) stay.
+ */
+export function restoreSaved(a, savedList) {
+  if (!savedList.length) return;
+  const keys = new Set(savedList.map((s) => s.key));
+  const savedEvents = new Set(savedList.flatMap((s) => s.events.map((e) => e.id)));
+  const savedSources = new Set(savedList.flatMap((s) => s.sources.map((x) => x.key)));
+  for (const [k, agent] of a.agents) if (keys.has(agent.session)) a.agents.delete(k);
+  for (const s of savedList) for (const agent of s.agents ?? []) a.agents.set(agent.key, { ...agent, missing: [...(agent.missing ?? [])] });
+  const isSaved = (v) => typeof v === 'string' && (savedEvents.has(v) || keys.has(v) || savedSources.has(v) || savedSources.has(v.replace(/:.*$/, '')));
+  const kept = a.links.filter((l) => !(OWN_LINKS.has(l.type) && (isSaved(l.from) || isSaved(l.to))));
+  const seen = new Set(kept.map((l) => `${l.type}\u0000${l.from}\u0000${l.to}`));
+  for (const s of savedList) {
+    for (const l of s.links ?? []) {
+      if (!OWN_LINKS.has(l.type) && !SHARED_LINKS.has(l.type)) continue;
+      const k = `${l.type}\u0000${l.from}\u0000${l.to}`;
+      if (seen.has(k)) continue;
+      seen.add(k);
+      kept.push(l);
+    }
+  }
+  a.links.length = 0;
+  a.links.push(...kept);
+  const keptAnomalies = a.anomalies.filter((x) => !savedEvents.has(x.event));
+  a.anomalies.length = 0;
+  a.anomalies.push(...keptAnomalies, ...savedList.flatMap((s) => s.anomalies ?? []));
+  for (const s of savedList) {
+    const sess = a.sessionsByKey.get(s.key);
+    if (!sess) continue;
+    if (s.record.launchedBy && !sess.launchedBy) sess.launchedBy = s.record.launchedBy;
+    if (s.record.startedFrom && !sess.startedFrom) sess.startedFrom = s.record.startedFrom;
+    sess.missing = [...(s.record.missing ?? [])];
+  }
+}

package/lib/replay/views.mjs

@@ -22,8 +22,19 @@ const I = EVIDENCE.INFERRED;
 
 const metric = (value, evidence, extra = {}) => ({ value, evidence, ...extra });
 
+const QUARTER_HOUR = 15 * 60 * 1000;
+const dayCache = new Map();
 export function localDay(t, tz) {
-  return localDateInTimezone(new Date(t), tz).toISOString().slice(0, 10);
+  // Every timezone's offset, and every change of it, falls on a quarter hour, so one quarter hour
+  // never spans two local days: the day is worked out once per quarter hour and zone.
+  const key = `${tz}\u0000${Math.floor(t / QUARTER_HOUR)}`;
+  let day = dayCache.get(key);
+  if (day === undefined) {
+    day = localDateInTimezone(new Date(t), tz).toISOString().slice(0, 10);
+    if (dayCache.size > 200_000) dayCache.clear();
+    dayCache.set(key, day);
+  }
+  return day;
 }
 
 function hasInference(e, value) {

package/lib/{view → replay}/word-index.mjs

@@ -1,4 +1,4 @@
-// lib/view/word-index.mjs: "search everywhere" for `honestweek view`.
+// lib/replay/word-index.mjs: "search everywhere", for `honestweek view`'s Find page and the `find` command.
 //
 // It reads the prompts and titles of every session in the window, from the same log
 // folders and window the history was built from, display-only repositories and folders
@@ -16,8 +16,8 @@
 // run's starting instruction. A child thread is skipped whole: its user messages are its
 // parent agent's hand-offs.
 
-import { readJsonlRecords, tryParse } from '../replay/jsonl.mjs';
-import { enumerateClaudeSources, enumerateCodexSources } from '../replay/sources.mjs';
+import { readJsonlRecords, tryParse } from './jsonl.mjs';
+import { enumerateClaudeSources, enumerateCodexSources } from './sources.mjs';
 import { createCodexTurnReader, isCodexExecSession } from '../codex-records.mjs';
 
 /** Harness text that arrives as a user record but isn't something a person typed. */

package/lib/replay/words.mjs

@@ -0,0 +1,122 @@
+// lib/replay/words.mjs: phrase search over a built work history, for `honestweek view`'s Find
+// page and the `find` command alike, so both read one implementation.
+//
+// Words match only sessions in configured repositories: a display-only or outside session never
+// joins a lookup, whichever build answers. Goal titles and ids match when the history was built
+// with a goal record. Each match says how it's known: words in a prompt, a title or a branch are
+// recorded there; ranking prompts by how many of the words they share is a named rule's reading.
+// Nothing here redacts: the history's strings already passed its redactor, and each caller shapes
+// and scrubs its own answer. "Search everywhere", which reads every session's prompts again from
+// the logs, is lib/replay/word-index.mjs.
+//
+// Zero runtime dependencies: Node built-ins only.
+
+/** The rules behind word matches, beside the engine's own. Their ids keep the `view.` prefix
+ *  they were first published under. */
+export const WORD_RULES = Object.freeze({
+  'view.shared-words': 'A prompt shares some of the words you typed. The score counts how many of your words appear in it as whole words; sharing words doesn\'t mean it was about the same thing.',
+  'view.similar-prompt': 'Two prompts share a large part of their words (the shared words divided by all the words either uses). Similar wording doesn\'t mean similar work.',
+});
+
+/** The most prompts one word search returns, and the most a "similar prompts" answer does. */
+export const MAX_PROMPTS = 20;
+export const MAX_SIMILAR = 10;
+/** The least share of words two prompts need to count as similar. */
+export const SIMILAR_MIN = 0.2;
+
+const STOP = new Set(['a', 'an', 'and', 'are', 'as', 'at', 'be', 'but', 'by', 'can', 'do', 'for', 'from', 'if', 'in', 'into', 'is', 'it', 'its', 'just', 'me', 'my', 'no', 'not', 'of', 'on', 'or', 'so', 'that', 'the', 'then', 'this', 'to', 'up', 'we', 'with', 'you', 'your', 'i', 'redacted']);
+const MARKERS = /\[redacted:[a-z]+\]/g;
+
+/** Lowercased words of a text, its redaction markers taken out first. */
+export function wordsOf(text) {
+  return (String(text ?? '').replace(MARKERS, ' ').toLowerCase().match(/[\p{L}\p{N}][\p{L}\p{N}_'-]*/gu) ?? []).filter((w) => w.length >= 2 && !STOP.has(w));
+}
+
+const PR_RE = /^(?:(?:[\w.-]+\/)?[\w.-]+#|pr\s*#?\s*|pull\/|#)(\d+)$/i;
+const PR_URL = /github\.com\/[^/\s]+\/[^/\s]+\/pull\/(\d+)/i;
+
+/**
+ * Whether `text` reads as a reference (a pull request, a commit, a file or a branch) rather than
+ * words: the Find page's rule (isRef in lib/view/assets/search.js, which keeps its own copy),
+ * plus the `pr:`, `pull:`, `commit:` and `path:` prefixes the find command names, so a prefix
+ * always makes it a reference.
+ */
+export function isReference(text) {
+  const q = String(text ?? '').trim();
+  if (/^(pr|pull|commit|path):/i.test(q)) return true;
+  return PR_RE.test(q) || PR_URL.test(q) || /^[0-9a-f]{7,40}$/i.test(q) || /^(file|branch):/i.test(q) || (!/\s/.test(q) && (/[\\/]/.test(q) || /^[\w.-]+\.[a-z0-9]{1,6}$/i.test(q)));
+}
+
+/** The prompts a word search reads: those with text, in sessions in configured repositories. */
+export function readablePrompts(h) {
+  const readable = new Set(h.sessions.filter((s) => s.private === false).map((s) => s.key));
+  return h.events.filter((e) => readable.has(e.session) && e.kind === 'prompt' && typeof e.facts?.text === 'string' && e.facts.text);
+}
+
+/**
+ * matchWords(h, text) -> { want, goals, sessions, branches, prompts }
+ *   want      the query's words (wordsOf), each once
+ *   goals     [{ index, matchedIn: 'title' | 'id' }], an index into h.goals, for a goal whose
+ *             title or id holds every word
+ *   sessions  [key] of configured sessions whose title holds every word
+ *   branches  [{ branch, sessions: [{ session, event }] }] for each branch name (pushed, checked
+ *             out, or the session's mode) holding the text, with each session's first such step
+ *   prompts   [{ event, shared }] up to MAX_PROMPTS prompts sharing any of the words, most shared
+ *             first, then newest; `event` is the history's own event
+ */
+export function matchWords(h, text) {
+  const q = String(text ?? '');
+  const want = [...new Set(wordsOf(q))];
+  const low = q.toLowerCase();
+  const has = (t) => want.length > 0 && want.every((w) => String(t ?? '').toLowerCase().includes(w));
+  const goals = (h.goals ?? []).flatMap((g, index) => {
+    const inTitle = has(g.title);
+    return inTitle || has(g.id) ? [{ index, matchedIn: inTitle ? 'title' : 'id' }] : [];
+  });
+  const sessions = h.sessions.filter((s) => s.private === false && s.title && has(s.title)).map((s) => s.key);
+  const readable = new Set(h.sessions.filter((s) => s.private === false).map((s) => s.key));
+  const branchMap = new Map();
+  for (const e of h.events) {
+    if (!readable.has(e.session)) continue;
+    const f = e.facts ?? {};
+    for (const b of [f.git?.push?.branch, f.git?.branch?.ref, e.kind === 'mode' ? f.branch : null]) {
+      if (typeof b !== 'string' || !b || !b.toLowerCase().includes(low)) continue;
+      if (!branchMap.has(b)) branchMap.set(b, new Map());
+      if (!branchMap.get(b).has(e.session)) branchMap.get(b).set(e.session, e.id);
+    }
+  }
+  const branches = [...branchMap].map(([branch, bySession]) => ({ branch, sessions: [...bySession].map(([session, event]) => ({ session, event })) }));
+  const prompts = readablePrompts(h)
+    .map((e) => {
+      const theirs = new Set(wordsOf(e.facts.text));
+      return { event: e, shared: want.filter((w) => theirs.has(w)).length };
+    })
+    .filter((x) => x.shared > 0)
+    .sort((a, b) => b.shared - a.shared || b.event.t - a.event.t)
+    .slice(0, MAX_PROMPTS);
+  return { want, goals, sessions, branches, prompts };
+}
+
+/**
+ * similarPrompts(h, eventId) -> null when no readable prompt has that id, else
+ * [{ event, score }]: up to MAX_SIMILAR other prompts sharing at least SIMILAR_MIN of their
+ * words with it (shared words over all the words either uses), most similar first, then newest.
+ */
+export function similarPrompts(h, eventId) {
+  const prompts = readablePrompts(h);
+  const base = prompts.find((e) => e.id === eventId);
+  if (!base) return null;
+  const mine = new Set(wordsOf(base.facts.text));
+  return prompts
+    .filter((e) => e.id !== base.id)
+    .map((e) => {
+      const theirs = new Set(wordsOf(e.facts.text));
+      let shared = 0;
+      for (const w of theirs) if (mine.has(w)) shared += 1;
+      const union = mine.size + theirs.size - shared;
+      return { event: e, score: union ? shared / union : 0 };
+    })
+    .filter((x) => x.score >= SIMILAR_MIN)
+    .sort((a, b) => b.score - a.score || b.event.t - a.event.t)
+    .slice(0, MAX_SIMILAR);
+}

package/lib/repo-identity.mjs

@@ -6,7 +6,7 @@
 import { existsSync, realpathSync } from 'node:fs';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 
-import { gitDirOf, resolveCommonDir } from './worktrees.mjs';
+import { gitDirOf, linkedWorkTrees, resolveCommonDir } from './worktrees.mjs';
 
 const samePath = (p) => (process.platform === 'win32' ? resolve(p).toLowerCase() : resolve(p));
 
@@ -45,36 +45,104 @@ const isUnder = (child, parent) => child.length > parent.length && child.startsW
  * or null. Git reading a repository reads the history of every folder in it, so a display
  * folder inside a featured or reference repository (or inside another worktree of it) would be
  * read after all (AGENTS.md invariant 4); a read repository inside a display folder is refused
- * too, since the person said that whole folder is display-only. Folders are compared by their
- * real paths, so a junction, a symlink or another case on Windows can't hide the overlap. The
- * same folder twice is left to checkSameRepos. `repos` are { path, label?, role }, paths resolved.
+ * too, since the person said that whole folder is display-only, and so is one with a worktree
+ * (or its main checkout) inside a display folder, since git reads the work done there with the
+ * rest of the repository. Folders are compared by their real paths, so a junction, a symlink or
+ * another case on Windows can't hide the overlap. The same folder twice is left to
+ * checkSameRepos. `repos` are { path, label?, role }, paths resolved.
  */
 export function checkNestedRoles(repos) {
   const keyed = repos.map((r) => ({ ...r, key: folderKey(r.path), name: r.label || basename(r.path) }));
   const display = keyed.filter((r) => r.role === 'display');
-  const read = keyed.filter((r) => r.role !== 'display');
+  if (display.length === 0) return null;
+  const read = keyed.filter((r) => r.role !== 'display').map((r) => ({ ...r, trees: workTreesOf(r.path) }));
   for (const d of display) {
     const walked = repoKey(d.path, { walk: true });
     for (const r of read) {
       if (isUnder(d.key, r.key) || (walked && !repoKey(d.path) && walked === repoKey(r.path))) return `${d.name} is display-only but sits inside ${r.name}, which git reads, so its history would be read too. Move it out of ${r.name}, or mark ${r.name} display as well.`;
       if (isUnder(r.key, d.key)) return `${r.name} is read by git but sits inside ${d.name}, which is display-only. Mark ${r.name} display as well, or remove one of them.`;
+      const wt = r.trees.find((t) => isUnder(t.key, d.key));
+      if (wt) return worktreeInside(r.name, wt, d.name);
     }
   }
   return null;
 }
 
+/** The refusal for a read repository with a checkout inside a display folder. A worktree whose
+ *  folder is gone still counts, since git lists it until it's pruned and sessions run there would
+ *  count as the repository's. Each way out is one git can follow: a hand move needs a repair
+ *  before a prune would drop the moved worktree's records, and a locked worktree needs an unlock. */
+function worktreeInside(name, wt, display) {
+  const tree = basename(wt.path);
+  if (wt.main) return `${name} is read by git but its main checkout, ${tree}, sits inside ${display}, which is display-only, so the work done there would be read too. Move it out of ${display}, or mark ${name} display as well.`;
+  if (!existsSync(wt.path) && wt.locked) return `${name} is read by git, which lists a locked worktree of it, ${tree}, inside ${display}, which is display-only, though that folder can't be found. If you moved it by hand, run git worktree repair with its new folder in ${name}; if its drive isn't connected, reconnect it and run git worktree unlock and git worktree move there; if it's gone for good, run git worktree unlock and git worktree prune there; or mark ${name} display as well.`;
+  if (!existsSync(wt.path)) return `${name} is read by git, which still lists a worktree of it, ${tree}, inside ${display}, which is display-only, though that folder is gone. If you moved it by hand, run git worktree repair with its new folder in ${name}; if it's gone for good, run git worktree prune there; or mark ${name} display as well.`;
+  const unlock = wt.locked ? 'git worktree unlock and ' : '';
+  return `${name} is read by git but has a worktree, ${tree}, inside ${display}, which is display-only, so the work done there would be read too. Move that worktree out of ${display} with ${unlock}git worktree move, or mark ${name} display as well.`;
+}
+
+/** Whether git running in folder `p` would reach a display-only folder too: `p` holds one, or
+ *  sits inside one, or is a plain subfolder of a checkout that holds one, since git there reads
+ *  that whole checkout (checkNestedRoles). Never runs git. */
+export function nestsDisplay(displayPaths) {
+  const display = displayPaths.map((d) => ({ path: d, role: 'display' }));
+  const nested = (q) => checkNestedRoles([{ path: q, role: 'reference' }, ...display]) !== null;
+  return (p) => {
+    const top = checkoutOf(p);
+    return nested(p) || (top !== null && nested(top));
+  };
+}
+
+/** Whether git can't be asked about folder `p` without reaching a display-only folder: `p` is,
+ *  or sits in, one of `displayPaths` or another worktree of one (displayTest), or git there would
+ *  reach one (nestsDisplay). Settings and discover both use it, so they skip git in the same
+ *  places. Never runs git. */
+export function reachesDisplay(displayPaths) {
+  const isDisplay = displayTest(displayPaths);
+  const nests = nestsDisplay(displayPaths);
+  return (p) => isDisplay(p, { walk: true }) || nests(p);
+}
+
+/** The nearest folder at or above `p` that holds a .git, or null outside a checkout. It walks up
+ *  from `p`'s real path, as git does, so a junction or symlink into a checkout finds that
+ *  checkout, not the one its name sits in. Never runs git. */
+export function checkoutOf(p) {
+  let start;
+  try {
+    start = realpathSync.native(p);
+  } catch {
+    start = resolve(p);
+  }
+  for (let d = start; ; d = dirname(d)) {
+    if (existsSync(join(d, '.git'))) return d;
+    if (dirname(d) === d) return null;
+  }
+}
+
 /** The git repository a folder belongs to, as its shared git folder (the one every worktree
  *  of it points at), read from git's files on disk, never by running git. With `walk`, a
  *  subfolder is read from the checkout that holds it. Null outside a repository. */
 export function repoKey(p, { walk = false } = {}) {
-  for (let d = resolve(p); ; ) {
-    // A worktree points at its repository's shared folder; a main checkout uses its own git
-    // folder, which `git init --separate-git-dir` puts elsewhere and names in a .git file.
-    if (existsSync(join(d, '.git'))) return folderKey(resolveCommonDir(d) ?? gitDirOf(d) ?? join(d, '.git'));
-    const up = dirname(d);
-    if (!walk || up === d) return null;
-    d = up;
-  }
+  const d = walk ? checkoutOf(p) : existsSync(join(resolve(p), '.git')) ? resolve(p) : null;
+  return d === null ? null : folderKey(sharedGitDir(d));
+}
+
+/** A worktree points at its repository's shared folder; a main checkout uses its own git
+ *  folder, which `git init --separate-git-dir` puts elsewhere and names in a .git file. */
+const sharedGitDir = (checkout) => resolveCommonDir(checkout) ?? gitDirOf(checkout) ?? join(checkout, '.git');
+
+/** Every folder the repository holding `p` is checked out in, as { path, key, main, locked }: its main
+ *  checkout and each linked worktree git lists in its shared folder. Read from git's files on
+ *  disk, never by running git. Empty for a folder that isn't there or isn't in a repository. */
+function workTreesOf(p) {
+  if (!existsSync(p)) return [];
+  const checkout = checkoutOf(p);
+  if (checkout === null) return [];
+  const common = sharedGitDir(checkout);
+  const trees = linkedWorkTrees(common, { withLocks: true }).map((t) => ({ ...t, main: false }));
+  // A main checkout keeps its git folder as `.git` inside it; a bare repository has no checkout.
+  if (basename(common) === '.git') trees.push({ path: dirname(common), main: true, locked: false });
+  return trees.map((t) => ({ ...t, key: folderKey(t.path) }));
 }
 
 /**