projectkeeper 0.0.0-stage → 1.0.0

package/src/sources/history.ts

@@ -0,0 +1,231 @@
+/**
+ * Old content from version history (Spec §1.2 `History only`, §3.1; CKC-03 AC-24; subagent/DECISIONS.md E64, E65).
+ *
+ * The Keeper can list the history of a path, read a file as it was at any commit — a deleted file, an old version of a
+ * plan, an old file of a worktree branch already merged — and list the documents main's history deleted. What it reads
+ * becomes a source whose `Used as` is `History only`, anchored at repository, commit and path. Deletion means "no
+ * longer needed" (D61), so that source has three uses only: marking what current material has outdated, cross-checking
+ * current documents, and producing the history when it is traced. It forms no current node, enters no context, and is
+ * never material waiting to be organized (the checks live with the writes and the coverage; `isHistoryOnly` is their
+ * one test).
+ *
+ * Only read-only git runs here, against the repositories in the project's scope.
+ */
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+import type { Project, ScopeItem, Source } from '../model/types.ts';
+import { fingerprint } from '../model/ids.ts';
+import type { ProjectStore } from '../store/project-store.ts';
+import {
+  gitCommitMeta, gitDeletedPaths, gitHashWorkingFile, gitPathHistory, gitResolveCommit, gitShow, gitTrackedPaths,
+  gitTreeEntry, gitUncommittedDeletions, isSafeRef, type CommitMeta,
+} from '../util/git.ts';
+import { isWithin, nameForm, normalizePath, samePath } from '../util/paths.ts';
+import { extractIds, redactCredentials, revisionSourceId } from './anchor.ts';
+
+/** Material that exists only in history: read from version history, or judged `History only` (a recovery-only place). */
+export function isHistoryOnly(source: Source): boolean {
+  return source.anchor.kind === 'revision' || source.usedAs === 'History only';
+}
+
+/** Same bound as a project file read into sources (sources/files.ts). */
+export const MAX_REVISION_BYTES = 2_000_000;
+
+/** Documents: what the intent material of a project is written in (design, plan, decision, review). */
+const DOC_RE = /\.(md|markdown|mdx|txt|text|rst|adoc|asciidoc|org|textile|wiki|html?)$/i;
+export const isDocumentPath = (path: string): boolean => DOC_RE.test(path);
+
+export interface HistoryTarget {
+  readonly item: ScopeItem;
+  /** Where git runs: the scope item's own checkout. */
+  readonly root: string;
+  /** The repository whose history it is: a worktree of the main repository shares the main repository's. */
+  readonly repo: string;
+  /** Relative to the root, forward slashes; '' for the root itself. */
+  readonly rel: string;
+}
+
+const repoItems = (project: Project): ScopeItem[] =>
+  project.scope.filter((i) => (i.category === 'Repository' || i.category === 'Worktree') && i.relation !== 'Excluded' && !i.missing);
+
+/**
+ * Which repository and path a call means: `repo` names a scope item by id or path; an absolute path picks the
+ * repository that holds it; otherwise the main repository. A path that leaves the repository is refused.
+ */
+export function resolveTarget(project: Project, input: { readonly path?: string; readonly repo?: string }): HistoryTarget | string {
+  const repos = repoItems(project);
+  if (repos.length === 0) return 'This project has no repository in its scope, so there is no version history to read.';
+  const raw = (input.path ?? '').trim();
+  let item: ScopeItem | undefined;
+  const repoArg = (input.repo ?? '').trim();
+  if (repoArg) {
+    item = repos.find((i) => i.id === repoArg) ?? repos.find((i) => samePath(i.path, repoArg));
+    if (!item) return `${repoArg} is not a repository or worktree in this project’s scope. Use one of: ${repos.map((i) => `${i.id} (${i.path})`).join(', ')}.`;
+  } else if (raw && isAbsolute(raw)) {
+    item = repos.filter((i) => isWithin(i.path, raw)).sort((a, b) => b.path.length - a.path.length)[0];
+    if (!item) return `${raw} is not inside a repository of this project’s scope.`;
+  } else {
+    item = repos.find((i) => i.relation === 'Main project' && i.category === 'Repository') ?? repos.find((i) => i.category === 'Repository') ?? repos[0]!;
+  }
+  const root = item.path;
+  let rel = raw;
+  if (raw && isAbsolute(raw)) {
+    if (!isWithin(root, raw)) return `${raw} is not inside ${root}.`;
+    rel = relative(normalizePath(root), normalizePath(raw));
+  }
+  // In the form names are kept in: a path copied from a directory listing on a Mac is in another one than git's.
+  rel = nameForm(rel).split('\\').join('/').replace(/^\.\/+/, '').replace(/\/+$/, '');
+  if (rel === '.') rel = '';
+  if (rel.split('/').some((seg) => seg === '..') || /^[A-Za-z]:/.test(rel) || rel.startsWith('/')) return `${raw} leaves the repository; give a path inside ${root}.`;
+  const repo = item.category === 'Worktree' && item.relation === 'Worktree of main repo' && item.worktreeOf ? item.worktreeOf : root;
+  return { item, root, repo, rel };
+}
+
+export type Change = 'Added' | 'Modified' | 'Deleted' | 'Renamed' | 'Copied' | 'Type changed';
+const CHANGE: Record<string, Change> = { A: 'Added', M: 'Modified', D: 'Deleted', R: 'Renamed', C: 'Copied', T: 'Type changed' };
+
+export interface HistoryRow {
+  readonly commit: string;
+  readonly at: string;
+  readonly author: string;
+  readonly subject: string;
+  readonly change: Change;
+  readonly path: string;
+  readonly from?: string;
+  readonly to?: string;
+  /** The commit whose tree holds this version: the commit itself, or for a deletion the last commit that had it. */
+  readonly readAt: string | null;
+}
+
+/**
+ * Every commit that touched a path (for a directory: anything under it), newest first, a page at a time: `limit` commits
+ * (default 100) after the first `offset`. Paging reaches the whole history (D77: no recent-N cap).
+ */
+export function pathHistory(project: Project, input: { readonly path: string; readonly repo?: string; readonly limit?: number; readonly offset?: number }): { target: HistoryTarget; rows: HistoryRow[]; more: boolean; offset: number; next: number | null } | string {
+  const target = resolveTarget(project, input);
+  if (typeof target === 'string') return target;
+  if (!target.rel) return 'Give a path inside the repository (a file or a directory).';
+  const limit = Math.max(1, Math.floor(Number(input.limit) || 100));
+  const offset = Math.max(0, Math.floor(Number(input.offset) || 0));
+  const commits = gitPathHistory(target.root, target.rel, limit + 1, 'HEAD', offset);
+  if (!commits) return `git could not read the history of ${target.rel} in ${target.root}.`;
+  const rows: HistoryRow[] = [];
+  for (const c of commits.slice(0, limit)) {
+    for (const ch of c.changes) {
+      const renamedAway = (ch.status === 'R' || ch.status === 'C') && ch.from !== null && (ch.from === target.rel || ch.from.startsWith(`${target.rel}/`)) && !(ch.path === target.rel || ch.path.startsWith(`${target.rel}/`));
+      rows.push({
+        commit: c.hash, at: c.at, author: c.author, subject: c.subject, change: CHANGE[ch.status]!,
+        path: renamedAway ? ch.from! : ch.path,
+        ...(ch.status === 'R' || ch.status === 'C' ? (renamedAway ? { to: ch.path } : { from: ch.from! }) : {}),
+        readAt: ch.status === 'D' || renamedAway ? (c.parents[0] ?? null) : c.hash,
+      });
+    }
+  }
+  const more = commits.length > limit;
+  return { target, rows, more, offset, next: more ? offset + limit : null };
+}
+
+export type RevisionRead =
+  | { readonly kind: 'history'; readonly source: Source; readonly target: HistoryTarget; readonly meta: CommitMeta | null; readonly text: string; readonly nowAtPath: 'Changed since' | 'Not at this path now' }
+  | { readonly kind: 'current'; readonly target: HistoryTarget; readonly commit: string; readonly file: string; readonly sourceIds: readonly string[] };
+
+/**
+ * A file as it was at a commit. When it is exactly what the project has at that path now, it is current material and
+ * nothing is recorded as history; otherwise it becomes (or refreshes) the `History only` source of that repository,
+ * commit and path. The refusals say what to do instead: a deleted file is read at the last commit that had it.
+ */
+export function readRevision(store: ProjectStore, project: Project, input: { readonly path: string; readonly commit: string; readonly repo?: string }): RevisionRead | string {
+  const target = resolveTarget(project, input);
+  if (typeof target === 'string') return target;
+  if (!target.rel) return 'Give the path of a file inside the repository.';
+  const ref = (input.commit ?? '').trim();
+  if (!isSafeRef(ref)) return `“${ref}” is not a commit: give a commit hash, a branch or tag name, or HEAD (optionally with ~n or ^); anything shaped like an option is refused, because history is read with read-only commands only.`;
+  const commit = gitResolveCommit(target.root, ref);
+  if (!commit) return `${ref} names no commit in ${target.root}. pk_history_log lists the commits that touched ${target.rel}.`;
+  const entry = gitTreeEntry(target.root, commit, target.rel);
+  if (!entry) {
+    const touched = gitPathHistory(target.root, target.rel, 1, commit)?.[0];
+    const gone = touched?.changes.some((c) => c.status === 'D' || (c.status === 'R' && c.from === target.rel));
+    if (touched && gone && touched.parents[0]) {
+      return `${target.rel} is not in ${commit.slice(0, 10)}: it was deleted (or moved away) in ${touched.hash.slice(0, 10)} (“${touched.subject}”), and its last version is at ${touched.parents[0].slice(0, 10)}. Read it there: commit "${touched.parents[0]}".`;
+    }
+    if (touched) return `${target.rel} is not a file in ${commit.slice(0, 10)}; the last commit up to it that touched the path is ${touched.hash.slice(0, 10)} (“${touched.subject}”). pk_history_log lists its versions.`;
+    return `${target.rel} is not in ${commit.slice(0, 10)}, and no commit up to it ever touched that path.`;
+  }
+  if (entry.type !== 'blob') return `${target.rel} is a ${entry.type === 'tree' ? 'directory' : 'submodule'} at ${commit.slice(0, 10)}; read one file at a time (pk_history_log lists what changed under a directory).`;
+  if (entry.size !== null && entry.size > MAX_REVISION_BYTES) return `${target.rel} is ${entry.size} bytes at ${commit.slice(0, 10)}, larger than the ${MAX_REVISION_BYTES} bytes a source holds.`;
+  const file = join(target.root, ...target.rel.split('/'));
+  if (existsSync(file) && gitHashWorkingFile(target.root, file, target.rel) === entry.id) {
+    const sourceIds = store.sources.filter((s) => s.anchor.kind === 'file' && samePath(s.anchor.path, file) && s.availability === null).map((s) => s.id);
+    return { kind: 'current', target, commit, file, sourceIds };
+  }
+  const text = gitShow(target.root, commit, target.rel);
+  if (text === null) return `git could not read ${target.rel} at ${commit.slice(0, 10)}.`;
+  if (text.slice(0, 8000).includes('\0')) return `${target.rel} at ${commit.slice(0, 10)} is not a text file.`;
+  const meta = gitCommitMeta(target.root, commit);
+  const red = redactCredentials(text);
+  const id = revisionSourceId(target.repo, commit, target.rel);
+  const previous = store.sources.get(id);
+  const name = target.rel.split('/').pop()!;
+  const source: Source = {
+    id, projectId: project.id, title: `${name} @ ${commit.slice(0, 8)}${meta ? ` · ${meta.at.slice(0, 10)}` : ''}`,
+    anchor: { kind: 'revision', repo: target.repo, commit, path: target.rel }, ids: extractIds(text),
+    version: { fingerprint: fingerprint(text), readAt: previous?.version.readAt ?? new Date().toISOString(), commit }, excerpt: red.text,
+    usedAs: 'History only', usedAsBy: 'keeper', usedAsByRuleId: null, availability: null, movedTo: null,
+    scopeItemId: target.item.id, hasCredential: red.found, bytes: Buffer.byteLength(text),
+  };
+  return { kind: 'history', source, target, meta, text: red.text, nowAtPath: existsSync(file) ? 'Changed since' : 'Not at this path now' };
+}
+
+export interface DeletedDocument {
+  readonly path: string;
+  readonly deletedIn: { readonly commit: string; readonly at: string; readonly author: string; readonly subject: string } | 'uncommitted';
+  readonly lastPresentIn: string | null;
+}
+export interface DeletedDirectory {
+  readonly dir: string;
+  readonly count: number;
+  readonly lastDeletedAt: string | null;
+  readonly files: readonly DeletedDocument[];
+}
+
+/**
+ * What main's history deleted and the current version does not have again, grouped by directory, each with the commit
+ * that deleted it and the last commit it appears in. Documents only unless `all`; a rename is not a deletion; a
+ * deletion in the working tree not committed yet is listed as such.
+ */
+export function deletedDocuments(project: Project, input: { readonly repo?: string; readonly dir?: string; readonly all?: boolean }): { target: HistoryTarget; head: string | null; directories: DeletedDirectory[]; total: number } | string {
+  const target = resolveTarget(project, { repo: input.repo, path: input.dir });
+  if (typeof target === 'string') return target;
+  const head = gitResolveCommit(target.root, 'HEAD');
+  if (!head) return `${target.root} has no commit yet.`;
+  const deleted = gitDeletedPaths(target.root, 'HEAD', target.rel || null);
+  if (!deleted) return `git could not read the deletions in ${target.root}.`;
+  const present = gitTrackedPaths(target.root, 'HEAD', target.rel || null) ?? new Set<string>();
+  const docs: DeletedDocument[] = [];
+  const keep = (path: string) => (input.all === true || isDocumentPath(path)) && !present.has(path) && !existsSync(join(target.root, ...path.split('/')));
+  for (const d of deleted) {
+    if (!keep(d.path)) continue;
+    docs.push({ path: d.path, deletedIn: { commit: d.deletedIn.hash, at: d.deletedIn.at, author: d.deletedIn.author, subject: d.deletedIn.subject }, lastPresentIn: d.deletedIn.parents[0] ?? null });
+  }
+  const listed = new Set(docs.map((d) => d.path));
+  for (const path of gitUncommittedDeletions(target.root)) {
+    if (listed.has(path) || !(input.all === true || isDocumentPath(path))) continue;
+    if (target.rel && !(path === target.rel || path.startsWith(`${target.rel}/`))) continue;
+    docs.push({ path, deletedIn: 'uncommitted', lastPresentIn: head });
+  }
+  const byDir = new Map<string, DeletedDocument[]>();
+  for (const d of docs) {
+    const dir = d.path.includes('/') ? d.path.slice(0, d.path.lastIndexOf('/')) : '.';
+    const list = byDir.get(dir) ?? [];
+    list.push(d);
+    byDir.set(dir, list);
+  }
+  const atOf = (d: DeletedDocument) => (d.deletedIn === 'uncommitted' ? '9999' : d.deletedIn.at);
+  const directories = [...byDir].map(([dir, files]) => {
+    const sorted = [...files].sort((a, b) => atOf(b).localeCompare(atOf(a)) || a.path.localeCompare(b.path));
+    const dated = sorted.map((f) => (f.deletedIn === 'uncommitted' ? null : f.deletedIn.at)).filter((x): x is string => x !== null);
+    return { dir, count: files.length, lastDeletedAt: dated[0] ?? null, files: sorted };
+  }).sort((a, b) => b.count - a.count || a.dir.localeCompare(b.dir));
+  return { target, head, directories, total: docs.length };
+}

package/src/sources/scan-worker.ts

@@ -0,0 +1,10 @@
+/**
+ * Worker-thread entry for `scanFilesAsync`: reads every file in scope off the main thread so the
+ * workbench keeps answering while a large project is taken in.
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+import type { ScopeItem } from '../model/types.ts';
+import { scanFiles } from './files.ts';
+
+const data = workerData as { projectId: string; scope: readonly ScopeItem[] };
+parentPort!.postMessage(scanFiles(data.projectId, data.scope));

package/src/sources/sessions/locate.ts

@@ -0,0 +1,292 @@
+/**
+ * Locate native session logs that belong to a set of working directories.
+ *
+ * Claude Code: `~/.claude/projects/<encoded cwd>/<sessionId>.jsonl` (the directory name is
+ * the encoding of the cwd; sub-agent transcripts live in a same-named subdirectory).
+ * Codex: `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`; the first line (`session_meta`) carries `cwd`. More Codex
+ * homes (a second account kept in `~/.codex-2`, say) are named in `PROJECTKEEPER_CODEX_HOMES`.
+ *
+ * Reading is by peeking at the head of each file; results are cached per file identity so a
+ * rescan only touches new or changed files. Nothing here writes anywhere.
+ *
+ * Both hosts record the working directory in the spelling the agent ran under — through a junction or a link, a
+ * `subst` drive, an 8.3 short name, another case — while the directories asked for are in the file system's own
+ * (util/paths.ts `canonicalPath`). A log belongs to a directory asked for when the two are one directory by the file
+ * system's judgement (`directoryKey`), not only when they are one text. For Claude Code that means looking past the
+ * folder named after the directory: the head of one log in each other folder is read once for the directory it
+ * records, and nothing else of it is kept.
+ */
+import { closeSync, existsSync, openSync, readSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, delimiter, join, resolve } from 'node:path';
+import type { SessionHost } from '../../model/vocab.ts';
+import { claudeProjectDirName, directoryKey, normalizePath, pathKey } from '../../util/paths.ts';
+
+export interface LocatedSession {
+  readonly host: SessionHost;
+  readonly file: string;
+  /** The working directory as the log records it, in the spelling the agent ran under; the directory asked for when a Claude Code log names none. */
+  readonly cwd: string | null;
+  /** The one of the directories asked for that `cwd` is — the same text, or another spelling of that directory; null when it is none of them. */
+  readonly matchedCwd: string | null;
+  readonly sessionId: string;
+  readonly bytes: number;
+  readonly mtimeMs: number;
+  readonly isSubagent: boolean;
+  readonly home: string;         // which host home it came from
+}
+
+const PEEK_BYTES = 8192;
+const peekCache = new Map<string, { size: number; mtimeMs: number; cwd: string | null; sessionId: string | null; sub: boolean }>();
+export interface CodexSessionHeader {
+  readonly cwd: string;
+  readonly sessionId: string | null;
+  readonly sub: boolean;
+}
+const codexHeaderCache = new Map<string, { size: number; mtimeMs: number; header: CodexSessionHeader | null }>();
+
+function peek(file: string): { cwd: string | null; sessionId: string | null; sub: boolean } {
+  const st = statSync(file);
+  const hit = peekCache.get(file);
+  if (hit && hit.size === st.size && hit.mtimeMs === st.mtimeMs) return hit;
+  let fd: number | null = null;
+  let head = '';
+  try {
+    fd = openSync(file, 'r');
+    const buf = Buffer.alloc(PEEK_BYTES);
+    const n = readSync(fd, buf, 0, PEEK_BYTES, 0);
+    head = buf.subarray(0, n).toString('utf8');
+  } catch {
+    head = '';
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+  const cwdMatch = /"cwd"\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(head);
+  const idMatch = /"session_id"\s*:\s*"([^"]+)"/.exec(head) ?? /"sessionId"\s*:\s*"([^"]+)"/.exec(head);
+  let cwd: string | null = null;
+  try { cwd = cwdMatch?.[1] ? (JSON.parse(`"${cwdMatch[1]}"`) as string) : null; } catch { cwd = null; }
+  const sub = /"thread_source"\s*:\s*"subagent"/.test(head) || /"isSidechain"\s*:\s*true/.test(head);
+  const entry = { size: st.size, mtimeMs: st.mtimeMs, cwd, sessionId: idMatch?.[1] ?? null, sub };
+  peekCache.set(file, entry);
+  return entry;
+}
+
+/**
+ * Read only a Codex log's first record. Ownership comes from the `session_meta` header; a `cwd` appearing later in an
+ * unrelated session's body is never considered. The fixed-size peek also keeps live watching from opening unrelated
+ * conversation content merely because some other project changed it.
+ */
+export function readCodexSessionHeader(file: string): CodexSessionHeader | null {
+  let st;
+  try { st = statSync(file); } catch { return null; }
+  if (!st.isFile()) return null;
+  const hit = codexHeaderCache.get(file);
+  if (hit && hit.size === st.size && hit.mtimeMs === st.mtimeMs) return hit.header;
+
+  let fd: number | null = null;
+  let head = '';
+  try {
+    fd = openSync(file, 'r');
+    const buf = Buffer.alloc(PEEK_BYTES);
+    const n = readSync(fd, buf, 0, PEEK_BYTES, 0);
+    head = buf.subarray(0, n).toString('utf8');
+  } catch {
+    head = '';
+  } finally {
+    if (fd !== null) closeSync(fd);
+  }
+
+  // Even when a very large session_meta line exceeds PEEK_BYTES, its type, id and cwd are at the front. When the
+  // first line is short, cut before the body so a later cwd cannot be mistaken for the header's.
+  const end = head.search(/[\r\n]/);
+  const first = end >= 0 ? head.slice(0, end) : head;
+  let header: CodexSessionHeader | null = null;
+  if (/"type"\s*:\s*"session_meta"/.test(first)) {
+    const cwdMatch = /"cwd"\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(first);
+    const idMatch = /"id"\s*:\s*"([^"\\]*(?:\\.[^"\\]*)*)"/.exec(first)
+      ?? /"session_id"\s*:\s*"([^"\\]*(?:\\.[^"\\]*)*)"/.exec(first);
+    let cwd: string | null = null;
+    let sessionId: string | null = null;
+    try { cwd = cwdMatch?.[1] ? (JSON.parse(`"${cwdMatch[1]}"`) as string) : null; } catch { cwd = null; }
+    try { sessionId = idMatch?.[1] ? (JSON.parse(`"${idMatch[1]}"`) as string) : null; } catch { sessionId = null; }
+    if (cwd) header = { cwd, sessionId, sub: /"thread_source"\s*:\s*"subagent"/.test(first) };
+  }
+  codexHeaderCache.set(file, { size: st.size, mtimeMs: st.mtimeMs, header });
+  return header;
+}
+
+/**
+ * For a set of directories asked for: which of them a directory a log records is, or null. The text is compared first
+ * (case and slashes as the system allows); a directory spelled otherwise is asked of the file system, once. Most of
+ * the directories an agent's history records are gone (worktrees, mostly), and one that is gone is rarely worth
+ * asking about: it cannot be another spelling of a directory that is there, and of one that is gone too only under the
+ * same last name, which is compared as text either way.
+ */
+export function cwdMatcher(cwds: readonly string[]): (recorded: string | null) => string | null {
+  const byText = new Map<string, string>();
+  for (const cwd of cwds) if (!byText.has(pathKey(cwd))) byText.set(pathKey(cwd), normalizePath(cwd));
+  let byDirectory: Map<string, string> | null = null;
+  const goneNames = new Set<string>();
+  const asked = new Map<string, string | null>();
+  return (recorded) => {
+    if (!recorded) return null;
+    const key = pathKey(recorded);
+    const text = byText.get(key);
+    if (text !== undefined) return text;
+    if (asked.has(key)) return asked.get(key)!;
+    if (!byDirectory) {
+      byDirectory = new Map();
+      for (const [cwdKey, cwd] of byText) {
+        if (!byDirectory.has(directoryKey(cwd))) byDirectory.set(directoryKey(cwd), cwd);
+        if (!existsSync(cwd)) goneNames.add(basename(cwdKey));
+      }
+    }
+    const worthAsking = existsSync(recorded) || goneNames.has(basename(key));
+    const hit = worthAsking ? byDirectory.get(directoryKey(recorded)) ?? null : null;
+    asked.set(key, hit);
+    return hit;
+  };
+}
+
+export function claudeProjectsRoot(home = homedir()): string {
+  return join(home, '.claude', 'projects');
+}
+
+/**
+ * The Codex homes under a user home: `.codex`, then every directory named in `PROJECTKEEPER_CODEX_HOMES` (separated like
+ * `PATH`; a name is taken under the user home, so a frozen copy of a home is read the same way; an absolute path as it is).
+ */
+export function codexHomes(home = homedir(), extra = process.env.PROJECTKEEPER_CODEX_HOMES ?? ''): string[] {
+  const named = extra.split(delimiter).map((d) => d.trim()).filter((d) => d !== '');
+  return [...new Set([join(home, '.codex'), ...named.map((d) => resolve(home, d))])];
+}
+
+export function codexSessionRoots(home = homedir()): string[] {
+  return codexHomes(home).map((d) => join(d, 'sessions')).filter((p) => existsSync(p));
+}
+
+/** How many logs of a Claude Code folder are asked which directory the folder is for, before it is passed over. */
+const FOLDER_PEEKS = 8;
+/** The directory each Claude Code folder is for, once one of its logs has said: a folder is named after it, so it stays. */
+const folderCwdCache = new Map<string, string>();
+
+/**
+ * The directory a Claude Code folder holds the sessions of, in the spelling its logs record. The folder's name is that
+ * directory's, encoded, so a log that records a directory with another name does not speak for the folder.
+ */
+function folderCwd(folder: string, name: string): string | null {
+  const known = folderCwdCache.get(folder);
+  if (known !== undefined) return known;
+  let entries: string[] = [];
+  try { entries = readdirSync(folder); } catch { return null; }
+  for (const entry of entries.filter((e) => e.endsWith('.jsonl')).slice(0, FOLDER_PEEKS)) {
+    let cwd: string | null = null;
+    try { cwd = peek(join(folder, entry)).cwd; } catch { continue; }
+    if (cwd && claudeProjectDirName(cwd).toLowerCase() === name.toLowerCase()) { folderCwdCache.set(folder, cwd); return cwd; }
+  }
+  return null;
+}
+
+/**
+ * The folders under a home's `.claude/projects` that hold the sessions of the given working directories, each with
+ * the directory it is for: the folder named after the directory, and any folder named after another spelling of it.
+ */
+export function claudeSessionFolders(cwds: readonly string[], home = homedir()): { readonly dir: string; readonly cwd: string }[] {
+  const root = claudeProjectsRoot(home);
+  let names: string[] = [];
+  try { names = readdirSync(root); } catch { return []; }
+  const named = new Map<string, string>();
+  for (const cwd of cwds) named.set(claudeProjectDirName(cwd).toLowerCase(), normalizePath(cwd));
+  const matched = cwdMatcher(cwds);
+  const out: { dir: string; cwd: string }[] = [];
+  for (const name of names) {
+    const dir = join(root, name);
+    const cwd = named.get(name.toLowerCase()) ?? matched(folderCwd(dir, name));
+    if (cwd) out.push({ dir, cwd });
+  }
+  return out;
+}
+
+/** Claude Code sessions for the given working directories (the directory itself, under any spelling; not what lies in it). */
+export function locateClaudeSessions(cwds: readonly string[], home = homedir()): LocatedSession[] {
+  const root = claudeProjectsRoot(home);
+  const matched = cwdMatcher(cwds);
+  const out: LocatedSession[] = [];
+  for (const { dir, cwd } of claudeSessionFolders(cwds, home)) {
+    let entries: string[] = [];
+    try { entries = readdirSync(dir); } catch { continue; }
+    for (const name of entries) {
+      if (!name.endsWith('.jsonl')) continue;
+      const file = join(dir, name);
+      let st;
+      try { st = statSync(file); } catch { continue; }
+      if (!st.isFile()) continue;
+      const info = peek(file);
+      out.push({
+        host: 'claude', file, cwd: info.cwd ?? cwd, matchedCwd: info.cwd ? matched(info.cwd) : cwd, sessionId: name.slice(0, -'.jsonl'.length),
+        bytes: st.size, mtimeMs: st.mtimeMs, isSubagent: info.sub, home: root,
+      });
+    }
+  }
+  return out.sort((a, b) => a.mtimeMs - b.mtimeMs);
+}
+
+function walkJsonl(dir: string, depth: number, into: string[]): void {
+  if (depth > 4) return;
+  let entries: string[] = [];
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const name of entries) {
+    const full = join(dir, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) walkJsonl(full, depth + 1, into);
+    else if (name.endsWith('.jsonl')) into.push(full);
+  }
+}
+
+/** Codex sessions (every home) whose recorded cwd is one of the given directories, under any spelling. */
+export function locateCodexSessions(cwds: readonly string[], home = homedir()): LocatedSession[] {
+  const matched = cwdMatcher(cwds);
+  const out: LocatedSession[] = [];
+  for (const root of codexSessionRoots(home)) {
+    const files: string[] = [];
+    walkJsonl(root, 0, files);
+    for (const file of files) {
+      const info = readCodexSessionHeader(file);
+      const matchedCwd = info ? matched(info.cwd) : null;
+      if (!info || !matchedCwd) continue;
+      let st;
+      try { st = statSync(file); } catch { continue; }
+      const stem = file.split(/[\\/]/).pop()!.replace(/\.jsonl$/, '');
+      out.push({
+        host: 'codex', file, cwd: normalizePath(info.cwd), matchedCwd,
+        sessionId: info.sessionId ?? stem.replace(/^rollout-\d{4}-\d{2}-\d{2}T[\d-]+-/, ''),
+        bytes: st.size, mtimeMs: st.mtimeMs, isSubagent: info.sub, home: root,
+      });
+    }
+  }
+  return out.sort((a, b) => a.mtimeMs - b.mtimeMs);
+}
+
+export function locateSessions(cwds: readonly string[], home = homedir()): LocatedSession[] {
+  return [...locateClaudeSessions(cwds, home), ...locateCodexSessions(cwds, home)];
+}
+
+/** Locate each cwd in its selected native home; a frozen copy never falls back to the live host's logs. */
+export function locateSessionsForHomes(cwds: readonly string[], homeFor: (host: 'claude' | 'codex', cwd: string) => string): LocatedSession[] {
+  const out: LocatedSession[] = [];
+  for (const host of ['claude', 'codex'] as const) {
+    const groups = new Map<string, { home: string; cwds: string[] }>();
+    for (const cwd of cwds) {
+      const home = normalizePath(homeFor(host, cwd));
+      const key = pathKey(home);
+      const group = groups.get(key) ?? { home, cwds: [] };
+      group.cwds.push(cwd);
+      groups.set(key, group);
+    }
+    for (const group of groups.values()) out.push(...(host === 'claude'
+      ? locateClaudeSessions(group.cwds, group.home)
+      : locateCodexSessions(group.cwds, group.home)));
+  }
+  return out;
+}