@vzn/vx 0.0.16 → 0.0.21

package/src/cache/tar.ts

@@ -1,343 +0,0 @@
-// In-process tar reader (POSIX ustar) for cache-hit restore.
-//
-// We replace `Bun.spawn(['tar', '-xf', ...])` on the cache-hit path
-// to save a per-restore fork+exec (~5-10ms on Linux). At 200 cached
-// tasks per run, that's 1-2s of pure overhead reclaimed.
-//
-// Tar layout we accept (produced by GNU/BSD `tar -cf - -C stage X Y Z`):
-//   - 512-byte POSIX ustar headers
-//   - name        : bytes 0..99    (null-padded)
-//   - mode        : bytes 100..107 (octal ASCII, null-padded)
-//   - mtime       : bytes 136..147 (octal ASCII seconds since epoch)
-//   - size        : bytes 124..135 (octal ASCII)
-//   - typeflag    : byte 156       ('0' or '\0' = file, '5' = dir,
-//                                   '2' = symlink, 'L' = GNU longname,
-//                                   'x' / 'g' / 'X' = PAX extended
-//                                   header — metadata for the next
-//                                   entry, not a file itself)
-//   - data        : `size` bytes, padded up to next 512-byte block
-//   - end         : two 512-byte zero blocks
-//
-// We tolerate the GNU longname extension (typeflag 'L') because some
-// tar binaries emit it for paths > 100 chars even when ustar's
-// prefix+name (256 chars) would suffice. PAX extended-header records
-// ('x' / 'g' / 'X') are SKIPPED — BSD tar (macOS default) emits one
-// per entry for xattrs / mtime-nanos / SCHILY metadata. We don't
-// need any of that; treating the headers as regular files would put
-// `PaxHeaders/foo` junk entries into the restored tree.
-//
-// AppleDouble files (`._<name>`) are also SKIPPED — macOS Finder /
-// `cp -p` leave these resource-fork siblings around (e.g. `._main.js`
-// next to `main.js`). They're not real outputs; filtering at parse
-// time prevents them from showing up in restored trees even when an
-// older / contaminated cache entry includes them. The matching
-// input-side filter lives in `src/cache/inputs.ts:ALWAYS_IGNORE`.
-//
-// We DO NOT support sparse files, character/block devices, or
-// hardlinks — they don't appear in build outputs.
-
-import { lstat, mkdir, chmod, realpath, unlink, utimes } from 'node:fs/promises'
-import path from 'node:path'
-
-export interface TarHeader {
-  /** Full archive-relative name, e.g. "outputs/dist/index.js" or "manifest.json". */
-  name: string
-  size: number
-  /** File permission bits, e.g. 0o644. */
-  mode: number
-  /** Modification time in ms since epoch (seconds-resolution from tar). */
-  mtimeMs: number
-  isDir: boolean
-  /** Offset in `tarBytes` where the file's data starts. */
-  dataOffset: number
-}
-
-/**
- * Walk a tar archive's headers and return them in source order.
- * Cheap: only reads 512-byte blocks; never decodes file bodies.
- */
-export function parseTarHeaders(tarBytes: Uint8Array): TarHeader[] {
-  const headers: TarHeader[] = []
-  const dec = new TextDecoder('utf-8')
-  let off = 0
-  let pendingLongName: string | null = null
-
-  while (off + 512 <= tarBytes.length) {
-    const header = tarBytes.subarray(off, off + 512)
-    // End-of-archive marker: 512 zero bytes (tar pads two such blocks).
-    let zero = true
-    for (let i = 0; i < 512 && zero; i++) {
-      if (header[i] !== 0) zero = false
-    }
-    if (zero) break
-
-    let nameEnd = 0
-    while (nameEnd < 100 && header[nameEnd] !== 0) nameEnd++
-    const rawName = dec.decode(header.subarray(0, nameEnd)).replace(/^\.\//, '')
-
-    const modeStr = dec.decode(header.subarray(100, 108)).trim().replace(/ +$/, '')
-    const mode = parseInt(modeStr, 8) || 0o644
-
-    const sizeStr = dec.decode(header.subarray(124, 136)).trim().replace(/ +$/, '')
-    const size = parseInt(sizeStr, 8) || 0
-
-    const mtimeStr = dec.decode(header.subarray(136, 148)).trim().replace(/ +$/, '')
-    const mtimeMs = (parseInt(mtimeStr, 8) || 0) * 1000
-
-    const typeFlag = header[156]
-    const isDir = typeFlag === 0x35 /* '5' */ || rawName.endsWith('/')
-
-    const dataStart = off + 512
-    const padded = Math.ceil(size / 512) * 512
-
-    if (typeFlag === 0x4c /* 'L' — GNU longname */) {
-      // The data block carries the next entry's full name (null-
-      // terminated). Stash it; the actual file header follows.
-      // Strip the null terminator(s) without writing a regex that lint
-      // flags as a control-char match.
-      const raw = dec.decode(tarBytes.subarray(dataStart, dataStart + size))
-      let endIdx = raw.length
-      while (endIdx > 0 && raw.charCodeAt(endIdx - 1) === 0) endIdx--
-      pendingLongName = raw.slice(0, endIdx)
-      off = dataStart + padded
-      continue
-    }
-
-    // PAX extended headers: metadata about the next entry (long
-    // names, large sizes, nanosecond mtime, BSD xattrs, etc). Their
-    // own entry name is something like `PaxHeaders/<basename>` or
-    // `./PaxHeader.NNNN/<basename>` — definitely not a file we want
-    // to write to disk. Skip the whole record (header + padded data)
-    // and let the next entry through unchanged.
-    if (
-      typeFlag === 0x78 /* 'x' — per-entry PAX */ ||
-      typeFlag === 0x67 /* 'g' — global PAX */ ||
-      typeFlag === 0x58 /* 'X' — Solaris extended */
-    ) {
-      off = dataStart + padded
-      continue
-    }
-
-    // Reject typeflags we don't support: hardlink (1), symlink (2),
-    // char device (3), block device (4), FIFO (6), contiguous (7).
-    // Build outputs are regular files + directories; anything else
-    // is either a producer bug or a smuggled non-file artifact (a
-    // symlink to /etc/passwd, a /dev/null mapping, etc.). Reject
-    // explicitly so future extractors can't be tricked into honoring
-    // these by accident.
-    if (typeFlag === 0x31 /* '1' */) {
-      throw new TarSecurityError(`tar entry typeflag 'hardlink' is unsupported: ${rawName}`)
-    }
-    if (typeFlag === 0x32 /* '2' */) {
-      throw new TarSecurityError(`tar entry typeflag 'symlink' is unsupported: ${rawName}`)
-    }
-    if (typeFlag === 0x33 /* '3' */) {
-      throw new TarSecurityError(`tar entry typeflag 'chardev' is unsupported: ${rawName}`)
-    }
-    if (typeFlag === 0x34 /* '4' */) {
-      throw new TarSecurityError(`tar entry typeflag 'blockdev' is unsupported: ${rawName}`)
-    }
-    if (typeFlag === 0x36 /* '6' */) {
-      throw new TarSecurityError(`tar entry typeflag 'fifo' is unsupported: ${rawName}`)
-    }
-    if (typeFlag === 0x37 /* '7' */) {
-      throw new TarSecurityError(`tar entry typeflag 'contiguous' is unsupported: ${rawName}`)
-    }
-
-    const name = pendingLongName ?? rawName
-    pendingLongName = null
-
-    if (name.length === 0) {
-      off = dataStart + padded
-      continue
-    }
-
-    // Path-traversal defense. We only ever want to extract entries
-    // under `outputs/<rel>` where `<rel>` is project-relative and
-    // contains no `..` segments and no absolute prefix. Reject at
-    // parse time so a malicious cache artifact can't write outside
-    // the destination (zip-slip class). Mirrors Turbo's
-    // restore.rs:check_path normalization.
-    if (name.startsWith('/')) {
-      throw new TarSecurityError(`tar entry name is absolute (unsafe): ${name}`)
-    }
-    if (hasParentSegment(name)) {
-      throw new TarSecurityError(`tar entry name escapes via '..' (unsafe): ${name}`)
-    }
-    if (name.includes('//')) {
-      throw new TarSecurityError(`tar entry name has empty path component (unsafe): ${name}`)
-    }
-    // Windows-shaped paths are categorically unsafe to extract on
-    // POSIX hosts (and vice versa): backslash separators, drive
-    // letters, extended-length prefixes. Reject before we touch
-    // anything.
-    if (name.includes('\\')) {
-      throw new TarSecurityError(`tar entry uses backslash separators (windows-unsafe): ${name}`)
-    }
-    if (/^[A-Za-z]:[\\/]/.test(name)) {
-      throw new TarSecurityError(`tar entry has windows drive prefix (unsafe): ${name}`)
-    }
-
-    // AppleDouble resource-fork siblings — basename starting with
-    // `._`. macOS Finder / `cp -p` leave these next to real files
-    // (e.g. `._main.js` shadowing `main.js`). They carry xattrs we
-    // don't care about; restoring them just pollutes the tree.
-    const basename = name.slice(name.lastIndexOf('/') + 1)
-    if (basename.startsWith('._')) {
-      off = dataStart + padded
-      continue
-    }
-
-    headers.push({ name, size, mode, mtimeMs, isDir, dataOffset: dataStart })
-    off = dataStart + padded
-  }
-  return headers
-}
-
-/**
- * Thrown by `parseTarHeaders` when an entry's name would let it
- * escape the extraction destination (absolute path, `..` traversal,
- * doubled separators). Callers should treat this as a corrupt /
- * malicious artifact — log it, drop the cache entry, and re-run.
- */
-export class TarSecurityError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'TarSecurityError'
-  }
-}
-
-function hasParentSegment(p: string): boolean {
-  if (p === '..' || p.startsWith('../') || p.endsWith('/..')) return true
-  return p.includes('/../')
-}
-
-/**
- * Read a single tar entry's text body. Returns '' for missing entries.
- * Used to extract `stdout` / `stderr` inline.
- */
-export function readTarText(tarBytes: Uint8Array, headers: TarHeader[], name: string): string {
-  const h = headers.find((e) => e.name === name)
-  if (!h) return ''
-  return new TextDecoder('utf-8').decode(tarBytes.subarray(h.dataOffset, h.dataOffset + h.size))
-}
-
-/**
- * Extract a tar's `outputs/<rel>` entries into `destDir/<rel>` (strips
- * the `outputs/` prefix), and — when `workspaceDest` is given — its
- * `workspace-outputs/<rel>` entries into `workspaceDest/<rel>`.
- * Entries in neither namespace are ignored; workspace entries are
- * also ignored when no `workspaceDest` is supplied.
- */
-export async function extractOutputs(
-  tarBytes: Uint8Array,
-  destDir: string,
-  workspaceDest?: string,
-): Promise<void> {
-  const headers = parseTarHeaders(tarBytes)
-
-  await mkdir(destDir, { recursive: true })
-
-  // Each namespace anchors at its own destination dir.
-  const destFor = (name: string): { base: string; rel: string } | null => {
-    if (name.startsWith('outputs/')) {
-      return { base: destDir, rel: name.slice('outputs/'.length) }
-    }
-    if (workspaceDest !== undefined && name.startsWith('workspace-outputs/')) {
-      return { base: workspaceDest, rel: name.slice('workspace-outputs/'.length) }
-    }
-    return null
-  }
-
-  // Two passes: directories first (depth-first via sort), then files.
-  // Keeps file writes from racing with their parent dir creation.
-  const dirEntries = headers
-    .filter((h) => h.isDir)
-    .map((h) => destFor(h.name))
-    .filter((d): d is { base: string; rel: string } => d !== null && d.rel.length > 0)
-    .sort((a, b) => (a.rel < b.rel ? -1 : 1))
-  for (const d of dirEntries) {
-    await mkdir(path.join(d.base, d.rel), { recursive: true })
-  }
-
-  const fileEntries = headers
-    .map((h) => ({ h, dest: destFor(h.name) }))
-    .filter(
-      (e): e is { h: TarHeader; dest: { base: string; rel: string } } =>
-        e.dest !== null && !e.h.isDir && e.dest.rel.length > 0,
-    )
-
-  // The REAL path of each base dir (symlinks resolved), memoized. Used to
-  // catch a symlinked ANCESTOR under the output tree: the lexical check
-  // below stops a `..` name, but if `<dest>/dist` is already an on-disk
-  // symlink pointing outside (planted in the repo or by a dependency
-  // postinstall), a lexically-contained entry `dist/x` would follow it and
-  // escape. Both sides are realpath'd, so a legitimate symlinked ANCESTOR of
-  // the base dir itself (e.g. macOS /tmp → /private/tmp) resolves
-  // consistently and is not flagged.
-  const realBaseCache = new Map<string, string>()
-  const realBaseOf = async (base: string): Promise<string> => {
-    const key = path.resolve(base)
-    let r = realBaseCache.get(key)
-    if (r === undefined) {
-      r = await realpath(key).catch(() => key)
-      realBaseCache.set(key, r)
-    }
-    return r
-  }
-
-  await Promise.all(
-    fileEntries.map(async ({ h, dest }) => {
-      const destResolved = path.resolve(dest.base)
-      const target = path.join(dest.base, dest.rel)
-      // Defense in depth — parseTarHeaders already rejects `..` /
-      // absolute paths, but if a future glitch lets one through we
-      // catch it here. path.resolve normalizes `..` components in
-      // the joined path so the comparison is sound.
-      const targetResolved = path.resolve(target)
-      if (targetResolved !== destResolved && !targetResolved.startsWith(destResolved + path.sep)) {
-        throw new TarSecurityError(`tar entry escapes destDir (unsafe): ${h.name}`)
-      }
-
-      // Ensure the parent dir exists. Cheap because mkdir(recursive)
-      // is a no-op when the dir is already there.
-      await mkdir(path.dirname(target), { recursive: true })
-
-      // Symlinked-parent escape check: the parent dir now exists — resolve
-      // its real path and require it to still sit inside the real base dir.
-      // A poisoned artifact whose entry lands under a pre-existing symlinked
-      // directory is refused before any bytes are written outside the tree.
-      const realBase = await realBaseOf(dest.base)
-      const realParent = await realpath(path.dirname(target)).catch(() => path.dirname(target))
-      if (realParent !== realBase && !realParent.startsWith(realBase + path.sep)) {
-        throw new TarSecurityError(`tar entry escapes destDir via a symlinked parent: ${h.name}`)
-      }
-
-      // Symlink TOCTOU defense: if the target IS a symlink, unlink
-      // it first so the upcoming write doesn't follow the link and
-      // clobber whatever the link points to (e.g. an attacker placed
-      // `<dest>/link -> /etc/passwd` to redirect our write). lstat
-      // doesn't follow the symlink, so we can detect the link itself.
-      try {
-        const ls = await lstat(target)
-        if (ls.isSymbolicLink()) await unlink(target)
-      } catch {
-        // Target doesn't exist — that's the common case; fall through.
-      }
-
-      const body = tarBytes.subarray(h.dataOffset, h.dataOffset + h.size)
-      // Bun.write benchmarks ~2× faster than fs/promises.writeFile
-      // for these per-entry restore writes (167µs vs 361µs per 1KB
-      // on the dev box; ~1.6× in batched Promise.all over 50 files).
-      // Native fast path; same correctness contract.
-      await Bun.write(target, body)
-      // Permission bits + mtime restoration — keeps a re-tar of the
-      // restored tree byte-identical to the original artifact.
-      if ((h.mode & 0o777) !== 0) await chmod(target, h.mode & 0o777)
-      if (h.mtimeMs > 0) {
-        const t = h.mtimeMs / 1000
-        await utimes(target, t, t)
-      }
-    }),
-  )
-}

package/src/cli/backend.ts

@@ -1,23 +0,0 @@
-// Execution as a pluggable backend — the same idea as the cache's
-// local/remote split, applied to running tasks. `vx run` resolves a
-// backend and calls `run(request)`; it neither knows nor cares whether the
-// work happened in-process or was delegated to a service. The DEFAULT is
-// pure in-process; routing to a service (local or hosted) is a `backend`
-// plugin capability, never core.
-
-import {
-  run as runOrchestrator,
-  projectOutcome,
-  requestToOptions,
-  type RunBackend,
-} from '../orchestrator/index.js'
-
-/** Run in-process via `run()` — core's default backend. Byte-identical to a plain `run()`. */
-export function localBackend(): RunBackend {
-  return {
-    async run(request) {
-      const summary = await runOrchestrator(requestToOptions(request))
-      return { ok: summary.ok, outcomes: summary.outcomes.map(projectOutcome) }
-    },
-  }
-}

package/src/cli/mcp-rpc.ts

@@ -1,292 +0,0 @@
-// MCP RPC dispatcher — pure handlers that the MCP server (and a future
-// WS-side inspector) both delegate to. Each tool here corresponds to one
-// of the inspector RPCs from docs/design/wire-protocol-2026-06.md §3.
-// Schemas are JSON Schema for the MCP listing; the handlers stay
-// untyped at the boundary and validate per-tool.
-//
-// Handlers open the local cache.db on demand. The MCP server is a
-// short-lived adapter — long-lived embedders should keep the Cache
-// open across calls via `setMcpContext`.
-
-import { Cache } from '../cache/index.js'
-import { LocalHistoryProvider } from '../orchestrator/index.js'
-import { findWorkspaceRoot, loadWorkspaceConfig, resolveCacheDir } from '../workspace/index.js'
-import { UserError } from '../util/index.js'
-
-export interface McpToolDef {
-  name: string
-  description: string
-  inputSchema: Record<string, unknown>
-}
-
-/**
- * Where the handlers reach for state. Overridable so an embedder
- * (a future inspector WS server) can inject a long-lived Cache + a
- * specific workspace root instead of opening one per RPC.
- */
-export interface McpContext {
-  /** Workspace root. Defaults to discovery from process.cwd(). */
-  workspaceRoot?: string
-}
-
-let mcpContext: McpContext = {}
-
-export function setMcpContext(ctx: McpContext): void {
-  mcpContext = ctx
-}
-
-const TOOLS: readonly McpToolDef[] = [
-  {
-    name: 'getCacheStats',
-    description: 'Aggregate cache statistics (entries, total size, hits in last 24h).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        scope: {
-          oneOf: [
-            { type: 'string', enum: ['all'] },
-            { type: 'object', properties: { project: { type: 'string' } }, required: ['project'] },
-          ],
-        },
-      },
-    },
-  },
-  {
-    name: 'getRunHistory',
-    description: 'Recent runs filtered by project / task, with per-task summary stats.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        project: { type: 'string' },
-        task: { type: 'string' },
-        limit: { type: 'integer', minimum: 1, maximum: 500, default: 50 },
-      },
-    },
-  },
-  {
-    name: 'explainCacheKey',
-    description:
-      'Break down the inputs that contribute to a task cache key (files / env / runtime / upstream).',
-    inputSchema: {
-      type: 'object',
-      properties: { taskId: { type: 'string', description: 'project#task' } },
-      required: ['taskId'],
-    },
-  },
-  {
-    name: 'whyDidThisRerun',
-    description:
-      'Compare two recent run cache keys for a task and identify the inputs that changed.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        runId: { type: 'string' },
-        taskId: { type: 'string' },
-      },
-      required: ['runId', 'taskId'],
-    },
-  },
-]
-
-export function listMcpTools(): readonly McpToolDef[] {
-  return TOOLS
-}
-
-/**
- * Dispatch a tool call by name. Returns a JSON-serializable result.
- */
-export async function handleMcpRequest(
-  name: string,
-  argsRaw: unknown,
-): Promise<Record<string, unknown>> {
-  const args = (argsRaw ?? {}) as Record<string, unknown>
-  switch (name) {
-    case 'getCacheStats':
-      return getCacheStats(args)
-    case 'getRunHistory':
-      return getRunHistory(args)
-    case 'explainCacheKey':
-      return explainCacheKey(args)
-    case 'whyDidThisRerun':
-      return whyDidThisRerun(args)
-    default:
-      throw new UserError(`vx mcp: unknown tool: ${name}`)
-  }
-}
-
-/** Discover + open a Cache against the current workspace. Caller closes. */
-async function openCache(): Promise<{ cache: Cache; workspaceRoot: string }> {
-  const workspaceRoot = mcpContext.workspaceRoot ?? (await findWorkspaceRoot(process.cwd()))
-  const config = await loadWorkspaceConfig(workspaceRoot)
-  const cacheDir = resolveCacheDir(workspaceRoot, config)
-  return { cache: new Cache(cacheDir), workspaceRoot }
-}
-
-async function getCacheStats(args: Record<string, unknown>): Promise<Record<string, unknown>> {
-  const { cache } = await openCache()
-  try {
-    const stats = cache.stats()
-    const hitRate24h = stats.runCountLast24h > 0 ? stats.hitCountLast24h / stats.runCountLast24h : 0
-    return {
-      scope: args.scope ?? 'all',
-      entryCount: stats.entryCount,
-      totalBytes: stats.totalBytes,
-      runCountLast24h: stats.runCountLast24h,
-      hitCountLast24h: stats.hitCountLast24h,
-      hitRate24h,
-    }
-  } finally {
-    cache.close()
-  }
-}
-
-async function getRunHistory(args: Record<string, unknown>): Promise<Record<string, unknown>> {
-  const limit = typeof args.limit === 'number' ? Math.min(500, Math.max(1, args.limit)) : 50
-  const projectFilter = typeof args.project === 'string' ? args.project : undefined
-  const taskFilter = typeof args.task === 'string' ? args.task : undefined
-
-  const { cache } = await openCache()
-  try {
-    const db = cache.dbHandle()
-    // Distinct (project, task) pairs from the most recent runs.
-    const where: string[] = []
-    const params: (string | number)[] = []
-    if (projectFilter) {
-      where.push('project = ?')
-      params.push(projectFilter)
-    }
-    if (taskFilter) {
-      where.push('task = ?')
-      params.push(taskFilter)
-    }
-    const clause = where.length > 0 ? `WHERE ${where.join(' AND ')}` : ''
-    const pairs = db
-      .query(`SELECT DISTINCT project, task FROM runs ${clause} ORDER BY started_at DESC LIMIT ?`)
-      .all(...params, limit) as { project: string; task: string }[]
-    if (pairs.length === 0) {
-      return { runs: [], history: [] }
-    }
-    const ids = pairs.map((p) => `${p.project}#${p.task}`)
-    const provider = new LocalHistoryProvider(db)
-    const table = await provider.loadFor(ids)
-    const history = ids
-      .map((id) => {
-        const h = table.get(id)
-        return h ? { id, ...h } : null
-      })
-      .filter((x) => x !== null)
-    // Most-recent N rows for the timeline view.
-    const recent = db
-      .query(
-        `SELECT run_id AS runId, project, task, status, duration_ms AS durationMs,
-                started_at AS startedAt, ended_at AS endedAt, cache_hit AS cacheHit
-         FROM runs ${clause} ORDER BY started_at DESC LIMIT ?`,
-      )
-      .all(...params, limit) as Array<{
-      runId: string | null
-      project: string
-      task: string
-      status: string
-      durationMs: number
-      startedAt: number
-      endedAt: number
-      cacheHit: number | null
-    }>
-    return { runs: recent, history }
-  } finally {
-    cache.close()
-  }
-}
-
-async function explainCacheKey(args: Record<string, unknown>): Promise<Record<string, unknown>> {
-  const taskId = args.taskId
-  if (typeof taskId !== 'string' || !taskId.includes('#')) {
-    throw new UserError('explainCacheKey: taskId must be a "project#task" string')
-  }
-  const [project, task] = taskId.split('#', 2) as [string, string]
-  const { cache } = await openCache()
-  try {
-    const db = cache.dbHandle()
-    // The cache stores the resolved task hash on the latest entry; we
-    // surface what we know from the entries + runs tables. The deeper
-    // input-component breakdown (env / runtime / upstream) requires
-    // re-deriving the key from a live config; that's the next layer
-    // (a "prepareRun-lite" tool). For now we return what's persisted.
-    const entry = db
-      .query(
-        `SELECT hash, command, exit_code AS exitCode, duration_ms AS durationMs,
-                size_bytes AS sizeBytes, created_at AS createdAt
-         FROM entries WHERE project = ? AND task = ? ORDER BY created_at DESC LIMIT 1`,
-      )
-      .get(project, task) as
-      | {
-          hash: string
-          command: string
-          exitCode: number
-          durationMs: number
-          sizeBytes: number
-          createdAt: number
-        }
-      | undefined
-    return {
-      taskId,
-      project,
-      task,
-      latestEntry: entry ?? null,
-      note: 'cache key components (files / env / runtime / upstream hashes) require live config evaluation; this surface returns the persisted entry metadata',
-    }
-  } finally {
-    cache.close()
-  }
-}
-
-async function whyDidThisRerun(args: Record<string, unknown>): Promise<Record<string, unknown>> {
-  const runId = args.runId
-  const taskId = args.taskId
-  if (typeof runId !== 'string' || typeof taskId !== 'string') {
-    throw new UserError('whyDidThisRerun: runId and taskId must be strings')
-  }
-  if (!taskId.includes('#')) {
-    throw new UserError('whyDidThisRerun: taskId must be a "project#task" string')
-  }
-  const [project, task] = taskId.split('#', 2) as [string, string]
-  const { cache } = await openCache()
-  try {
-    const db = cache.dbHandle()
-    const this_ = db
-      .query(
-        `SELECT hash, status, cache_hit AS cacheHit, started_at AS startedAt
-         FROM runs WHERE run_id = ? AND project = ? AND task = ?`,
-      )
-      .get(runId, project, task) as
-      | { hash: string; status: string; cacheHit: number | null; startedAt: number }
-      | undefined
-    if (!this_) {
-      return { runId, taskId, found: false, note: 'no row matching that runId + taskId' }
-    }
-    const prev = db
-      .query(
-        `SELECT hash, status, cache_hit AS cacheHit, started_at AS startedAt
-         FROM runs WHERE project = ? AND task = ? AND started_at < ?
-         ORDER BY started_at DESC LIMIT 1`,
-      )
-      .get(project, task, this_.startedAt) as
-      | { hash: string; status: string; cacheHit: number | null; startedAt: number }
-      | undefined
-    return {
-      runId,
-      taskId,
-      thisRun: this_,
-      previousRun: prev ?? null,
-      hashChanged: prev ? prev.hash !== this_.hash : null,
-      note:
-        prev && prev.hash !== this_.hash
-          ? 'cache key changed between the previous run and this one (inputs differ)'
-          : prev
-            ? 'cache key unchanged — re-run with the same key (likely --no-cache or unrelated)'
-            : 'no prior run for this (project, task)',
-    }
-  } finally {
-    cache.close()
-  }
-}