agenticreplay 0.1.0 → 0.1.2

package/packages/core/src/graph.ts

@@ -1,450 +0,0 @@
-import type { TraceEvent } from '@agenticreplay/schema';
-
-/** A forkable point in a run. Derived from the log, never recorded (spec §3). */
-export interface Checkpoint {
-  seq: number;
-  turn: number;
-  /** Tree id from the governing `fs.snapshot`, when it recorded one. */
-  fsTree?: string;
-}
-
-export interface Turn {
-  turn: number;
-  startSeq: number;
-  endSeq: number;
-  events: TraceEvent[];
-}
-
-export interface SnapResult {
-  checkpoint: Checkpoint;
-  /** True when the target was not itself a checkpoint and had to move back. */
-  snapped: boolean;
-}
-
-function bySeq(events: TraceEvent[]): TraceEvent[] {
-  return [...events].sort((a, b) => a.seq - b.seq);
-}
-
-/**
- * The seq of the first `model.request` with no reply, or Infinity when the conversation is whole.
- *
- * Requests and responses are paired in order, so a second request that is still in flight is not
- * excused by the first one's reply. Everything after an unanswered request is un-forkable: the
- * model's effect on the run is unknown there.
- */
-function firstUnansweredRequest(events: TraceEvent[]): number {
-  const requests = events.filter((e) => e.type === 'model.request');
-  const responses = events.filter((e) => e.type === 'model.response');
-  for (let i = 0; i < requests.length; i++) {
-    const request = requests[i];
-    const response = responses[i];
-    if (!request) continue;
-    if (!response || response.seq <= request.seq) return request.seq;
-  }
-  return Number.POSITIVE_INFINITY;
-}
-
-/**
- * Every seq that satisfies both checkpoint conditions of spec §3: an `fs.snapshot` at or before it
- * in the same turn, and a complete conversation prefix.
- */
-export function deriveCheckpoints(events: TraceEvent[]): Checkpoint[] {
-  const ordered = bySeq(events);
-  const cutoff = firstUnansweredRequest(ordered);
-  const checkpoints: Checkpoint[] = [];
-  let snapshot: { turn: number; tree: string | undefined } | undefined;
-
-  for (const e of ordered) {
-    if (e.seq > cutoff) break;
-    if (e.type === 'fs.snapshot') {
-      const tree = e.attrs?.['tree'];
-      snapshot = { turn: e.turn, tree: typeof tree === 'string' ? tree : undefined };
-    }
-    // A snapshot only vouches for the state of its own turn; work in a later turn has moved on.
-    if (!snapshot || snapshot.turn !== e.turn) continue;
-    const checkpoint: Checkpoint = { seq: e.seq, turn: e.turn };
-    if (snapshot.tree !== undefined) checkpoint.fsTree = snapshot.tree;
-    checkpoints.push(checkpoint);
-  }
-  return checkpoints;
-}
-
-/**
- * The checkpoint a fork of `target` must actually start from — the nearest preceding one.
- *
- * Never rounds forward. Forking from state the run had not reached yet would produce a child run
- * that silently disagrees with its parent, which is worse than refusing outright.
- */
-export function snapToCheckpoint(cps: Checkpoint[], target: number): SnapResult {
-  const ordered = [...cps].sort((a, b) => a.seq - b.seq);
-  if (ordered.length === 0) {
-    throw new Error(
-      `cannot fork at seq ${target}: this run has no checkpoints — it recorded no fs.snapshot`,
-    );
-  }
-  let found: Checkpoint | undefined;
-  for (const cp of ordered) {
-    if (cp.seq > target) break;
-    found = cp;
-  }
-  if (!found) {
-    throw new Error(
-      `no checkpoint at or before ${target}: the earliest forkable seq is ${ordered[0]?.seq}`,
-    );
-  }
-  return { checkpoint: found, snapped: found.seq !== target };
-}
-
-/** The events of a run grouped into model turns, in turn order. */
-export function turnsOf(events: TraceEvent[]): Turn[] {
-  const byTurn = new Map<number, TraceEvent[]>();
-  for (const e of bySeq(events)) {
-    const bucket = byTurn.get(e.turn);
-    if (bucket) bucket.push(e);
-    else byTurn.set(e.turn, [e]);
-  }
-  return [...byTurn.entries()]
-    .sort((a, b) => a[0] - b[0])
-    .map(([turn, group]) => ({
-      turn,
-      startSeq: group[0]?.seq ?? 0,
-      endSeq: group[group.length - 1]?.seq ?? 0,
-      events: group,
-    }));
-}
-
-/** The event at `seq` and everything transitively named by `causes`, oldest first. */
-export function causalChain(events: TraceEvent[], seq: number): TraceEvent[] {
-  const index = new Map(events.map((e) => [e.seq, e]));
-  const start = index.get(seq);
-  if (!start) throw new Error(`no event with seq ${seq} in this trace`);
-
-  const seen = new Set<number>([seq]);
-  const queue = [start];
-  const chain: TraceEvent[] = [];
-  while (queue.length > 0) {
-    const event = queue.shift();
-    if (!event) break;
-    chain.push(event);
-    for (const cause of event.causes ?? []) {
-      // A cycle is malformed, and an ancestor may be missing because the reader skipped an
-      // unknown event type. Neither may stop the walk.
-      if (seen.has(cause)) continue;
-      seen.add(cause);
-      const parent = index.get(cause);
-      if (parent) queue.push(parent);
-    }
-  }
-  return chain.sort((a, b) => a.seq - b.seq);
-}
-
-/** Where an edge came from. The distinction is the whole honesty mechanism — see `runGraph`. */
-export type EdgeKind = 'recorded' | 'inferred';
-
-export interface GraphNode {
-  seq: number;
-  turn: number;
-  type: TraceEvent['type'];
-  attrs?: Record<string, unknown>;
-}
-
-export interface GraphEdge {
-  /** The cause. Always less than `to`, as spec §2.1 requires of `causes`. */
-  from: number;
-  to: number;
-  kind: EdgeKind;
-  /** Why this edge exists. For an inferred edge, the rule that produced it. */
-  rule: string;
-}
-
-export interface RunGraph {
-  nodes: GraphNode[];
-  edges: GraphEdge[];
-}
-
-/**
- * What a recorded pair means, when the pair is one agenticreplay itself writes.
- *
- * `causes` says *that* one event caused another and never *why*, so this is a post-hoc reading of
- * the type pair rather than anything the trace claims. An unrecognised pair says `causes` and
- * stops there, which is the honest answer for an edge written by a reader we do not know.
- */
-const RECORDED_RULES: Record<string, string> = {
-  'tool.call→tool.result': 'tool result answers its call',
-  'shell.exec→shell.result': 'shell result answers its exec',
-  'net.request→net.response': 'network response answers its request',
-  'model.request→model.response': 'the model answered this request',
-  'model.response→tool.call': 'tool_use block in the response',
-  'tool.result→model.request': 'tool_result block in the request',
-};
-
-const ARGV_RULE = 'argv matches tool input, same or previous turn';
-const PATH_RULE = 'changed path appears in tool input, same or previous turn';
-
-/**
- * How many turns back an effect may reach for the call that caused it.
- *
- * One, not zero. A snapshot is taken when the turn's exchange is persisted, which races the agent
- * actually running the tool — an end-to-end recording produced the edit in the turn's own snapshot
- * on one run and in the next turn's on another. A same-turn rule therefore made the graph differ
- * between two identical runs. Not more than one either: an effect two turns later would have been
- * reported by the snapshot in between.
- */
-const TURN_REACH = 1;
-
-/** The longest string in an argv array — in practice the command, not the shell that ran it. */
-function commandOf(argv: unknown): string {
-  if (!Array.isArray(argv)) return '';
-  let longest = '';
-  for (const part of argv) {
-    if (typeof part === 'string' && part.length > longest.length) longest = part;
-  }
-  return longest;
-}
-
-function inputText(call: TraceEvent): string {
-  const input = (call.attrs ?? {})['input'];
-  if (input === undefined) return '';
-  try {
-    return typeof input === 'string' ? input : (JSON.stringify(input) ?? '');
-  } catch {
-    return '';
-  }
-}
-
-/**
- * The one tool call that can be said to have caused `effect`, or undefined when that is not
- * exactly one call.
- *
- * Candidates are calls whose input names `needle`, that happened first, and that are within
- * `TURN_REACH` turns. Of those, only the nearest turn is considered: a later call supersedes an
- * earlier one, since a file edited twice was last edited by the most recent call to name it.
- *
- * Two calls in that nearest turn is the case worth dwelling on. Picking either would produce an
- * edge indistinguishable from a true one and wrong half the time, and a wrong edge is worse than
- * a missing one because the missing one is visible. So ambiguity yields nothing.
- */
-function soleMatchingCall(
-  calls: TraceEvent[],
-  effect: TraceEvent,
-  needle: string,
-): TraceEvent | undefined {
-  if (needle === '') return undefined;
-  const candidates = calls.filter(
-    (call) =>
-      call.seq < effect.seq &&
-      effect.turn - call.turn >= 0 &&
-      effect.turn - call.turn <= TURN_REACH &&
-      inputText(call).includes(needle),
-  );
-  if (candidates.length === 0) return undefined;
-  const nearest = Math.max(...candidates.map((c) => c.turn));
-  const inNearest = candidates.filter((c) => c.turn === nearest);
-  return inNearest.length === 1 ? inNearest[0] : undefined;
-}
-
-/**
- * The longest string a graph node carries. A graph is about structure, not payloads.
- *
- * `agenticreplay_graph` answers an agent, and the answer lands in its context — so a `tool.call` whose
- * `input` holds a whole file body would spend that context on something the graph never uses. The
- * shape survives so a label can still read `input.path`; the bulk does not. `agenticreplay events` is one
- * command away when the full value is what you want.
- */
-const ATTR_MAX = 200;
-
-function clampValue(value: unknown, depth = 0): unknown {
-  if (typeof value === 'string') {
-    return value.length <= ATTR_MAX ? value : `${value.slice(0, ATTR_MAX)}…`;
-  }
-  if (depth >= 4 || value === null || typeof value !== 'object') return value;
-  if (Array.isArray(value)) return value.slice(0, 20).map((v) => clampValue(v, depth + 1));
-  const out: Record<string, unknown> = {};
-  for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
-    out[key] = clampValue(v, depth + 1);
-  }
-  return out;
-}
-
-function clampAttrs(attrs: Record<string, unknown>): Record<string, unknown> {
-  return clampValue(attrs) as Record<string, unknown>;
-}
-
-/**
- * A run as nodes and edges, with every edge saying whether the trace vouches for it.
- *
- * Two kinds, and they are not interchangeable. A `recorded` edge came out of `causes`, which the
- * recorder wrote because it watched the relationship happen. An `inferred` edge was derived here,
- * just now, by the named rule — a filesystem snapshot is taken once per turn rather than once per
- * tool call, and shell frames are bucketed into turns by wall clock, so attributing an effect to a
- * *particular* call is a guess however good the heuristic is.
- *
- * Inferred edges are therefore never written back to the trace. That is the same discipline spec
- * §3 applies to checkpoints, which are derived and never recorded, and it exists so that a field
- * a third-party reader trusts never contains something agenticreplay made up.
- */
-export function runGraph(events: TraceEvent[]): RunGraph {
-  const ordered = bySeq(events);
-  const present = new Set(ordered.map((e) => e.seq));
-  const nodes: GraphNode[] = ordered.map((e) => ({
-    seq: e.seq,
-    turn: e.turn,
-    type: e.type,
-    ...(e.attrs === undefined ? {} : { attrs: clampAttrs(e.attrs) }),
-  }));
-
-  const byType = new Map(ordered.map((e) => [e.seq, e.type]));
-  const edges: GraphEdge[] = [];
-
-  for (const event of ordered) {
-    for (const cause of event.causes ?? []) {
-      // A reader may have dropped an event type it did not know (spec §2.3), so an edge can name
-      // an ancestor that is not here. Naming a node that does not exist is worse than no edge.
-      if (!present.has(cause)) continue;
-      const pair = `${byType.get(cause)}→${event.type}`;
-      edges.push({
-        from: cause,
-        to: event.seq,
-        kind: 'recorded',
-        rule: RECORDED_RULES[pair] ?? 'causes',
-      });
-    }
-  }
-
-  const calls = ordered.filter((e) => e.type === 'tool.call');
-  if (calls.length > 0) {
-    for (const event of ordered) {
-      const attrs = event.attrs ?? {};
-      let match: TraceEvent | undefined;
-      let rule = '';
-      if (event.type === 'shell.exec') {
-        match = soleMatchingCall(calls, event, commandOf(attrs['argv']));
-        rule = ARGV_RULE;
-      } else if (event.type === 'fs.change') {
-        const path = attrs['path'];
-        match = soleMatchingCall(calls, event, typeof path === 'string' ? path : '');
-        rule = PATH_RULE;
-      }
-      if (match) edges.push({ from: match.seq, to: event.seq, kind: 'inferred', rule });
-    }
-  }
-
-  edges.sort((a, b) => a.to - b.to || a.from - b.from);
-  return { nodes, edges };
-}
-
-/**
- * The sub-graph that produced `seq`: that event and everything transitively behind it.
- *
- * `causalChain` walks `causes` alone and so stops at the first inferred hop, which in a real run
- * is the hop from a tool call to the shell command it ran — exactly the one a person following a
- * failure backwards needs. This walks the derived graph instead, so it crosses both kinds.
- */
-export function chainTo(graph: RunGraph, seq: number): RunGraph {
-  if (!graph.nodes.some((n) => n.seq === seq)) {
-    throw new Error(`no event with seq ${seq} in this graph`);
-  }
-  const incoming = new Map<number, GraphEdge[]>();
-  for (const edge of graph.edges) {
-    const bucket = incoming.get(edge.to);
-    if (bucket) bucket.push(edge);
-    else incoming.set(edge.to, [edge]);
-  }
-
-  const kept = new Set<number>([seq]);
-  const edges: GraphEdge[] = [];
-  const queue = [seq];
-  while (queue.length > 0) {
-    const at = queue.shift();
-    if (at === undefined) break;
-    for (const edge of incoming.get(at) ?? []) {
-      edges.push(edge);
-      // A cycle is malformed rather than impossible, and it must not hang the walk.
-      if (kept.has(edge.from)) continue;
-      kept.add(edge.from);
-      queue.push(edge.from);
-    }
-  }
-
-  return {
-    nodes: graph.nodes.filter((n) => kept.has(n.seq)),
-    edges: edges.sort((a, b) => a.to - b.to || a.from - b.from),
-  };
-}
-
-/**
- * The event a card about this run should be about, or undefined when nothing stands out.
- *
- * Which chain to draw *is* the feature. A card gets screenshotted whether or not it happens to be
- * the interesting one, so an arbitrary pick travels further than no card at all — hence a run with
- * nothing notable returns undefined and the caller refuses rather than drawing something.
- *
- * The order is failure first, then the largest visible effect: a command that exited non-zero, a
- * tool that reported an error, an error agenticreplay itself recorded, a replay divergence, and only then
- * the last file the run changed. Within a kind the last one wins, since that is where the run
- * ended up.
- */
-export function pickChainTarget(events: TraceEvent[]): number | undefined {
-  const ordered = bySeq(events);
-  const last = (match: (e: TraceEvent) => boolean): number | undefined => {
-    for (let i = ordered.length - 1; i >= 0; i--) {
-      const event = ordered[i];
-      if (event && match(event)) return event.seq;
-    }
-    return undefined;
-  };
-
-  return (
-    last((e) => e.type === 'shell.result' && (e.attrs?.['exit_code'] ?? 0) !== 0) ??
-    last((e) => e.type === 'tool.result' && e.attrs?.['is_error'] === true) ??
-    last((e) => e.type === 'error') ??
-    last((e) => e.type === 'divergence') ??
-    last((e) => e.type === 'fs.change')
-  );
-}
-
-/** Attributes as a plain record, since the envelope leaves them optional. */
-function toAttrs(event: TraceEvent): Record<string, unknown> {
-  return event.attrs ?? {};
-}
-
-/** Tool calls that hand work to another agent, by the argument every harness gives them. */
-export function isDelegation(event: TraceEvent): boolean {
-  if (event.type !== 'tool.call') return false;
-  const input = toAttrs(event)['input'];
-  if (input === null || typeof input !== 'object') return false;
-  const shape = input as Record<string, unknown>;
-  return typeof shape['subagent_type'] === 'string' || typeof shape['agent'] === 'string';
-}
-
-/**
- * The delegation whose span encloses `seq`, if any.
- *
- * A replay that halts inside one is the hardest kind of miss to read: the distance is small, the
- * trace is intact, and nothing on the line says why the same run asked a different question. The
- * answer is that the harness wrote the delegate's prompt itself and writes a fresh one every time,
- * so that request genuinely was not the recorded one. Naming the delegation turns a number into
- * that sentence.
- */
-export function enclosingDelegation(
-  events: TraceEvent[],
-  seq: number,
-): { seq: number; subagent: string } | undefined {
-  const closesAt = new Map<number, number>();
-  for (const event of events) {
-    if (event.type !== 'tool.result') continue;
-    for (const cause of event.causes ?? []) closesAt.set(cause, event.seq);
-  }
-  let found: { seq: number; subagent: string } | undefined;
-  for (const event of events) {
-    if (event.seq > seq) break;
-    if (!isDelegation(event)) continue;
-    const closes = closesAt.get(event.seq);
-    // Still open at `seq`: an unclosed delegation ran to the end of the trace.
-    if (closes !== undefined && closes < seq) continue;
-    const input = toAttrs(event)['input'] as Record<string, unknown> | undefined;
-    const subagent = String(input?.['subagent_type'] ?? input?.['agent'] ?? 'sub-agent');
-    found = { seq: event.seq, subagent };
-  }
-  return found;
-}

package/packages/core/src/index.ts

@@ -1,8 +0,0 @@
-export * from './blobs.js';
-export * from './fetch.js';
-export * from './graph.js';
-export * from './paths.js';
-export * from './private-files.js';
-export * from './reader.js';
-export * from './redaction.js';
-export * from './writer.js';

package/packages/core/src/paths.ts

@@ -1,180 +0,0 @@
-import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { RUN_ID_PATTERN } from '@agenticreplay/schema';
-import {
-  assertPrivatePathIdentity,
-  privatePathIdentity,
-  restrictToOwner,
-} from './private-files.js';
-
-export interface RunRef {
-  runId: string;
-  /** RFC3339, from the manifest when it is readable, else the directory's mtime. */
-  createdAt: string;
-  dir: string;
-  /** Set when this run was forked from another (spec §1). Absent on a plain recording. */
-  parentRun?: string;
-  forkPoint?: number;
-}
-
-export function agenticreplayDir(cwd: string): string {
-  return join(cwd, '.agenticreplay');
-}
-
-export function runsDir(cwd: string): string {
-  return join(agenticreplayDir(cwd), 'runs');
-}
-
-/**
- * Create `.agenticreplay/runs`, and make the store ignore itself.
- *
- * A recording is the conversation the model saw — which is your source — plus shell output, a
- * snapshot of the whole workspace, and an environment allowlist. SECURITY.md says to treat one as
- * roughly as sensitive as a shell history plus a heap dump. It was also landing in `git status` as
- * an untracked directory, one `git add -A` away from being committed and pushed, in the working
- * tree of the project it just recorded.
- *
- * `.agenticreplay/.gitignore` containing `*` is git's own idiom for a directory that excludes itself: no
- * edit to the user's `.gitignore`, nothing to remember, and it works in a repo agenticreplay has never seen
- * before. Written once at creation and never rewritten, so anyone who deliberately wants their
- * traces tracked can delete it and agenticreplay will not put it back.
- */
-export async function ensureRunsDir(cwd: string): Promise<string> {
-  const dir = runsDir(cwd);
-  const agenticreplay = agenticreplayDir(cwd);
-
-  if (process.platform === 'win32') {
-    // Secure the container before creating the store inside it. Ownership is checked as well:
-    // removing a foreign owner's ACE alone would leave it able to restore its own access.
-    await mkdir(agenticreplay, { recursive: true, mode: 0o700 });
-    const agenticreplayWas = await privatePathIdentity(agenticreplay);
-    await restrictToOwner(agenticreplay, 0o700);
-    await assertPrivatePathIdentity(agenticreplay, agenticreplayWas);
-
-    await mkdir(dir, { recursive: true, mode: 0o700 });
-    // Check again after making the container non-empty. These checks detect replacement during
-    // setup; they do not lock ancestors against an account that can keep replacing them later.
-    await assertPrivatePathIdentity(agenticreplay, agenticreplayWas);
-    const dirWas = await privatePathIdentity(dir);
-    await restrictToOwner(dir, 0o700);
-    await assertPrivatePathIdentity(dir, dirWas);
-  } else {
-    // POSIX, unchanged: only when this call created it, which is what passing `mode` to mkdir
-    // already meant. Every file beneath gets its own 0600 from the writer regardless, so the
-    // directory's mode is not load-bearing, and one the user has deliberately opened up is theirs
-    // to have opened up. `chmod` follows a symlink here, and pointing a store at another disk is
-    // an ordinary thing to do, so there is no link check either.
-    const created = (await mkdir(dir, { recursive: true, mode: 0o700 })) !== undefined;
-    // Swallowed, the way `sync.ts` swallows the same call three times over. `mkdir`'s mode is a
-    // request a filesystem without permissions ignores; `chmod` on that same filesystem fails. And
-    // `ensureRunsDir` is the first thing `record`, `attach`, `replay`, `pull` and `quickstart` all
-    // do, so making it fatal would abort every one of them on an exFAT or vfat workspace that
-    // worked before. What it buys is narrow enough to be worth losing there: umask can only clear
-    // bits, so `mkdir(0o700)` is already at most 0700 and this only restores what an exotic one
-    // took away. On Windows, where the mode is discarded and the ACL is the whole protection, the
-    // branch above stays fatal.
-    if (created) await restrictToOwner(dir, 0o700).catch(() => undefined);
-  }
-
-  const ignore = join(agenticreplay, '.gitignore');
-  if (!(await stat(ignore).catch(() => null))) {
-    await writeFile(
-      ignore,
-      '# Recordings hold source, shell output and workspace snapshots. Not for committing.\n*\n',
-      { mode: 0o600, flag: 'wx' },
-    ).catch(() => undefined);
-  }
-  return dir;
-}
-
-/** Run ids reach us from argv, so the pattern check is also the path-traversal guard. */
-export function runDirFor(cwd: string, runId: string): string {
-  if (!RUN_ID_PATTERN.test(runId)) throw new Error(`not a valid run id: ${JSON.stringify(runId)}`);
-  return join(runsDir(cwd), runId);
-}
-
-/**
- * The manifest facts a listing needs, read in one pass.
- *
- * Everything here degrades rather than throws: a run whose manifest is missing or truncated is
- * still worth listing — that is exactly the crashed run someone is looking for.
- */
-async function factsOf(dir: string): Promise<Omit<RunRef, 'runId' | 'dir'>> {
-  try {
-    const raw = JSON.parse(await readFile(join(dir, 'manifest.json'), 'utf8')) as {
-      created_at?: unknown;
-      parent_run?: unknown;
-      fork_point?: unknown;
-    };
-    const at = raw.created_at;
-    if (typeof at === 'string' && !Number.isNaN(Date.parse(at))) {
-      return {
-        createdAt: at,
-        ...(typeof raw.parent_run === 'string' ? { parentRun: raw.parent_run } : {}),
-        ...(typeof raw.fork_point === 'number' ? { forkPoint: raw.fork_point } : {}),
-      };
-    }
-  } catch {
-    // Fall through to the directory's mtime.
-  }
-  return { createdAt: new Date((await stat(dir)).mtimeMs).toISOString() };
-}
-
-/** Every recorded run in the workspace, newest first. */
-export async function listRuns(cwd: string): Promise<RunRef[]> {
-  const root = runsDir(cwd);
-  const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
-  const runs: RunRef[] = [];
-  for (const e of entries) {
-    if (!e.isDirectory() || !RUN_ID_PATTERN.test(e.name)) continue;
-    const dir = join(root, e.name);
-    runs.push({ runId: e.name, dir, ...(await factsOf(dir)) });
-  }
-  return runs.sort((a, b) =>
-    a.createdAt === b.createdAt
-      ? b.runId.localeCompare(a.runId)
-      : b.createdAt.localeCompare(a.createdAt),
-  );
-}
-
-/**
- * A run that describes another run rather than being one: an exact replay's own trace.
- *
- * It holds divergences and nothing else — no exchanges, no blobs, no filesystem store. A fork is
- * not one of these: it has a `fork_point`, real exchanges and a worktree, and is a thing you act
- * on.
- */
-function isReplayTrace(run: RunRef): boolean {
-  return run.parentRun !== undefined && run.forkPoint === undefined;
-}
-
-/**
- * Resolves the CLI's run argument: `last` for the newest run, anything else as a run id.
- *
- * `last` skips replay traces. Since exact replay started writing one, the newest run in a
- * directory is usually a report about the run before it, and every command defaults to `last` — so
- * that quietly redirected all of them. The sharpest case is the line in the README:
- * `agenticreplay scrub last --match my-hostname` scrubbed the empty trace, found nothing, and said "nothing
- * matched — the trace is unchanged", while the secret sat in the recording beside it. A security
- * tool reporting clean because it searched the wrong thing is worse than one that fails.
- *
- * Naming a replay trace explicitly still resolves it, and when a directory holds nothing else it
- * is still returned — a selector that refuses to resolve is not an improvement.
- */
-export async function resolveRunSelector(cwd: string, selector: string): Promise<RunRef> {
-  if (selector === 'last') {
-    const runs = await listRuns(cwd);
-    const newest = runs.find((r) => !isReplayTrace(r)) ?? runs[0];
-    if (!newest) {
-      throw new Error(
-        `no runs recorded in ${runsDir(cwd)} — record one first: agenticreplay record -- <your agent>`,
-      );
-    }
-    return newest;
-  }
-  const dir = runDirFor(cwd, selector);
-  const found = (await listRuns(cwd)).find((r) => r.dir === dir);
-  if (!found)
-    throw new Error(`no run ${selector} in ${runsDir(cwd)} — list runs with: agenticreplay list`);
-  return found;
-}