Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
28.0 KB
Raw Blame
/**
 * The touched-files archive (policy `touched_files`, README "Touched
 * files"): in a session folder that is neither a git repository nor inside
 * one, only the files the agent touched there are archived, byte for byte.
 * The session uploader reports every path the session touched (the trace's tool
 * paths, the watcher's changes); TouchedPathStore keeps them per session on
 * disk, and scanTouchedFiles turns them into archive entries at capture
 * time: regular files inside the root only, never through a symlinked
 * folder, a touched folder never expanded, with the whole-folder scan's
 * exclusions, and never a file git ignores (`ignore.ts`) unless the caller
 * keeps ignored files (includeIgnored: the archiver always does). Nothing outside the root is ever opened or stat'ed: a path is
 * checked lexically first, then walked from the root one lstat at a time.
 */
import { createHash } from "node:crypto";
import type { BigIntStats } from "node:fs";
import { appendFile, lstat, open, readdir, readFile, readlink, realpath, rm, writeFile } from "node:fs/promises";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";

import {
  HASH_CONCURRENCY,
  HASH_READ_BYTES,
  OPEN_ENTRY_FLAGS,
  OUTSIDE_ROOT_NAME,
  ENCLOSING_REPO_ROOT_NAME,
  RESERVED_ROOT_NAME,
  STAT_CONCURRENCY,
  compareArchivePaths,
  decodeName,
  emptyExcludedCounts,
  excludedRelativeDirs,
  forEachBounded,
  isArchiveCredentialPath,
  isArchiveEntryModified,
  isSameFileIdentity,
  portable,
  statFields,
  type ArchiveEntry,
  type ArchiveHashCache,
  type ExcludedCounts,
  type ScannedEntry,
} from "./manifest.js";
import { isArchiveCodeFile, needsCodeCheck, readCleanCodeFile } from "./code-files.js";
import { stateKey } from "./files.js";
import { touchedIgnoredPaths } from "./ignore.js";
import { REGENERABLE_DIR_NAMES } from "../session-uploader.js";
import type { ArchiveLog } from "./upload.js";
import { outsideArchivePath } from "./outside.js";

/** A session keeps at most this many touched paths; later ones are not archived (one log line). */
export const MAX_TOUCHED_PATHS = 100_000;
const MAX_TOUCHED_PATH_CHARS = 4_096;
/** A touched symlink is followed to a file inside the root through at most this many links. */
const MAX_LINK_HOPS = 8;
/** Reported paths reach the session's file within this long. */
const TOUCHED_FLUSH_MS = 2_000;
const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;

// --- scan -------------------------------------------------------------------------

export type TouchedScanOptions = {
  /** Absolute app state/temp/data directories; a path under one inside the root is counted as app_state. */
  excludedDirs?: readonly string[];
  /** archiveIncludeCredentialFiles: turns the credential filter off entirely. */
  includeCredentialFiles?: boolean;
  /** The root's hash cache; the scan looks up and adds entries and never prunes it (it sees only part of the root). */
  hashCache?: ArchiveHashCache;
  /** Stops the scan between paths: it then rejects with the signal's reason. */
  signal?: AbortSignal;
  /** Gitignored files are kept (the reproducible-task rule: touched files and lockfiles are archived even when ignored). */
  includeIgnored?: boolean;
  /** Tests: every absolute path the scan lstats, reads a link of or opens, before it does. */
  onAccess?: (path: string) => void;
};

export type TouchedScanResult = {
  /** The touched regular files inside the root, sorted by UTF-8 bytes. */
  entries: ScannedEntry[];
  /**
   * Touched paths that hold no regular file inside the root any more: gone,
   * a folder, a symlink, a special file, or reached through a folder that is
   * no longer a real folder, or a file git now ignores. A delta deletes
   * those it archived before.
   */
  gone: Set<string>;
  excluded: ExcludedCounts;
  /** Touched files left out because git ignores them (not in `excluded`, section 5.6 is unchanged). */
  ignored: number;
};

/** A touched path's components when it is a plain relative path (portable `/`), else null. */
export function touchedPathParts(path: string): string[] | null {
  if (!path || path.length > MAX_TOUCHED_PATH_CHARS || path.includes("\0") || path.startsWith("/")) return null;
  const parts = path.split("/");
  if (parts.some((part) => part === "" || part === "." || part === "..")) return null;
  // Windows: no drive, no stream (`file:stream`), no separator inside a name.
  if (sep === "\\" && parts.some((part) => part.includes("\\") || part.includes(":"))) return null;
  return parts;
}

/**
 * Whether a reported path is an absolute path outside the workspace that the
 * store keeps apart from the workspace-relative ones (outside.ts archives
 * those under `__outside__/`).
 */
export function isOutsideTouchedPath(path: string): boolean {
  return typeof path === "string" && isAbsolute(path) && resolve(path) === path && outsideArchivePath(path) !== null;
}

type DirState = "dir" | "gone" | "unreadable";

function missing(error: unknown): boolean {
  const code = error instanceof Error && "code" in error ? error.code : undefined;
  return code === "ENOENT" || code === "ENOTDIR";
}

/**
 * The root-relative path a symlink at `path` (absolute, under real folders)
 * points to, when it stays inside the root: resolved lexically against the
 * root as given and as its real path, so that nothing outside is looked at.
 * Null when it points outside, at the root itself, or cannot be read.
 */
function linkTargetInside(path: string, target: string, roots: readonly string[]): string | null {
  const absolute = isAbsolute(target) ? resolve(target) : resolve(dirname(path), target);
  for (const root of roots) {
    const rel = relative(root, absolute);
    if (rel && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel)) return portable(rel);
  }
  return null;
}

/** Lockfiles and dependency pins, archived in full wherever they sit (outside the regenerable folders). */
const LOCKFILE_NAMES = new Set([
  "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml", "bun.lock", "bun.lockb", "deno.lock",
  "Cargo.lock", "poetry.lock", "Pipfile.lock", "uv.lock", "pdm.lock", "pixi.lock", "conda-lock.yml",
  "Gemfile.lock", "composer.lock", "go.sum", "go.work.sum", "mix.lock", "pubspec.lock", "Package.resolved",
  "packages.lock.json", "gradle.lockfile", "flake.lock", "Podfile.lock", "Cartfile.resolved",
  // Capture v2 (#4): more ecosystems' pins.
  "renv.lock", "Manifest.toml", "paket.lock", "stack.yaml.lock", "cabal.project.freeze", "shard.lock",
  "requirements.lock", "requirements-dev.lock", "vcpkg-lock.json", "MODULE.bazel.lock",
]);
const LOCKFILE_MAX_DEPTH = 8;
const LOCKFILE_MAX_DIRS = 20_000;
const LOCKFILE_MAX_FOUND = 1_000;

/**
 * The lockfiles under `root`, workspace-relative and portable: a bounded walk
 * (depth, folders visited, results) that never follows a symlink and skips
 * `.git/` and the regenerable folders. scanTouchedFiles checks each one again
 * before anything is archived. Never throws.
 */
export async function findLockfiles(root: string, signal?: AbortSignal): Promise<string[]> {
  const found: string[] = [];
  let visited = 0;
  const walk = async (rel: string, depth: number): Promise<void> => {
    if (depth > LOCKFILE_MAX_DEPTH || visited >= LOCKFILE_MAX_DIRS || found.length >= LOCKFILE_MAX_FOUND || signal?.aborted) return;
    visited += 1;
    let entries;
    try {
      entries = await readdir(rel ? join(root, ...rel.split("/")) : root, { withFileTypes: true });
    } catch {
      return;
    }
    entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
    for (const entry of entries) {
      const path = rel ? `${rel}/${entry.name}` : entry.name;
      if (entry.isFile() && LOCKFILE_NAMES.has(entry.name)) {
        if (found.length < LOCKFILE_MAX_FOUND) found.push(path);
      } else if (entry.isDirectory() && entry.name !== ".git" && !REGENERABLE_DIR_NAMES.has(entry.name)) {
        await walk(path, depth + 1);
      }
    }
  };
  await walk("", 0);
  return found;
}

/**
 * Pass 1 of a touched-files capture: each path (and each symlink target
 * inside the root it leads to) walked from the root with lstat, never
 * following a link, then hashed; excluded like the whole-folder scan
 * (credential files, app state, reserved names, special files, unreadable
 * and non-UTF-8 names), and a file git ignores is left out (and deletes a
 * copy the chain holds, like a gone file). A path that is not plain, or whose link leads out of
 * the root, is skipped without touching the file system outside the root.
 */
export async function scanTouchedFiles(root: string, paths: Iterable<string>, options: TouchedScanOptions = {}): Promise<TouchedScanResult> {
  const { signal, hashCache: cache } = options;
  const access = options.onAccess ?? (() => undefined);
  const base = resolve(root);
  access(base);
  const roots = [base];
  const real = await realpath(base);
  if (real !== base) roots.push(real);
  const pruned = [...(await excludedRelativeDirs(base, options.excludedDirs ?? []))];
  const includeCredentials = options.includeCredentialFiles === true;
  const excluded = emptyExcludedCounts();
  const gone = new Set<string>();
  const entries: ScannedEntry[] = [];
  const seen = new Set<string>();
  const codeChecks = new Set<ScannedEntry>();
  const dirs = new Map<string, Promise<DirState>>();

  /** Whether `relDir` is a real folder under real folders (a symlink or a file in the way is "gone": the path is not inside the root). */
  const dirState = (parts: readonly string[], depth: number): Promise<DirState> => {
    const key = parts.slice(0, depth).join("/");
    let known = dirs.get(key);
    if (!known) {
      known = (async () => {
        if (depth > 1) {
          const parent = await dirState(parts, depth - 1);
          if (parent !== "dir") return parent;
        }
        const absolute = join(base, ...parts.slice(0, depth));
        access(absolute);
        try {
          const stats = await lstat(absolute);
          return stats.isDirectory() ? "dir" : "gone";
        } catch (error) {
          return missing(error) ? "gone" : "unreadable";
        }
      })();
      dirs.set(key, known);
    }
    return known;
  };

  const visit = async (path: string, hops: number): Promise<void> => {
    signal?.throwIfAborted();
    if (seen.has(path)) return;
    seen.add(path);
    const parts = touchedPathParts(path);
    if (!parts) return;
    if (LONE_SURROGATE.test(path)) {
      excluded.non_utf8 += 1;
      return;
    }
    if (parts[0] === RESERVED_ROOT_NAME || parts[0] === OUTSIDE_ROOT_NAME || parts[0] === ENCLOSING_REPO_ROOT_NAME) {
      excluded.reserved += 1;
      return;
    }
    if (pruned.some((dir) => path === dir || path.startsWith(`${dir}/`))) {
      excluded.app_state += 1;
      return;
    }
    // A source file named like a key store is decided once it is known not to be ignored, by its content (code-files.ts).
    let codeCheck = false;
    if (!includeCredentials && (isArchiveCredentialPath(path) || needsCodeCheck(parts))) {
      if (!isArchiveCodeFile(parts)) {
        excluded.credential += 1;
        return;
      }
      codeCheck = true;
    }
    if (parts.length > 1) {
      const parent = await dirState(parts, parts.length - 1);
      if (parent === "unreadable") excluded.unreadable += 1;
      if (parent !== "dir") {
        if (parent === "gone") gone.add(path);
        return;
      }
    }
    const absolute = join(base, ...parts);
    let stats: BigIntStats;
    try {
      access(absolute);
      stats = await lstat(absolute, { bigint: true });
    } catch (error) {
      if (missing(error)) gone.add(path);
      else excluded.unreadable += 1;
      return;
    }
    if (stats.isDirectory()) {
      // A touched folder is never expanded.
      gone.add(path);
      return;
    }
    if (stats.isSymbolicLink()) {
      gone.add(path);
      let target: string | null;
      try {
        access(absolute);
        target = decodeName(await readlink(absolute, { encoding: "buffer" }));
      } catch {
        excluded.unreadable += 1;
        return;
      }
      if (target === null) {
        excluded.non_utf8 += 1;
        return;
      }
      const inside = hops < MAX_LINK_HOPS ? linkTargetInside(absolute, target, roots) : null;
      // A link out of the root (or a chain too long) is skipped: its target is never looked at.
      if (inside === null) excluded.special += 1;
      else await visit(inside, hops + 1);
      return;
    }
    if (!stats.isFile()) {
      gone.add(path);
      excluded.special += 1;
      return;
    }
    const entry: ScannedEntry = { path, type: "file", size: Number(stats.size), sha256: null, ...statFields(stats) };
    entries.push(entry);
    if (codeCheck) codeChecks.add(entry);
  };

  await forEachBounded([...paths], STAT_CONCURRENCY, (path) => visit(path, 0));

  // Source files named like key stores: never when git ignores them (even where ignored files are kept), else only with clean content.
  if (codeChecks.size > 0) {
    const ignoredCode = await touchedIgnoredPaths(base, [...codeChecks].map((entry) => entry.path), signal);
    const dropped = new Set<ScannedEntry>();
    await forEachBounded([...codeChecks], HASH_CONCURRENCY, async (entry) => {
      signal?.throwIfAborted();
      const absolute = join(base, ...entry.path.split("/"));
      access(absolute);
      const clean = ignoredCode.has(entry.path) ? null : await readCleanCodeFile(absolute, entry.path, (opened) => isSameFileIdentity(entry, opened));
      if (!clean) {
        dropped.add(entry);
        return;
      }
      // Pass 2 writes exactly the checked bytes.
      entry.content = clean.bytes;
      entry.size = clean.bytes.length;
      entry.sha256 = clean.sha256;
    });
    if (dropped.size > 0) {
      excluded.credential += dropped.size;
      // An archived file that now fails the check leaves the chain like a gone one.
      for (const entry of dropped) gone.add(entry.path);
      const remaining = entries.filter((entry) => !dropped.has(entry));
      entries.length = 0;
      entries.push(...remaining);
    }
  }

  // Git's answer for just the files found, so the folder is never walked (none asked when ignored files are kept).
  const ignoredPaths = options.includeIgnored === true ? new Set<string>() : await touchedIgnoredPaths(base, entries.map((entry) => entry.path), signal);
  signal?.throwIfAborted();
  if (ignoredPaths.size > 0) {
    let kept = 0;
    for (const entry of entries) {
      if (ignoredPaths.has(entry.path)) gone.add(entry.path);
      else entries[kept++] = entry;
    }
    entries.length = kept;
  }

  const unreadable = new Set<ScannedEntry>();
  const buffers: Buffer[] = [];
  await forEachBounded(entries, HASH_CONCURRENCY, async (entry) => {
    signal?.throwIfAborted();
    if (entry.content) return;
    const cached = cache?.lookup(entry) ?? null;
    if (cached) {
      entry.sha256 = cached;
      return;
    }
    const buffer = buffers.pop() ?? Buffer.allocUnsafe(HASH_READ_BYTES);
    try {
      const absolute = join(base, ...entry.path.split("/"));
      access(absolute);
      const sha256 = await hashTouchedFile(absolute, entry, buffer, signal);
      if (sha256 === null) {
        unreadable.add(entry);
        cache?.forget(entry.path);
        return;
      }
      entry.sha256 = sha256;
      cache?.remember(entry);
    } finally {
      buffers.push(buffer);
    }
  });
  signal?.throwIfAborted();
  for (const path of gone) cache?.forget(path);
  excluded.unreadable += unreadable.size;
  const kept = unreadable.size > 0 ? entries.filter((entry) => !unreadable.has(entry)) : entries;
  kept.sort((left, right) => compareArchivePaths(left.path, right.path));
  return { entries: kept, gone, excluded, ignored: ignoredPaths.size };
}

/** SHA-256 of the first entry.size bytes of the very file pass 1 lstat'ed (same st_dev and st_ino), else null. */
async function hashTouchedFile(absolute: string, entry: ScannedEntry, buffer: Buffer, signal?: AbortSignal): Promise<string | null> {
  let handle: Awaited<ReturnType<typeof open>>;
  try {
    handle = await open(absolute, OPEN_ENTRY_FLAGS);
  } catch {
    return null;
  }
  try {
    const stats = await handle.stat({ bigint: true });
    if (!stats.isFile() || !isSameFileIdentity(entry, stats)) return null;
    const hash = createHash("sha256");
    let remaining = entry.size;
    while (remaining > 0) {
      if (signal?.aborted) return null;
      const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, remaining), null);
      if (bytesRead === 0) break;
      hash.update(buffer.subarray(0, bytesRead));
      remaining -= bytesRead;
    }
    return hash.digest("hex");
  } catch {
    return null;
  } finally {
    await handle.close().catch(() => undefined);
  }
}

export type TouchedChange = {
  /** What the archive carries: every touched file for a base, the added and modified ones for a delta. */
  files: ScannedEntry[];
  /** Files an earlier archive of the chain holds that are gone from the folder. */
  deleted: string[];
  /** The chain's entry list after this archive: the next baseline. */
  next: ArchiveEntry[];
};

/**
 * A touched-files archive against the chain's baseline (empty for a base).
 * A baseline file the scan did not see and that is not gone (unreadable for
 * now) stays in the baseline as it was; only a gone one is deleted.
 */
export function touchedChange(baseline: readonly ArchiveEntry[], scan: TouchedScanResult): TouchedChange {
  const current = new Set(scan.entries.map((entry) => entry.path));
  const previous = new Map(baseline.map((entry) => [entry.path, entry]));
  const files = scan.entries.filter((entry) => {
    const old = previous.get(entry.path);
    return !old || isArchiveEntryModified(old, entry);
  });
  const kept = baseline.filter((entry) => !current.has(entry.path) && !scan.gone.has(entry.path));
  const deleted = baseline.filter((entry) => !current.has(entry.path) && scan.gone.has(entry.path)).map((entry) => entry.path);
  const next: ArchiveEntry[] = [...scan.entries, ...kept].sort((left, right) => compareArchivePaths(left.path, right.path));
  return { files, deleted: deleted.sort(compareArchivePaths), next };
}

// --- the touched set ------------------------------------------------------------------

type TouchedSession = {
  /** unknown until the gate has run for the session (paths wait in memory); ignored: not a touched-files chain. */
  mode: "unknown" | "tracked" | "ignored";
  /** The paths in the session's file (null until read) and those written since. */
  known: Set<string> | null;
  /** Reported and not in `known` yet. */
  pending: Set<string>;
  /** Being appended to the file right now. */
  writing: readonly string[];
  /** The file ends in a line torn by a crash: the next append starts a new line. */
  torn: boolean;
  capped: boolean;
};

/**
 * The paths each touched-files session touched, from its first prompt on:
 * appended to `<dir>/<session key>.jsonl` (a header line, then one JSON
 * string per line; a torn last line is skipped) a moment after they are
 * reported, so they survive an app restart. Paths of a session the gate has
 * not decided on yet wait in memory; `track` keeps them, `forget` drops them
 * and the file.
 */
export class TouchedPathStore {
  private readonly sessions = new Map<string, TouchedSession>();
  private readonly tails = new Map<string, Promise<void>>();
  private timer: ReturnType<typeof setTimeout> | null = null;
  /** Bumped by clear(): writes started before it never land. */
  private epoch = 0;

  constructor(
    private readonly dir: string,
    private readonly options: {
      /** Resolves once the state dir is recovered. */
      ready: () => Promise<void>;
      /** What the session's record says it is: a touched-files chain, something else, or not known yet. */
      modeOf: (sessionId: string) => Promise<"tracked" | "ignored" | "unknown">;
      log: ArchiveLog;
      flushMs?: number;
    },
  ) {}

  /**
   * A path the session uploader reported for the session: workspace-relative
   * (portable), or an absolute path outside the workspace (kept apart: see
   * outside()). Cheap: a repeat is a lookup.
   */
  note(sessionId: string, path: string): void {
    let session = this.sessions.get(sessionId);
    if (!session) {
      session = { mode: "unknown", known: null, pending: new Set(), writing: [], torn: false, capped: false };
      this.sessions.set(sessionId, session);
      const created = session;
      const epoch = this.epoch;
      void this.options.modeOf(sessionId).then((mode) => {
        if (epoch !== this.epoch || this.sessions.get(sessionId) !== created || created.mode !== "unknown" || mode === "unknown") return;
        if (mode === "tracked") this.track(sessionId);
        else this.drop(created);
      }, () => undefined);
    }
    if (session.mode === "ignored" || session.known?.has(path) || session.pending.has(path)) return;
    if (touchedPathParts(path) === null && !isOutsideTouchedPath(path)) return;
    if ((session.known?.size ?? 0) + session.pending.size + session.writing.length >= MAX_TOUCHED_PATHS) {
      if (!session.capped) this.options.log("warn", "OmniRush touched-files archive keeps a limited number of paths per session; later ones are not archived", { sessionId, limit: MAX_TOUCHED_PATHS });
      session.capped = true;
      return;
    }
    session.pending.add(path);
    if (session.mode === "tracked") this.schedule();
  }

  /** The session is a touched-files chain: its paths are kept on disk from now on. */
  track(sessionId: string): void {
    const session = this.sessions.get(sessionId);
    if (session) session.mode = "tracked";
    else this.sessions.set(sessionId, { mode: "tracked", known: null, pending: new Set(), writing: [], torn: false, capped: false });
    this.schedule();
  }

  /** The session is not (or no longer) a touched-files chain: nothing more is kept, and its file goes. */
  forget(sessionId: string): Promise<void> {
    const session = this.sessions.get(sessionId);
    if (session) this.drop(session);
    else this.sessions.set(sessionId, { mode: "ignored", known: null, pending: new Set(), writing: [], torn: false, capped: false });
    const epoch = this.epoch;
    return this.serial(sessionId, async () => {
      if (epoch === this.epoch) await rm(this.file(sessionId), { force: true });
    });
  }

  /** Every workspace-relative path the session touched: its file and what is not written yet. The session counts as tracked from now on. */
  snapshot(sessionId: string): Promise<Set<string>> {
    return this.snapshotWhere(sessionId, false);
  }

  /** Every absolute path outside the workspace the session touched, like snapshot(). */
  outside(sessionId: string): Promise<Set<string>> {
    return this.snapshotWhere(sessionId, true);
  }

  private snapshotWhere(sessionId: string, outside: boolean): Promise<Set<string>> {
    this.track(sessionId);
    return this.serial(sessionId, async () => {
      await this.write(sessionId);
      const session = this.sessions.get(sessionId);
      return new Set([...(session?.known ?? []), ...(session?.pending ?? [])].filter((path) => isOutsideTouchedPath(path) === outside));
    });
  }

  /** Whether the session has touched paths (in memory or on disk). */
  async has(sessionId: string): Promise<boolean> {
    const session = this.sessions.get(sessionId);
    if (session && session.pending.size + (session.known?.size ?? 0) > 0) return true;
    return (await this.load(sessionId)).paths.size > 0;
  }

  /** Writes every tracked session's pending paths now. */
  async flush(): Promise<void> {
    this.clearTimer();
    await Promise.all([...this.sessions].filter(([, session]) => session.mode === "tracked" && session.pending.size > 0).map(([sessionId]) => this.serial(sessionId, () => this.write(sessionId))));
  }

  /** Sign-out: everything in memory goes, and no write started before lands. */
  clear(): void {
    this.epoch += 1;
    this.clearTimer();
    this.sessions.clear();
  }

  private drop(session: TouchedSession): void {
    session.mode = "ignored";
    session.known = null;
    session.pending = new Set();
  }

  private file(sessionId: string): string {
    return join(this.dir, `${stateKey(sessionId)}.jsonl`);
  }

  private schedule(): void {
    if (this.timer) return;
    this.timer = setTimeout(() => {
      this.timer = null;
      void this.flush().catch((error: unknown) => this.options.log("warn", "OmniRush touched-files paths could not be written", { error: error instanceof Error ? error.message : "unknown" }));
    }, this.options.flushMs ?? TOUCHED_FLUSH_MS);
    this.timer.unref?.();
  }

  private clearTimer(): void {
    if (this.timer) clearTimeout(this.timer);
    this.timer = null;
  }

  /** Runs `task` after the session's earlier file work. */
  private serial<T>(sessionId: string, task: () => Promise<T>): Promise<T> {
    const previous = this.tails.get(sessionId) ?? Promise.resolve();
    const run = previous.then(task);
    const tail = run.then(() => undefined, () => undefined);
    this.tails.set(sessionId, tail);
    void tail.then(() => {
      if (this.tails.get(sessionId) === tail) this.tails.delete(sessionId);
    });
    return run;
  }

  /**
   * The paths in the session's file; `fresh` when there is no usable file
   * (missing, or its header is not this session's), `torn` when its last
   * line has no end.
   */
  private async load(sessionId: string): Promise<{ paths: Set<string>; fresh: boolean; torn: boolean }> {
    await this.options.ready();
    const paths = new Set<string>();
    let text: string;
    try {
      text = await readFile(this.file(sessionId), "utf8");
    } catch {
      return { paths, fresh: true, torn: false };
    }
    const lines = text.split("\n");
    if (lines[0] !== this.header(sessionId)) return { paths, fresh: true, torn: false };
    for (const line of lines.slice(1)) {
      if (!line) continue;
      try {
        const path: unknown = JSON.parse(line);
        if (typeof path === "string" && touchedPathParts(path) !== null) paths.add(path);
        // An outside path is an object line (releases without outside capture skip it).
        else if (typeof path === "object" && path !== null && "outside" in path && typeof path.outside === "string" && isOutsideTouchedPath(path.outside)) paths.add(path.outside);
      } catch {
        // A line torn by a crash.
      }
    }
    return { paths, fresh: false, torn: !text.endsWith("\n") };
  }

  private header(sessionId: string): string {
    return JSON.stringify({ v: 1, session_id: sessionId });
  }

  /** Appends the pending paths of a tracked session to its file (under serial()); a file that is not usable is started again. */
  private async write(sessionId: string): Promise<void> {
    const epoch = this.epoch;
    const session = this.sessions.get(sessionId);
    if (!session || session.mode !== "tracked") return;
    let header = "";
    if (!session.known) {
      const loaded = await this.load(sessionId);
      if (epoch !== this.epoch || session.mode !== "tracked") return;
      session.known = loaded.paths;
      for (const path of loaded.paths) session.pending.delete(path);
      if (loaded.fresh) header = `${this.header(sessionId)}\n`;
      session.torn = loaded.torn;
    }
    const known = session.known;
    if (session.pending.size === 0) {
      // Nothing to write to a file that has no header yet: it is loaded (and started) again by the next write,
      // else that write would append to a file without its header, unreadable after a restart.
      if (header) session.known = null;
      return;
    }
    const batch = [...session.pending];
    session.pending = new Set();
    session.writing = batch;
    try {
      const lines = `${batch.map((path) => JSON.stringify(isOutsideTouchedPath(path) ? { outside: path } : path)).join("\n")}\n`;
      if (header) await writeFile(this.file(sessionId), `${header}${lines}`, { mode: 0o600 });
      else await appendFile(this.file(sessionId), `${session.torn ? "\n" : ""}${lines}`, { mode: 0o600 });
      session.torn = false;
      for (const path of batch) known.add(path);
    } catch (error) {
      for (const path of batch) if (!known.has(path)) session.pending.add(path);
      // Written from the start next time.
      if (header) session.known = null;
      throw error;
    } finally {
      session.writing = [];
    }
  }
}