claude-code-runrate 0.3.0 → 0.4.0

package/src/doctor.js

@@ -91,8 +91,12 @@ function run(opts = {}) {
     out.push(dim('· ccs not installed (optional — only for `ccr <profile>`)'));
   }
 
-  // newest captured snapshot across ~/.ccr and its per-profile subdirs (state
-  // lives under the user's home now, never world-shared /tmp).
+  // newest captured snapshot across the container. Instances live TWO levels
+  // down under the 0.4.0 layout (~/.ccr/instances/<n>/last-status.json) — the
+  // one-level scan alone would report "no status captured" while instances run
+  // fine (features/instance-lifecycle.feature: "doctor finds a live instance's
+  // captured status"). The root and one-level entries are still scanned so a
+  // pre-migration home keeps diagnosing.
   const ccrDir = path.join(homedir, '.ccr');
   const dirs = [ccrDir];
   try {
@@ -101,6 +105,13 @@ function run(opts = {}) {
       try { if (fs.statSync(sub).isDirectory()) dirs.push(sub); } catch { /* ignore */ }
     }
   } catch { /* none */ }
+  try {
+    const inst = path.join(ccrDir, 'instances');
+    for (const d of fs.readdirSync(inst)) {
+      const sub = path.join(inst, d);
+      try { if (fs.statSync(sub).isDirectory()) dirs.push(sub); } catch { /* ignore */ }
+    }
+  } catch { /* none */ }
   let newest = null;
   for (const d of dirs) {
     try { const m = fs.statSync(path.join(d, 'last-status.json')).mtimeMs; if (!newest || m > newest.m) newest = { d, m }; } catch { /* none */ }

package/src/git-history.js

@@ -0,0 +1,273 @@
+// @ts-check
+'use strict';
+// src/git-history.js — recent commits with their branch structure, the model
+// behind the pane's graph section (features/git-commit-graph.feature).
+//
+// THE WALK STARTS AT EVERY LOCAL BRANCH, not just HEAD. The visionary chose a
+// multi-lane graph to match IDE git-graph habits, and those graphs answer
+// "what lines of work exist here", which a HEAD-ancestry walk cannot — a
+// repository with three topic branches would draw one lane and call itself
+// done. Tips are ordered newest-first; when there are more tips than lanes
+// (laneBudget in the renderer), the newest keep their lanes and the rest are
+// COUNTED, never silently dropped — the lane-overflow scenario exists because
+// the visionary was warned a graph that dropped branches would be worse than
+// the flat list it replaced.
+//
+// LANE ASSIGNMENT is the classic newest-first sweep: each lane holds the
+// commit id it expects next; a commit takes the leftmost lane expecting it,
+// closes every other lane that expected it (a fork, seen from below), and
+// hands its first parent that lane — extra parents open lanes beside it (the
+// merge's second line). This is a simplification of git log --graph's painter
+// and its contract is exactly what the scenarios pin: lane COUNT, join at the
+// merge, newest first.
+//
+// Commit metadata is display data from an untrusted repository: subjects are
+// stripped at THIS boundary (the choke-point rule of src/git-repo.js), and
+// every read is bounded — the walk has a hard commit cap, and object reads
+// inherit src/git-objects.js's own caps.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { readObject, resolveHead, resolveRef } = require('./git-objects');
+const { readTextCapped } = require('./safe-read');
+const { stripControl } = require('./sanitize');
+
+// More commits than a sidebar can show, fewer than a pathological repository
+// could make us read. The renderer slices further by its row budget.
+const MAX_COMMITS = 64;
+
+// Branch tips considered, before the renderer's lane budget cuts further.
+const MAX_TIPS = 128;
+
+// A subject longer than this cannot survive any pane layout; cap at the read
+// boundary so layout budgets around a value, not a megabyte.
+const SUBJECT_MAX = 200;
+
+/**
+ * @typedef {object} CommitRow
+ * @property {string} oid
+ * @property {string} shortHash   7 hex chars, git's default abbreviation floor.
+ * @property {string} subject     First message line, control-stripped, capped.
+ * @property {number} when        Committer time, seconds.
+ * @property {number} lane        0-based lane of this commit's node.
+ * @property {boolean[]} activeMask  Which lanes are live on this row (the
+ *   renderer's `│` columns).
+ * @property {number[]} joinLanes  Lanes this merge's extra parents run in —
+ *   the renderer's join glyph, the merge scenario's evidence.
+ * @property {boolean} closes     Another lane also expected this commit (a
+ *   fork seen from below) and was folded into this one.
+ */
+
+/**
+ * @typedef {object} History
+ * @property {'ok'|'empty'|'unavailable'} state  'empty' = no commits anywhere.
+ * @property {CommitRow[]} rows        Newest first.
+ * @property {number} laneCount        Widest simultaneous lane use.
+ * @property {number} droppedBranches  Tips beyond the lane budget, counted.
+ */
+
+/**
+ * Parse the header of a commit object: tree, parents, committer time, subject.
+ * @param {Buffer} data
+ * @returns {{ parents: string[], when: number, subject: string }|null}
+ */
+function parseCommit(data) {
+  const text = data.toString('utf8');
+  const headerEnd = text.indexOf('\n\n');
+  const header = headerEnd === -1 ? text : text.slice(0, headerEnd);
+  if (!/^tree [0-9a-f]{40}|^tree [0-9a-f]{64}/m.test(header)) return null;
+  const parents = [...header.matchAll(/^parent ([0-9a-f]{40}|[0-9a-f]{64})$/gm)].map((m) => m[1]);
+  const committer = /^committer [^\n]* (\d{1,12}) [+-]\d{4}$/m.exec(header);
+  const when = committer ? Number(committer[1]) : 0;
+  const body = headerEnd === -1 ? '' : text.slice(headerEnd + 2);
+  const firstLine = body.split('\n')[0] || '';
+  const clean = stripControl(firstLine).trim();
+  const cps = [...clean];
+  const subject = cps.length <= SUBJECT_MAX ? clean : cps.slice(0, SUBJECT_MAX - 1).join('') + '…';
+  return { parents, when, subject };
+}
+
+/**
+ * Every local branch tip: loose refs under refs/heads plus packed-refs
+ * entries, deduplicated, HEAD's target included even when detached.
+ * @param {string} gitDir
+ * @returns {string[]}  Tip oids, unordered.
+ */
+function branchTips(gitDir) {
+  /** @type {Set<string>} */
+  const tips = new Set();
+  const headsDir = path.join(gitDir, 'refs', 'heads');
+  /** @type {Array<{ dir: string, ref: string }>} */
+  const stack = [{ dir: headsDir, ref: 'refs/heads' }];
+  let visited = 0;
+  while (stack.length > 0 && tips.size < MAX_TIPS) {
+    const top = /** @type {{ dir: string, ref: string }} */ (stack.pop());
+    /** @type {fs.Dirent[]} */
+    let dirents = [];
+    try { dirents = fs.readdirSync(top.dir, { withFileTypes: true }); } catch { continue; }
+    for (const d of dirents) {
+      visited += 1;
+      if (visited > MAX_TIPS * 4) break;
+      if (d.isDirectory()) stack.push({ dir: path.join(top.dir, d.name), ref: top.ref + '/' + d.name });
+      else if (d.isFile()) {
+        const oid = resolveRef(gitDir, top.ref + '/' + d.name);
+        if (oid) tips.add(oid);
+      }
+    }
+  }
+  const packed = readTextCapped(path.join(gitDir, 'packed-refs'), 4 * 1024 * 1024);
+  if (packed) {
+    for (const line of packed.split('\n')) {
+      if (tips.size >= MAX_TIPS) break;
+      const m = /^([0-9a-f]{40}|[0-9a-f]{64}) refs\/heads\/\S+$/.exec(line.trim());
+      // A loose ref shadows its packed entry; resolveRef already prefers it,
+      // and adding the packed oid too would resurrect a stale tip. Only tips
+      // whose ref has no loose file get taken from here — approximated by the
+      // Set: a shadowed packed oid that differs would add a phantom tip, so
+      // resolve the ref properly instead.
+      if (m) {
+        const ref = line.trim().slice(line.trim().indexOf(' ') + 1);
+        const oid = resolveRef(gitDir, ref);
+        if (oid) tips.add(oid);
+      }
+    }
+  }
+  const head = resolveHead(gitDir);
+  if (head) tips.add(head);
+  return [...tips];
+}
+
+/**
+ * Read recent history: tips, walk, lanes.
+ *
+ * @param {string} gitDir
+ * @param {{ maxLanes?: number, maxRows?: number }} [opts]
+ * @returns {History}
+ */
+function readHistory(gitDir, opts = {}) {
+  const maxLanes = opts.maxLanes && opts.maxLanes > 0 ? opts.maxLanes : 6;
+  const maxRows = opts.maxRows && opts.maxRows > 0 ? Math.min(opts.maxRows, MAX_COMMITS) : MAX_COMMITS;
+
+  const tips = branchTips(gitDir);
+  if (tips.length === 0) {
+    // No refs anywhere. An unborn HEAD (fresh init) is the EMPTY state the
+    // no-commits scenario names; an unreadable HEAD is not.
+    const raw = readTextCapped(path.join(gitDir, 'HEAD'), 4096);
+    const unborn = raw !== null && /^ref:[ \t]*refs\//.test(raw.split('\n')[0].trim());
+    return { state: unborn ? 'empty' : 'unavailable', rows: [], laneCount: 0, droppedBranches: 0 };
+  }
+
+  // Load every tip commit; tips that no longer resolve to a commit degrade the
+  // whole section (never guess at history).
+  /** @type {Map<string, { parents: string[], when: number, subject: string }>} */
+  const loaded = new Map();
+  const load = (/** @type {string} */ oid) => {
+    if (loaded.has(oid)) return loaded.get(oid) || null;
+    const obj = readObject(gitDir, oid);
+    if (obj === null || obj.type !== 'commit') return null;
+    const parsed = parseCommit(obj.data);
+    if (parsed === null) return null;
+    loaded.set(oid, parsed);
+    return parsed;
+  };
+
+  /** @type {Array<{ oid: string, when: number }>} */
+  const tipList = [];
+  for (const oid of tips) {
+    const c = load(oid);
+    if (c === null) return { state: 'unavailable', rows: [], laneCount: 0, droppedBranches: 0 };
+    tipList.push({ oid, when: c.when });
+  }
+  tipList.sort((a, b) => b.when - a.when || (a.oid < b.oid ? -1 : 1));
+  const taken = tipList.slice(0, maxLanes);
+  // Tips sharing history with a taken tip still count as their own branch —
+  // the scenario counts BRANCHES, and each tip is one.
+  const droppedBranches = tipList.length - taken.length;
+
+  // Date-ordered walk from the taken tips: a max-heap by committer time,
+  // approximated with a sorted array (sizes here are tens, not thousands).
+  /** @type {Array<{ oid: string, when: number }>} */
+  const frontier = [...taken];
+  /** @type {Set<string>} */
+  const emitted = new Set();
+  /** Lanes: the commit id each lane expects next (null = closed). */
+  /** @type {Array<string|null>} */
+  const lanes = [];
+  /** @type {CommitRow[]} */
+  const rows = [];
+  let laneCount = 0;
+
+  while (frontier.length > 0 && rows.length < maxRows) {
+    frontier.sort((a, b) => b.when - a.when || (a.oid < b.oid ? -1 : 1));
+    const next = /** @type {{ oid: string, when: number }} */ (frontier.shift());
+    if (emitted.has(next.oid)) continue;
+    const c = load(next.oid);
+    if (c === null) return { state: 'unavailable', rows: [], laneCount: 0, droppedBranches };
+    emitted.add(next.oid);
+
+    // The leftmost lane expecting this commit; none → a new tip opens a lane.
+    let lane = lanes.findIndex((l) => l === next.oid);
+    let closes = false;
+    if (lane === -1) {
+      lane = lanes.findIndex((l) => l === null);
+      if (lane === -1) { lanes.push(null); lane = lanes.length - 1; }
+    } else {
+      // Every OTHER lane expecting it folds into this one — a fork, viewed
+      // from below.
+      for (let i = 0; i < lanes.length; i += 1) {
+        if (i !== lane && lanes[i] === next.oid) { lanes[i] = null; closes = true; }
+      }
+    }
+    const first = c.parents[0] || null;
+    lanes[lane] = first && !emitted.has(first) ? first : null;
+    /** @type {number[]} */
+    const joinLanes = [];
+    for (const p of c.parents.slice(1)) {
+      if (emitted.has(p)) continue;
+      const existing = lanes.indexOf(p);
+      if (existing !== -1) {
+        // The merge's other line already runs in a lane; the join points there.
+        joinLanes.push(existing);
+        continue;
+      }
+      // Open the nearest free lane for it.
+      let free = lanes.findIndex((l) => l === null);
+      if (free === -1) {
+        if (lanes.length >= maxLanes) continue;
+        lanes.push(p);
+        free = lanes.length - 1;
+      } else {
+        lanes[free] = p;
+      }
+      joinLanes.push(free);
+    }
+    while (lanes.length > 0 && lanes[lanes.length - 1] === null) lanes.pop();
+    const activeMask = lanes.map((l) => l !== null);
+    while (activeMask.length < lane + 1) activeMask.push(false);
+    activeMask[lane] = true; // the node's own column is always drawn
+    const active = activeMask.filter(Boolean).length;
+    laneCount = Math.max(laneCount, Math.max(active, lane + 1));
+
+    rows.push({
+      oid: next.oid,
+      shortHash: next.oid.slice(0, 7),
+      subject: c.subject,
+      when: c.when,
+      lane,
+      activeMask,
+      joinLanes,
+      closes,
+    });
+    for (const p of c.parents) {
+      if (!emitted.has(p)) {
+        const pc = load(p);
+        if (pc === null) return { state: 'unavailable', rows: [], laneCount: 0, droppedBranches };
+        frontier.push({ oid: p, when: pc.when });
+      }
+    }
+  }
+
+  return { state: 'ok', rows, laneCount: Math.min(laneCount, maxLanes), droppedBranches };
+}
+
+module.exports = { readHistory, branchTips, parseCommit, MAX_COMMITS };

package/src/git-ignore.js

@@ -0,0 +1,118 @@
+// @ts-check
+'use strict';
+// src/git-ignore.js — enough of gitignore matching for the untracked walk.
+//
+// The untracked list is the one part of the working-tree section that reads
+// the WORLD rather than `.git`, and without ignore rules it would lead with
+// node_modules — a thousand-line lie of omission about what the user actually
+// created. So the walk honors the two per-repo sources: `.git/info/exclude`
+// and every `.gitignore` on the path down.
+//
+// WHAT IS DELIBERATELY OUT: the user's global excludesFile (a config lookup
+// away, but its patterns describe the USER's machine, and the far-side oracle
+// pins this reader against `git status` run with that config disabled), and
+// the escape subtleties (`\#`, trailing backslash-space). Both are recorded in
+// features/design/git-untracked-walk.feature rather than silently absent.
+//
+// Precedence is git's: within one file the LAST matching pattern wins; a
+// deeper .gitignore beats a shallower one; exclude is the weakest. A directory
+// that is ignored is never descended into, which also reproduces git's "cannot
+// re-include below an excluded directory" rule for free.
+
+/**
+ * @typedef {object} IgnoreRule
+ * @property {boolean} neg      `!pattern` — re-includes.
+ * @property {boolean} dirOnly  Trailing slash — matches directories only.
+ * @property {RegExp} re        Compiled against the path RELATIVE TO the rule's base.
+ */
+
+/**
+ * Compile one gitignore pattern line, or null for blanks and comments.
+ * @param {string} line
+ * @returns {IgnoreRule|null}
+ */
+function compilePattern(line) {
+  let p = line.replace(/\r$/, '');
+  if (!p || p.startsWith('#')) return null;
+  let neg = false;
+  if (p.startsWith('!')) { neg = true; p = p.slice(1); }
+  p = p.replace(/(?<!\\)\s+$/, ''); // unescaped trailing spaces are trimmed
+  if (!p) return null;
+  let dirOnly = false;
+  if (p.endsWith('/')) { dirOnly = true; p = p.slice(0, -1); }
+  // A slash anywhere (now that a trailing one is gone) anchors the pattern to
+  // the rule's own directory; without one it matches at any depth.
+  const anchored = p.includes('/');
+  if (p.startsWith('/')) p = p.slice(1);
+
+  let re = '';
+  for (let i = 0; i < p.length; i += 1) {
+    const c = p[i];
+    if (c === '*') {
+      if (p[i + 1] === '*') {
+        // `**` spans directories: leading `**/` any prefix, trailing `/**`
+        // everything below, `a**b` collapses to any run.
+        i += 1;
+        if (p[i + 1] === '/') { i += 1; re += '(?:[^/]+/)*'; } else re += '.*';
+      } else re += '[^/]*';
+    } else if (c === '?') {
+      re += '[^/]';
+    } else if (c === '[') {
+      const close = p.indexOf(']', i + 2);
+      if (close === -1) { re += '\\['; continue; }
+      let cls = p.slice(i + 1, close);
+      if (cls.startsWith('!')) cls = '^' + cls.slice(1);
+      re += '[' + cls.replace(/\\/g, '\\\\') + ']';
+      i = close;
+    } else if (c === '\\' && i + 1 < p.length) {
+      i += 1;
+      re += p[i].replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    } else {
+      re += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  const body = anchored ? re : '(?:[^/]+/)*' + re;
+  let compiled;
+  try {
+    compiled = new RegExp('^' + body + '$');
+  } catch {
+    return null; // a pattern this reader cannot compile ignores nothing
+  }
+  return { neg, dirOnly, re: compiled };
+}
+
+/**
+ * Parse a whole ignore file's text into rules, in order.
+ * @param {string|null} text
+ * @returns {IgnoreRule[]}
+ */
+function parseIgnore(text) {
+  if (!text) return [];
+  /** @type {IgnoreRule[]} */
+  const out = [];
+  for (const line of text.split('\n')) {
+    const rule = compilePattern(line);
+    if (rule) out.push(rule);
+  }
+  return out;
+}
+
+/**
+ * Is `rel` (POSIX path relative to the rules' base) ignored by these rules?
+ * Returns the last matching rule's verdict, or null when nothing matched.
+ * @param {IgnoreRule[]} rules
+ * @param {string} rel
+ * @param {boolean} isDir
+ * @returns {boolean|null}
+ */
+function matchRules(rules, rel, isDir) {
+  /** @type {boolean|null} */
+  let verdict = null;
+  for (const r of rules) {
+    if (r.dirOnly && !isDir) continue;
+    if (r.re.test(rel)) verdict = !r.neg;
+  }
+  return verdict;
+}
+
+module.exports = { compilePattern, parseIgnore, matchRules };

package/src/git-index.js

@@ -0,0 +1,167 @@
+// @ts-check
+'use strict';
+// src/git-index.js — parse `.git/index`, the staging area, without git.
+//
+// Second stop of the build fork src/git-repo.js rules in its header: the pane
+// reads `.git` itself, so the working-tree section needs the index in git's own
+// on-disk format. The contract this parser is held to lives in
+// features/design/git-index-format.feature — the design tier, because an index
+// byte layout is an implementation criterion no visionary should be asked to
+// review.
+//
+// WHAT IS PARSED, AND WHAT IS DELIBERATELY NOT. Versions 2, 3 and 4 — the three
+// git writes today — including the stage bits that mark conflicts and the stat
+// cache the modified-check needs. Extensions (TREE, REUC, link…) are skipped
+// whole: every one is an optimization cache over the entries themselves, and a
+// reader that consults none of them can never be lied to by a stale one.
+//
+// EVERY FAILURE IS null, NEVER A GUESS. A truncated entry, an impossible count,
+// an unknown version, an over-cap file — the caller degrades to "git data
+// unavailable" (features/git-pane-safety.feature), which is honest where a
+// partial listing would be a quiet lie about what is staged.
+//
+// Hostile-input rules are src/safe-read.js's: the index is read through
+// readBytesCapped (regular file only, size-capped, never blocks), and paths are
+// NOT display-sanitized here — the model layer does that at its own boundary,
+// because these paths are also compared against real directory listings and a
+// stripped path would fail to match the file it names.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readBytesCapped, readTextCapped } = require('./safe-read');
+
+// A generous roof, not a target: the linux kernel's index is ~10 MB. Past this
+// the pane degrades rather than spending the draw loop's budget parsing.
+const INDEX_MAX_BYTES = 32 * 1024 * 1024;
+
+// Entries are ~70 bytes plus a path, so this cap can only trip on a file whose
+// header count lies about its body — the exact corruption it exists to stop.
+const MAX_ENTRIES = 200_000;
+
+/**
+ * One index entry. `stage` is 0 for an ordinary staged path and 1..3 for the
+ * three sides of a conflict (base, ours, theirs).
+ *
+ * @typedef {object} IndexEntry
+ * @property {string} path      Repo-relative, POSIX separators, as git stores it.
+ * @property {number} mode      File mode (e.g. 0o100644, 0o120000 symlink).
+ * @property {number} stage     0 normal, 1-3 conflict stages.
+ * @property {string} oid       Object id, lowercase hex (40 or 64 chars).
+ * @property {number} size      Cached worktree size at add time.
+ * @property {number} mtimeSec  Cached worktree mtime (seconds).
+ * @property {number} mtimeNsec Cached worktree mtime (nanoseconds part).
+ */
+
+/**
+ * @typedef {object} GitIndex
+ * @property {IndexEntry[]} entries  In file order (git keeps them path-sorted).
+ * @property {number} version
+ * @property {number} mtimeMs        The index file's own mtime — the racy-clean
+ *   comparison needs it (see src/git-working-tree.js).
+ */
+
+/**
+ * Does this repository use sha-256 object names? The index does not declare its
+ * hash width; the repository does, in config. A config that cannot be read
+ * means the default format, which is what the fallback answers.
+ * @param {string} gitDir
+ * @returns {boolean}
+ */
+function usesSha256(gitDir) {
+  const cfg = readTextCapped(path.join(gitDir, 'config'), 64 * 1024);
+  return cfg != null && /^\s*objectformat\s*=\s*sha256\s*$/im.test(cfg);
+}
+
+/**
+ * Parse `.git/index`. Returns the entries, or null when the file cannot be
+ * trusted, or `{ entries: [] }` (empty, versioned 0) when it simply does not
+ * exist — a freshly-initialized repository has no index yet, and "nothing is
+ * staged" is the true statement about it.
+ *
+ * @param {string} gitDir
+ * @returns {GitIndex|null}
+ */
+function readIndex(gitDir) {
+  const file = path.join(gitDir, 'index');
+  let st = null;
+  try { st = fs.lstatSync(file); } catch { st = null; }
+  if (st === null) return { entries: [], version: 0, mtimeMs: 0 };
+
+  const buf = readBytesCapped(file, INDEX_MAX_BYTES);
+  if (buf === null || buf.length < 12) return null;
+  if (buf.toString('latin1', 0, 4) !== 'DIRC') return null;
+  const version = buf.readUInt32BE(4);
+  if (version < 2 || version > 4) return null;
+  const count = buf.readUInt32BE(8);
+  if (count > MAX_ENTRIES) return null;
+
+  const hashBytes = usesSha256(gitDir) ? 32 : 20;
+  /** @type {IndexEntry[]} */
+  const entries = [];
+  let off = 12;
+  let prevPath = '';
+  for (let i = 0; i < count; i += 1) {
+    const start = off;
+    // Fixed part: ctime(8) mtime(8) dev(4) ino(4) mode(4) uid(4) gid(4)
+    // size(4) oid(hashBytes) flags(2).
+    if (off + 40 + hashBytes + 2 > buf.length) return null;
+    const mtimeSec = buf.readUInt32BE(off + 8);
+    const mtimeNsec = buf.readUInt32BE(off + 12);
+    const mode = buf.readUInt32BE(off + 24);
+    const size = buf.readUInt32BE(off + 36);
+    const oid = buf.toString('hex', off + 40, off + 40 + hashBytes);
+    const flags = buf.readUInt16BE(off + 40 + hashBytes);
+    off += 40 + hashBytes + 2;
+    const stage = (flags >> 12) & 0x3;
+    // Version 3+ may carry an extended-flags word, marked by bit 14.
+    if (flags & 0x4000) {
+      if (version < 3 || off + 2 > buf.length) return null;
+      off += 2;
+    }
+
+    /** @type {string} */
+    let p;
+    if (version === 4) {
+      // v4 compresses paths: a varint N ("strip N bytes from the previous
+      // path"), then the NUL-terminated suffix to append.
+      if (off >= buf.length) return null;
+      let b = buf[off]; off += 1;
+      let strip = b & 0x7f;
+      let hops = 0;
+      while (b & 0x80) {
+        // Git's offset varint: the accumulated value gains 1 BEFORE each
+        // 7-bit shift — decode_varint in git's own varint.c.
+        if (off >= buf.length || hops > 6) return null;
+        b = buf[off]; off += 1;
+        strip = ((strip + 1) << 7) + (b & 0x7f);
+        hops += 1;
+      }
+      const nul = buf.indexOf(0, off);
+      if (nul === -1) return null;
+      const suffix = buf.toString('utf8', off, nul);
+      off = nul + 1;
+      if (strip > prevPath.length) return null;
+      p = prevPath.slice(0, prevPath.length - strip) + suffix;
+    } else {
+      // v2/v3: NUL-terminated path, then the whole entry padded with NULs to a
+      // multiple of 8 bytes from the entry's start.
+      const nameLen = flags & 0x0fff;
+      const nul = nameLen < 0x0fff && off + nameLen <= buf.length && buf[off + nameLen] === 0
+        ? off + nameLen
+        : buf.indexOf(0, off);
+      if (nul === -1) return null;
+      p = buf.toString('utf8', off, nul);
+      off = nul + 1;
+      const entryLen = off - start;
+      const padded = Math.ceil(entryLen / 8) * 8;
+      off = start + padded;
+      if (off > buf.length) return null;
+    }
+    if (!p) return null;
+    entries.push({ path: p, mode, stage, oid, size, mtimeSec, mtimeNsec });
+    prevPath = p;
+  }
+  return { entries, version, mtimeMs: st.mtimeMs };
+}
+
+module.exports = { readIndex, usesSha256, INDEX_MAX_BYTES, MAX_ENTRIES };