claude-memory-admin 1.7.0 → 1.9.0

package/public/views/sessions.mjs

@@ -5,6 +5,8 @@ import { state } from '/state.mjs';
 import { sizeLabel, sessionDate, isAt } from '/parts.mjs';
 import { selectMemory } from '/store.mjs';
 import { paint } from '/bus.mjs';
+import { goTo } from '/parts.mjs';
+import { toast } from '/api.mjs';
 
 const TITLE_SOURCE = {
   'ai-title': 'title Claude Code generated for this session',
@@ -12,11 +14,32 @@ const TITLE_SOURCE = {
   prompt: 'first prompt, no generated title found in the part read',
 };
 
-function sessionRow(session, memoriesFrom) {
+export function focusSession(id) {
+  state.aux.sessionFocus = id;
+  state.aux.sessionDay = null;
+  goTo('environment', 'sessions');
+}
+
+function agoLabel(ms) {
+  const seconds = Math.max(0, Math.round((Date.now() - ms) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  return `${Math.round(minutes / 60)}h ago`;
+}
+
+function sessionRow(session, memoriesFrom, focused, live) {
   const soon = session.expiresInDays !== null && session.expiresInDays <= 7;
-  const caret = node('span', { class: ui.contextCaret, text: '\u25b8' });
+  const caret = node('span', { class: ui.contextCaret, text: focused ? '\u25be' : '\u25b8' });
 
   const tags = [];
+  if (live) {
+    tags.push(node('span', {
+      class: ui.badge('ok'),
+      text: live.status === 'waiting' ? 'waiting' : live.status || 'active',
+      title: live.waitingFor || `updated ${agoLabel(live.updatedAt)}`,
+    }));
+  }
   if (session.gitBranch) tags.push(node('span', { class: ui.badge('neutral'), text: session.gitBranch }));
   if (session.model) tags.push(node('span', { class: ui.badge('neutral'), text: session.model }));
   if (session.expiresInDays !== null) {
@@ -29,7 +52,7 @@ function sessionRow(session, memoriesFrom) {
     tags.push(node('span', { class: ui.badge('project'), text: memory.name }));
   }
 
-  const body = node('div', { class: ui.contextBody, hidden: true });
+  const body = node('div', { class: ui.contextBody, hidden: !focused });
   const facts = node('dl', { class: ui.metaList });
   const rows = [
     ['session', session.id],
@@ -62,7 +85,7 @@ function sessionRow(session, memoriesFrom) {
 
   const button = node('button', {
     class: ui.contextRowButton,
-    'aria-expanded': 'false',
+    'aria-expanded': String(Boolean(focused)),
     onclick: (event) => {
       const open = body.hidden;
       body.hidden = !open;
@@ -188,8 +211,33 @@ export async function renderSessions(container) {
     paint('tab');
   };
 
+  const active = state.activeSessions.filter((s) => s.storeId === state.storeId);
+  const byId = new Map(active.map((s) => [s.sessionId, s]));
+
   container.append(node('p', { class: ui.noteTight, text: 'The transcripts sitting beside this store\u2019s memory. Claude Code deletes them once they pass the retention period and never touches memory/, so this is the evidence that expires while the memories stay. This tab only reads, and only the head of each file - nothing here deletes a transcript.' }));
 
+  if (active.length) {
+    const list = node('div', { class: ui.card });
+    for (const session of active) {
+      list.append(node('button', {
+        class: ui.contextRowButton,
+        onclick: () => focusSession(session.sessionId),
+      }, [
+        node('div', { class: ui.contextMain }, [
+          node('div', { class: ui.contextTags }, [
+            node('span', {
+              class: ui.badge('ok'),
+              text: session.status === 'waiting' ? 'waiting' : session.status || 'active',
+            }),
+          ]),
+          node('div', { class: ui.contextFile, text: session.name || session.sessionId }),
+        ]),
+        node('div', { class: ui.contextSize, text: session.waitingFor || agoLabel(session.updatedAt) }),
+      ]));
+    }
+    container.append(meterPanel('Active now', null, list));
+  }
+
   container.append(node('div', { class: ui.meter }, [
     node('div', { class: ui.meterTop }, [
       node('span', { class: ui.meterValue, text: String(data.count) }),
@@ -227,9 +275,21 @@ export async function renderSessions(container) {
     }));
   }
   container.append(listHead);
+  const focus = state.aux.sessionFocus;
+  state.aux.sessionFocus = null;
+
   const card = node('div', { class: ui.card });
+  let focused = null;
   for (const session of visible) {
-    card.append(sessionRow(session, byOrigin.get(session.id) || []));
+    const row = sessionRow(session, byOrigin.get(session.id) || [], session.id === focus, byId.get(session.id));
+    if (session.id === focus) focused = row;
+    card.append(row);
   }
   container.append(card);
+
+  if (focus && focused) {
+    requestAnimationFrame(() => focused.scrollIntoView({ block: 'center' }));
+  } else if (focus) {
+    toast('That transcript is no longer beside this store - Claude Code has swept it.');
+  }
 }

package/public/views/stores.mjs

@@ -22,10 +22,17 @@ function issueTitle(store) {
   return parts.length ? `${store.dir}\n${parts.join(', ')}` : store.dir;
 }
 
+function activeTitle(active) {
+  const waiting = active.filter((s) => s.status === 'waiting').length;
+  const label = active.length === 1 ? '1 session' : `${active.length} sessions`;
+  return waiting ? `${label} - ${waiting} waiting for input` : `${label} ${active.length === 1 ? 'is' : 'are'} busy`;
+}
+
 function storeButton(store) {
   const global = store.kind === 'global';
   const health = !global && !store.hasMemoryDir ? 'none' : store.severity || 'ok';
   const off = store.autoMemory && store.autoMemory.known && !store.autoMemory.enabled;
+  const active = state.activeSessions.filter((s) => s.storeId === store.id);
   return node('button', {
     class: ui.storeItem({ active: store.id === state.storeId, empty: !global && !store.hasMemoryDir }),
     onclick: () => openStore(store.id),
@@ -34,6 +41,7 @@ function storeButton(store) {
     node('span', { class: ui.storeRow }, [
       node('span', { class: ui.dot(health) }),
       node('span', { class: ui.storeName, text: store.label }),
+      active.length ? node('span', { class: ui.dot('ok'), title: activeTitle(active) }) : null,
       off ? node('span', { class: ui.offMarker, text: 'off', title: 'Auto memory is disabled for this project' }) : null,
       global ? null : node('span', { class: ui.storeCount, text: store.hasMemoryDir ? String(store.memoryCount) : '-' }),
     ]),

package/public/views/tools.mjs

@@ -4,73 +4,141 @@ import { api } from '/api.mjs';
 import { state } from '/state.mjs';
 import { isAt } from '/parts.mjs';
 import { paint } from '/bus.mjs';
-import { renderRtk } from '/views/rtk.mjs';
+import { renderRtk, rtkSummary } from '/views/rtk.mjs';
+import { renderCcusage, ccusageSummary } from '/views/ccusage.mjs';
 
 const OPT_IN = 'toolsOptIn';
 
-const installedRtk = () => state.tools.find((tool) => tool.id === 'rtk' && tool.found) || null;
+const PANELS = {
+  rtk: { render: renderRtk, summary: rtkSummary },
+  ccusage: { render: renderCcusage, summary: ccusageSummary },
+};
 
-async function fetchRtk() {
-  const id = state.storeId;
+const installed = () => state.tools.filter((tool) => tool.found && PANELS[tool.id]);
+
+const openKey = (id) => `toolOpen:${id}`;
+const isOpen = (id) => localStorage.getItem(openKey(id)) === '1';
+
+function setOpen(id, open) {
+  if (open) localStorage.setItem(openKey(id), '1');
+  else localStorage.removeItem(openKey(id));
+}
+
+async function fetchTool(id) {
+  const storeId = state.storeId;
   let next;
   try {
-    next = { data: await api(`/api/stores/${encodeURIComponent(id)}/tools/rtk`) };
+    next = { data: await api(`/api/stores/${encodeURIComponent(storeId)}/tools/${encodeURIComponent(id)}`) };
   } catch (err) {
     next = { error: err.message };
   }
-  if (state.storeId !== id) return;
-  state.aux.rtk = next;
+  if (state.storeId !== storeId) return;
+  state.aux.tools = { ...state.aux.tools, [id]: next };
   if (isAt('environment', 'tools')) paint('tab');
 }
 
-function startRtk({ remember = true } = {}) {
+function start({ remember = true } = {}) {
   if (remember) localStorage.setItem(OPT_IN, '1');
-  state.aux.rtk = { running: true };
-  fetchRtk();
+  const running = {};
+  for (const tool of installed()) running[tool.id] = { running: true };
+  state.aux.tools = running;
+  for (const tool of installed()) fetchTool(tool.id);
 }
 
-function readRtk() {
-  startRtk();
+function readAll() {
+  start();
   paint('tab');
 }
 
 function turnOff() {
   localStorage.removeItem(OPT_IN);
-  state.aux.rtk = null;
+  state.aux.tools = null;
   paint('tab');
 }
 
-function gate(container, tool) {
+function gate(container, tools) {
+  const names = tools.map((tool) => tool.label).join(' and ');
+  const verb = tools.length > 1 ? 'are installed' : 'is installed';
   container.append(node('div', { class: ui.issue(false) }, [
     node('div', { class: ui.issueBody }, [
-      node('div', { class: ui.issueTitle, text: 'rtk is installed, and is not being read' }),
-      node('div', { class: ui.issueDetail, text: `${tool.path} keeps a ledger of what its filters stripped before it reached the model. Reading it runs rtk on this machine, so it stays off until you ask.` }),
+      node('div', { class: ui.issueTitle, text: `${names} ${verb}, and not being read` }),
+      node('div', { class: ui.issueDetail, text: `Each keeps a ledger of what it saved or spent on your behalf. Reading them runs ${names} on this machine, so it stays off until you ask.` }),
     ]),
-    node('button', { class: ui.buttonSmall, text: 'Read rtk stats', onclick: readRtk }),
+    node('button', { class: ui.buttonSmall, text: 'Read tool stats', onclick: readAll }),
   ]));
 }
 
-function failure(container, message) {
-  container.append(node('div', { class: ui.issue(true) }, [
-    node('div', { class: ui.issueBody }, [
-      node('div', { class: ui.issueTitle, text: 'rtk could not be read' }),
-      node('div', { class: ui.issueDetail, text: message }),
+function headline(tool, slot) {
+  if (!slot || slot.running) return 'reading…';
+  if (slot.error) return 'could not be read';
+  return PANELS[tool.id].summary(slot.data);
+}
+
+function subtitle(tool, slot) {
+  const report = slot && slot.data;
+  if (report && report.version) return `${tool.label} ${report.version}`;
+  return tool.label;
+}
+
+function body(tool, slot) {
+  const host = node('div');
+  if (!slot || slot.running) {
+    host.append(node('p', { class: ui.note, text: `Reading the ${tool.label} ledger…` }));
+    return host;
+  }
+  if (slot.error) {
+    host.append(node('div', { class: ui.issue(true) }, [
+      node('div', { class: ui.issueBody }, [
+        node('div', { class: ui.issueTitle, text: `${tool.label} could not be read` }),
+        node('div', { class: ui.issueDetail, text: slot.error }),
+      ]),
+      node('button', { class: ui.buttonSmall, text: 'Try again', onclick: readAll }),
+    ]));
+    return host;
+  }
+  PANELS[tool.id].render(host, slot.data);
+  return host;
+}
+
+function accordion(container, tool, slot) {
+  const open = isOpen(tool.id);
+  const panel = body(tool, slot);
+  panel.hidden = !open;
+
+  const caret = node('span', { class: ui.contextCaret, text: open ? '▾' : '▸' });
+
+  container.append(node('button', {
+    class: ui.contextRowButton,
+    'aria-expanded': String(open),
+    onclick: (event) => {
+      const next = panel.hidden;
+      panel.hidden = !next;
+      caret.textContent = next ? '▾' : '▸';
+      event.currentTarget.setAttribute('aria-expanded', String(next));
+      setOpen(tool.id, next);
+    },
+  }, [
+    node('div', { class: ui.contextMain }, [
+      node('div', { class: ui.contextFile }, [caret, document.createTextNode(subtitle(tool, slot))]),
     ]),
-    node('button', { class: ui.buttonSmall, text: 'Turn off', onclick: turnOff }),
-    node('button', { class: ui.buttonSmall, text: 'Try again', onclick: readRtk }),
+    node('div', { class: ui.contextSize, text: headline(tool, slot) }),
   ]));
+  container.append(panel);
 }
 
 export function renderTools(container) {
-  const tool = installedRtk();
-  if (!tool) return;
+  const tools = installed();
+  if (!tools.length) return;
 
-  if (!state.aux.rtk && localStorage.getItem(OPT_IN) === '1') startRtk({ remember: false });
+  if (!state.aux.tools && localStorage.getItem(OPT_IN) === '1') start({ remember: false });
+  if (!state.aux.tools) return gate(container, tools);
 
-  const report = state.aux.rtk;
-  if (!report) return gate(container, tool);
-  if (report.running) return container.append(node('p', { class: ui.note, text: 'Reading the rtk ledger…' }));
-  if (report.error) return failure(container, report.error);
+  container.append(node('div', { class: ui.listBar }, [
+    node('span', { class: ui.sectionLabelInline, text: 'Companion tools' }),
+    node('span', { class: ui.listSpacer }),
+    node('button', { class: ui.buttonSmall, text: 'Re-read', onclick: readAll }),
+    node('button', { class: ui.buttonSmall, text: 'Turn off', onclick: turnOff }),
+  ]));
 
-  renderRtk(container, report.data, { reread: readRtk, turnOff });
+  for (const tool of tools) accordion(container, tool, state.aux.tools[tool.id]);
 }

package/server.mjs

@@ -16,8 +16,9 @@ import { listStores } from './src/stores.mjs';
 import { forgetPath, rememberPath } from './src/pathcache.mjs';
 import { searchAll } from './src/search.mjs';
 import { verifyPaths } from './src/pathcheck.mjs';
-import { findRtk, rtkReport } from './src/rtk.mjs';
+import { detectTools, toolReport } from './src/tools.mjs';
 import { sessionsWithSummaries, transcriptDir } from './src/sessions.mjs';
+import { readLiveSessions } from './src/liveSessions.mjs';
 import {
   addIndexEntry,
   addIndexEntryPreview,
@@ -129,6 +130,14 @@ function requireStore(id) {
   return store;
 }
 
+const VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version || null;
+  } catch {
+    return null;
+  }
+})();
+
 function storeProjectDir(store) {
   // The global store is the user scope itself, which no project owns.
   if (store.kind === 'global') return null;
@@ -218,7 +227,8 @@ async function handleApi(req, res, url) {
       rootSource: origin.path === ROOT ? origin.source : 'flag',
       rootFile: origin.path === ROOT ? origin.file : null,
       rootWarning: origin.invalid,
-      tools: [findRtk()],
+      version: VERSION,
+      tools: detectTools(),
       stores: listStores(ROOT),
     });
   }
@@ -233,6 +243,18 @@ async function handleApi(req, res, url) {
     return sendJson(res, 200, { stores: issueSweep() });
   }
 
+  // Same "ahead of requireStore" reasoning as the issues sweep above: real
+  // store ids always carry a "kind:" prefix, so "active" can never collide.
+  if (segments.length === 3 && segments[1] === 'stores' && segments[2] === 'active' && req.method === 'GET') {
+    const live = readLiveSessions();
+    const projectStores = listStores(ROOT).filter((s) => s.kind === 'auto' && s.pathExists);
+    const sessions = live.map((session) => ({
+      ...session,
+      storeId: projectStores.find((s) => s.path === session.cwd)?.id ?? null,
+    }));
+    return sendJson(res, 200, { sessions });
+  }
+
   if (segments[1] !== 'stores' || segments.length < 3) {
     return sendJson(res, 404, { error: 'Unknown endpoint' });
   }
@@ -278,11 +300,12 @@ async function handleApi(req, res, url) {
     return sendJson(res, 200, sessionsWithSummaries(slugDir, { projectDir: storeProjectDir(store) }));
   }
 
-  if (action === 'tools/rtk' && req.method === 'GET') {
-    const rtk = findRtk();
-    if (!rtk.found) throw new Error('rtk is not installed, or not on the PATH this server was started with.');
-    const report = await rtkReport(storeProjectDir(store));
-    return sendJson(res, 200, { ...report, path: rtk.path });
+  if (action.startsWith('tools/') && req.method === 'GET') {
+    const target = {
+      projectDir: store.kind === 'global' ? null : storeProjectDir(store),
+      slug: store.kind === 'auto' ? store.slug : null,
+    };
+    return sendJson(res, 200, await toolReport(action.slice('tools/'.length), target));
   }
 
   if (action === 'settings' && req.method === 'GET') {

package/src/ccusage.mjs

@@ -0,0 +1,122 @@
+import os from 'node:os';
+
+import { collector, findBinary, num, parseJson, pct, runBinary, text } from './toolrun.mjs';
+
+const BINARY = 'ccusage';
+const WINDOW_DAYS = 30;
+const SESSION_LIMIT = 8;
+const MODEL_LIMIT = 6;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export const findCcusage = (env = process.env) => ({ id: BINARY, ...findBinary(BINARY, env) });
+
+const runCcusage = (args, options) => runBinary(BINARY, args, options);
+
+const ZERO = { sessions: 0, cost: 0, tokens: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+
+function rowOf(session) {
+  const models = Array.isArray(session.modelBreakdowns) ? session.modelBreakdowns : [];
+  return {
+    id: text(session.sessionId),
+    slug: text(session.projectPath),
+    cost: num(session.totalCost),
+    tokens: num(session.totalTokens),
+    input: num(session.inputTokens),
+    output: num(session.outputTokens),
+    cacheRead: num(session.cacheReadTokens),
+    cacheWrite: num(session.cacheCreationTokens),
+    last: text(session.lastActivity),
+    models: models
+      .filter((model) => model && typeof model === 'object')
+      .map((model) => ({ name: text(model.modelName), cost: num(model.cost), tokens: num(model.outputTokens) }))
+      .filter((model) => model.name),
+  };
+}
+
+const totalsOf = (rows) => rows.reduce((sum, row) => ({
+  sessions: sum.sessions + 1,
+  cost: sum.cost + row.cost,
+  tokens: sum.tokens + row.tokens,
+  input: sum.input + row.input,
+  output: sum.output + row.output,
+  cacheRead: sum.cacheRead + row.cacheRead,
+  cacheWrite: sum.cacheWrite + row.cacheWrite,
+}), ZERO);
+
+function modelMix(rows) {
+  const byName = new Map();
+  for (const row of rows) {
+    for (const model of row.models) {
+      const seen = byName.get(model.name) || { name: model.name, cost: 0, tokens: 0 };
+      seen.cost += model.cost;
+      seen.tokens += model.tokens;
+      byName.set(model.name, seen);
+    }
+  }
+  return [...byName.values()].sort((a, b) => b.cost - a.cost).slice(0, MODEL_LIMIT);
+}
+
+function windowOf(rows, now) {
+  const cutoff = now - (WINDOW_DAYS * DAY_MS);
+  const recent = rows.filter((row) => {
+    const stamp = Date.parse(row.last);
+    return Number.isFinite(stamp) && stamp >= cutoff;
+  });
+  return { days: WINDOW_DAYS, ...totalsOf(recent) };
+}
+
+function machineOf(raw, rows) {
+  const totals = raw && typeof raw.totals === 'object' && raw.totals ? raw.totals : {};
+  return {
+    sessions: rows.length,
+    cost: num(totals.totalCost),
+    tokens: num(totals.totalTokens),
+    input: num(totals.inputTokens),
+    output: num(totals.outputTokens),
+    cacheRead: num(totals.cacheReadTokens),
+    cacheWrite: num(totals.cacheCreationTokens),
+  };
+}
+
+export async function ccusageReport(target = {}, { run = runCcusage, home = os.homedir(), now = Date.now() } = {}) {
+  const { errors, step } = collector();
+
+  const [version, raw] = await Promise.all([
+    step('version', async () => text(await run(['--version'], { cwd: home })).trim().replace(/^ccusage\s+/, '')),
+    step('claude session', async () => parseJson(
+      await run(['claude', 'session', '--json', '--offline'], { cwd: home }),
+      'ccusage claude session',
+    )),
+  ]);
+
+  if (!raw) {
+    return { tool: BINARY, version: version || null, slug: target.slug || null, machine: null, project: null, errors };
+  }
+
+  const rows = (Array.isArray(raw.sessions) ? raw.sessions : [])
+    .filter((session) => session && typeof session === 'object')
+    .map(rowOf)
+    .filter((row) => row.id);
+
+  const machine = machineOf(raw, rows);
+  const mine = target.slug ? rows.filter((row) => row.slug === target.slug) : null;
+  const mineTotals = mine ? totalsOf(mine) : null;
+
+  return {
+    tool: BINARY,
+    version: version || null,
+    slug: target.slug || null,
+    machine: { ...machine, window: windowOf(rows, now) },
+    project: mine ? {
+      ...mineTotals,
+      share: pct(mineTotals.cost, machine.cost),
+      window: windowOf(mine, now),
+      models: modelMix(mine),
+      top: [...mine]
+        .sort((a, b) => b.cost - a.cost)
+        .slice(0, SESSION_LIMIT)
+        .map(({ id, cost, tokens, last }) => ({ id, cost, tokens, last })),
+    } : null,
+    errors,
+  };
+}

package/src/liveSessions.mjs

@@ -0,0 +1,46 @@
+// The live-session registry Claude Code keeps at ~/.claude/sessions/<pid>.json,
+// one file per running `claude` process. This is distinct from the transcript
+// history in sessions.mjs: that reads what happened, this reads what is
+// happening right now.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code !== 'ESRCH';
+  }
+}
+
+/**
+ * Every session whose process is still running, newest-updated first. A file
+ * left behind by a process that has since exited is silently skipped rather
+ * than reported as stale - the registry itself is not this app's to clean up.
+ */
+export function readLiveSessions({ dir = path.join(os.homedir(), '.claude', 'sessions') } = {}) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const sessions = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    let session;
+    try {
+      session = JSON.parse(fs.readFileSync(path.join(dir, entry.name), 'utf8'));
+    } catch {
+      continue;
+    }
+    if (!session || typeof session.pid !== 'number' || !isAlive(session.pid)) continue;
+    sessions.push(session);
+  }
+
+  return sessions.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+}

package/src/rtk.mjs

@@ -1,66 +1,16 @@
-import { execFile } from 'node:child_process';
-import fs from 'node:fs';
 import os from 'node:os';
-import path from 'node:path';
+
+import { collector, findBinary, num, parseJson, pct, runBinary, text, usableDir } from './toolrun.mjs';
 
 const BINARY = 'rtk';
-const TIMEOUT_MS = 15000;
-const MAX_BUFFER = 4 * 1024 * 1024;
 const DISCOVER_DAYS = 30;
 const DISCOVER_LIMIT = 10;
 const MISSED_LIMIT = 12;
 const TREND_DAYS = 30;
 
-const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
-const text = (value) => (typeof value === 'string' ? value : '');
-const pct = (part, whole) => (whole > 0 ? (part / whole) * 100 : 0);
-
-function candidateNames(env) {
-  if (process.platform !== 'win32') return [BINARY];
-  const exts = text(env.PATHEXT || '.EXE').split(';').filter(Boolean);
-  return exts.map((ext) => BINARY + ext.toLowerCase());
-}
-
-export function findRtk(env = process.env) {
-  const dirs = text(env.PATH).split(path.delimiter).filter(Boolean);
-  const names = candidateNames(env);
-  for (const dir of dirs) {
-    for (const name of names) {
-      const candidate = path.join(dir, name);
-      try {
-        if (!fs.statSync(candidate).isFile()) continue;
-        fs.accessSync(candidate, fs.constants.X_OK);
-        return { id: BINARY, found: true, path: candidate };
-      } catch {
-        continue;
-      }
-    }
-  }
-  return { id: BINARY, found: false, path: null };
-}
-
-function runRtk(args, { cwd, timeout = TIMEOUT_MS } = {}) {
-  return new Promise((resolve, reject) => {
-    const options = { cwd, timeout, maxBuffer: MAX_BUFFER, windowsHide: true, encoding: 'utf8' };
-    execFile(BINARY, args, options, (err, stdout, stderr) => {
-      if (!err) return resolve(stdout);
-      if (err.code === 'ENOENT') return reject(new Error('rtk is not on this process PATH'));
-      if (err.killed) return reject(new Error(`rtk ${args[0]} was still running after ${timeout}ms and was stopped`));
-      const detail = text(stderr || stdout).trim().split('\n')[0];
-      return reject(new Error(detail ? `rtk ${args[0]} failed: ${detail}` : `rtk ${args[0]} exited ${err.code}`));
-    });
-  });
-}
+export const findRtk = (env = process.env) => ({ id: BINARY, ...findBinary(BINARY, env) });
 
-function parseJson(raw, label) {
-  try {
-    const value = JSON.parse(raw);
-    if (!value || typeof value !== 'object') throw new Error('not an object');
-    return value;
-  } catch {
-    throw new Error(`rtk ${label} did not answer with JSON`);
-  }
-}
+const runRtk = (args, options) => runBinary(BINARY, args, options);
 
 function summaryOf(raw) {
   const summary = raw && typeof raw.summary === 'object' && raw.summary ? raw.summary : {};
@@ -133,35 +83,17 @@ function discoverOf(raw) {
   };
 }
 
-function usableDir(dir) {
-  if (!dir) return null;
-  try {
-    return fs.statSync(dir).isDirectory() ? dir : null;
-  } catch {
-    return null;
-  }
-}
-
-export async function rtkReport(projectDir, { run = runRtk, home = os.homedir() } = {}) {
-  const errors = [];
-  const step = async (label, work) => {
-    try {
-      return await work();
-    } catch (err) {
-      errors.push({ step: label, message: err.message });
-      return null;
-    }
-  };
-
-  const dir = usableDir(projectDir);
+export async function rtkReport(target = {}, { run = runRtk, home = os.homedir() } = {}) {
+  const { errors, step } = collector();
+  const dir = usableDir(target.projectDir);
 
   const [version, machine, project, discover] = await Promise.all([
     step('version', async () => text(await run(['--version'], { cwd: home })).trim().replace(/^rtk\s+/, '')),
-    step('gain', async () => parseJson(await run(['gain', '-a', '--format', 'json'], { cwd: home }), 'gain')),
-    dir ? step('gain --project', async () => parseJson(await run(['gain', '-p', '--format', 'json'], { cwd: dir }), 'gain --project')) : null,
+    step('gain', async () => parseJson(await run(['gain', '-a', '--format', 'json'], { cwd: home }), 'rtk gain')),
+    dir ? step('gain --project', async () => parseJson(await run(['gain', '-p', '--format', 'json'], { cwd: dir }), 'rtk gain --project')) : null,
     dir ? step('discover', async () => parseJson(
       await run(['discover', '--format', 'json', '-s', String(DISCOVER_DAYS), '-l', String(DISCOVER_LIMIT)], { cwd: dir }),
-      'discover',
+      'rtk discover',
     )) : null,
   ]);