claude-code-runrate 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-runrate",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Claude Code run-rate — subscription burn-rate & economy for your Claude Code sessions.",
   "license": "MIT",
   "author": "Bing Ho <reps-attic-riot@duck.com>",
@@ -25,12 +25,18 @@
     "scripts/launch.sh",
     "sidecar",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
     "test": "node --test",
     "typecheck": "tsc --noEmit -p jsconfig.json",
-    "lint": "oxlint"
+    "lint": "oxlint",
+    "release-gate": "node scripts/release-gate.js",
+    "install-hooks": "node scripts/install-hooks.js",
+    "probe:wt": "node scripts/probe-wt.js",
+    "scan-package": "node scripts/scan-package.js",
+    "prepublishOnly": "npm run release-gate && npm run scan-package && npm run lint && npm run typecheck && npm test"
   },
   "keywords": [
     "claude-code",

package/scripts/launch.sh

@@ -42,7 +42,14 @@ chmod +x "$REPO/sidecar/ccr-statusline" 2>/dev/null || true
 
 # Prefer the newest nvm-installed node; `sort -V` is a GNU-ism, so suppress its
 # error on BSD/macOS and fall back to PATH node below.
-NODE="$(ls -d "$HOME"/.nvm/versions/node/*/bin/node 2>/dev/null | sort -V 2>/dev/null | tail -1)"
+#
+# The `|| true` is load-bearing, not defensive habit: with `set -e` and
+# `pipefail`, `ls` failing on a machine with no ~/.nvm makes the whole pipeline
+# non-zero, and a failing command substitution in an assignment aborts the
+# script. That killed the launcher outright — exit 2, no message, no sidebar —
+# for exactly the user who has plain Claude Code and no nvm, who then never
+# reaches the PATH fallback two lines below. Reproduced 2026-08-04.
+NODE="$(ls -d "$HOME"/.nvm/versions/node/*/bin/node 2>/dev/null | sort -V 2>/dev/null | tail -1 || true)"
 [ -x "$NODE" ] || NODE="$(command -v node || true)"
 [ -n "$NODE" ] || { echo "ccr: node not found" >&2; exit 1; }
 command -v tmux >/dev/null 2>&1 || { echo "ccr: tmux not found (required for the sidebar)" >&2; exit 1; }
@@ -55,13 +62,15 @@ if [ -n "$PROFILE" ]; then
     exit 1
   fi
   CC_CMD="ccs $PROFILE"
-  SESSION="${CCR_SESSION:-ccr-$PROFILE}"
-  STATE="${CCR_STATE_DIR:-$HOME/.ccr/$PROFILE}"
 else
   CC_CMD="${CC_BIN:-claude}"
-  SESSION="${CCR_SESSION:-ccr}"
-  STATE="${CCR_STATE_DIR:-$HOME/.ccr}"
 fi
+# The launcher normally arrives with CCR_SESSION/CCR_STATE_DIR already set by
+# the slot allocator (bin/ccr.js — every launch slots, profiled or bare). The
+# fallbacks cover only a direct invocation of this script, and they point at
+# slot 1's member dir: ~/.ccr itself is a container now, never a state dir.
+SESSION="${CCR_SESSION:-ccr}"
+STATE="${CCR_STATE_DIR:-$HOME/.ccr/instances/1}"
 
 # Every instance gets its OWN tmux server, on a socket named after the session
 # (-L puts it under /tmp/tmux-$UID/). On a shared server, one server death —
@@ -76,6 +85,17 @@ SOCKET="$SESSION"
 mkdir -p "$STATE"
 chmod 700 "$HOME/.ccr" "$STATE" 2>/dev/null || true
 rm -f "$STATE/exited"
+# The directory ccr was launched in — the tab's stable identity for the git
+# pane (src/state-dir.js: recordLaunchDir does the same for the other two
+# launchers). Best-effort: a tab that cannot record it falls back to naming
+# only the repo the session is in.
+# The rm is load-bearing, not tidiness: `>` on a planted FIFO blocks until a
+# reader appears and hangs the launcher here, before Claude is ever spawned, and
+# on a planted symlink it overwrites the link's target. Removing first turns both
+# into an ordinary create. src/state-dir.js does the same for the other two
+# launchers, and both sibling writers in <stateDir> already guard this way.
+rm -f "$STATE/launch-cwd" 2>/dev/null || true
+printf '%s\n' "$PWD" > "$STATE/launch-cwd" 2>/dev/null || true
 
 SETTINGS='{"statusLine":{"type":"command","command":"'"$REPO/sidecar/ccr-statusline"'"}}'
 
@@ -105,6 +125,15 @@ CLAUDE_PANE="$(tmux -L "$SOCKET" new-session -d -P -F '#{pane_id}' -s "$SESSION"
   "$ENV_PREAMBLE; $CC_CMD --settings '$SETTINGS'; touch '$STATE_Q/exited'; sleep 2; tmux -L '$SOCKET_Q' kill-session -t '$SESSION_Q' 2>/dev/null")"
 tmux -L "$SOCKET" set-environment -t "$SESSION" CCR_STATE_DIR "$STATE"
 
+# The tab's ADDRESS: composed once by the launcher (CCR_TITLE = "[profile / ]name",
+# both halves allow-listed), never retitled mid-session. set-titles-string is a
+# literal — deliberately NOT a tmux format that would follow the session; the
+# pane and the status line are the surfaces honest about movement.
+if [ -n "${CCR_TITLE:-}" ]; then
+  tmux -L "$SOCKET" set-option -t "$SESSION" set-titles on
+  tmux -L "$SOCKET" set-option -t "$SESSION" set-titles-string "$CCR_TITLE"
+fi
+
 # Pane 1: the live economy sidebar. Capture its pane id so we can scope a hook to it.
 SIDEBAR_PANE="$(tmux -L "$SOCKET" split-window -t "$SESSION:0" -h -p "${CCR_SIDEBAR_PCT:-34}" -P -F '#{pane_id}' \
   "$ENV_PREAMBLE; \"$NODE\" \"$REPO/bin/ccr.js\" sidecar; read -r -p 'sidebar exited — Enter to close '")"

package/src/account-limits.js

@@ -33,7 +33,8 @@ const { parseResetsAt } = require('./burn');
 const { modelScope } = require('./rate-limits');
 
 const MAX_SNAPSHOT_BYTES = 1_000_000; // a status JSON is a few KB; bound parse/disk
-const MAX_PROFILES = 32;              // sanity cap on how many siblings we scan
+const MAX_PROFILES = 32;              // sanity cap on how many siblings we merge
+const MAX_SCAN_ENTRIES = 512;         // sanity cap on how many dir entries we inspect
 
 /**
  * Canonical reset instant for fingerprinting/matching — tolerant of CC reporting
@@ -127,12 +128,14 @@ function readSiblingRateLimits(file) {
  * reconcile the local meters against them. Best-effort — returns `localRl` on any
  * problem so it can wrap the render path without a guard at the call site.
  *
- * Engages ONLY for the launcher's profile layout (`~/.ccr/<profile>`): the state
- * dir's parent must be `~/.ccr`. For ad-hoc `~/.ccr` or a custom CCR_STATE_DIR we
- * have no sibling set to trust, so we behave exactly as before (no merge).
+ * Engages ONLY for the launcher's layout: instances under `~/.ccr/instances/`
+ * (the 0.4.0 container/member split — src/instance-slot.js). A custom
+ * CCR_STATE_DIR elsewhere has no sibling set to trust, so it behaves as
+ * before (no merge). There is no slot-1 special case any more: slot 1 is an
+ * ordinary member of instances/, which is exactly why the layout changed.
  *
  * @param {any} localRl the local snapshot's `rate_limits`
- * @param {string} stateDir the local profile's state dir (CCR_STATE_DIR)
+ * @param {string} stateDir the local instance's state dir (CCR_STATE_DIR)
  * @param {{ home?: string }} [opts]
  * @returns {any}
  */
@@ -140,21 +143,26 @@ function freshenAccountLimits(localRl, stateDir, opts = {}) {
   try {
     if (!localRl || typeof localRl !== 'object') return localRl;
     const home = opts.home || os.homedir();
-    const root = path.dirname(path.resolve(stateDir));
-    if (root !== path.resolve(path.join(home, '.ccr'))) return localRl; // not a profile layout
+    const root = path.resolve(path.join(home, '.ccr', 'instances'));
+    const self = path.resolve(stateDir);
+    if (path.dirname(self) !== root) return localRl; // not the launcher's layout
     const selfFile = path.resolve(path.join(stateDir, 'last-status.json'));
 
     /** @type {any[]} */
     const siblings = [];
+    // Bound the WALK, not just the harvest: MAX_PROFILES alone counts collected
+    // siblings, so entries that yield nothing — slot dirs with no snapshot yet,
+    // junk — would all be stat'd on every tick. This runs inside the sidecar's
+    // ~1s draw loop, so the scan stays capped by entries seen even though
+    // instances/ holds only instance dirs under the 0.4.0 layout.
+    let seen = 0;
     for (const name of fs.readdirSync(root)) {
-      if (siblings.length >= MAX_PROFILES) break;
+      if (siblings.length >= MAX_PROFILES || ++seen > MAX_SCAN_ENTRIES) break;
       const p = path.join(root, name);
       let st; try { st = fs.statSync(p); } catch { continue; }
-      // A sibling profile dir (~/.ccr/<name>/last-status.json) or the ad-hoc
-      // ~/.ccr/last-status.json file itself.
-      const file = st.isDirectory() ? path.join(p, 'last-status.json')
-        : (name === 'last-status.json' ? p : null);
-      if (!file || path.resolve(file) === selfFile) continue;
+      if (!st.isDirectory()) continue;
+      const file = path.join(p, 'last-status.json');
+      if (path.resolve(file) === selfFile) continue;
       const rl = readSiblingRateLimits(file);
       if (rl) siblings.push(rl);
     }

package/src/doctor.js

@@ -9,6 +9,7 @@ const path = require('node:path');
 const os = require('node:os');
 const { spawnSync } = require('node:child_process');
 const { stripControl } = require('./sanitize');
+const { loadPaneConfig } = require('./pane-config');
 
 const ok = (/** @type {string} */ s) => `\x1b[32m✓\x1b[0m ${s}`;
 const bad = (/** @type {string} */ s) => `\x1b[31m✗\x1b[0m ${s}`;
@@ -36,7 +37,8 @@ function isExec(/** @type {string} */ f) {
 
 /**
  * @param {{ platform?: string, has?: (cmd: string) => (string|null),
- *   homedir?: string, repo?: string, write?: (s: string) => void }} [opts]
+ *   homedir?: string, repo?: string, write?: (s: string) => void,
+ *   env?: Record<string, string|undefined> }} [opts]
  *   side effects are injectable for testing; defaults hit the real environment
  * @returns {number} exit code (0 = healthy)
  */
@@ -91,8 +93,30 @@ 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).
+  // Pane wiring. This command exists to diagnose "nothing happens", and a pane
+  // config the user wrote and got wrong is exactly that — the sidecar has room
+  // for a one-line marker and no more. Here there is room for the path, the
+  // reason, and what ccr actually read out of the file, which is the question
+  // someone whose pane never appeared is really asking.
+  const cfg = loadPaneConfig({ env: opts.env, home: homedir });
+  if (cfg.error) {
+    out.push(bad(`pane config: ${cfg.error} — ${stripControl(cfg.configPath)}`));
+    problems++;
+  } else if (cfg.panes.length) {
+    out.push(ok(`pane config: ${cfg.panes.length} pane(s) (${stripControl(cfg.configPath)})`));
+    // The path as ccr resolved it, not as written: a tilde that did not expand
+    // is invisible in the source string and obvious in the resolved one.
+    for (const pane of cfg.panes) out.push(dim(`  · ${stripControl(pane.path)}`));
+  } else {
+    out.push(dim(`· no panes configured (optional — ${stripControl(cfg.configPath)})`));
+  }
+
+  // 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 +125,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 };