@chemx/starter-kit 26.10.8-344 → 26.10.10-75

package/cli/forge/fixtures/heal/cli/project-detector.js.txt

@@ -0,0 +1,364 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const loadProjectConfig = (cwd = process.cwd()) => {
+  const cfgPath = path.resolve(cwd, '.chemx', 'config.json');
+  const hasConfig = fs.existsSync(cfgPath);
+  if (!hasConfig) return {};
+  try {
+    return JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+};
+
+export const normalizeFramework = (val) => {
+  if (!val) return null;
+  const str = String(val).toLowerCase().trim();
+  const isReact = ['react', 'tsx', 'jsx'].includes(str);
+  if (isReact) return 'react';
+  const isVue = ['vue', 'vue3', 'nuxt'].includes(str);
+  if (isVue) return 'vue';
+  const isSvelte = ['svelte', 'svelte5', 'kit'].includes(str);
+  if (isSvelte) return 'svelte';
+  return null;
+};
+
+export const resolveFramework = ({ frameworkArg = null, cwd = process.cwd() } = {}) => {
+  // 1. Explicit flag
+  const explicit = normalizeFramework(frameworkArg);
+  if (explicit) return explicit;
+
+  // 2. Project config in .chemx/config.json
+  const config = loadProjectConfig(cwd);
+  const hasConfiguredFramework = Boolean(config.framework);
+  if (hasConfiguredFramework) {
+    const fromConfig = normalizeFramework(config.framework);
+    if (fromConfig) return fromConfig;
+  }
+
+  // 3. Auto-detect from package.json dependencies
+  const pkgPath = path.resolve(cwd, 'package.json');
+  const hasPackageJson = fs.existsSync(pkgPath);
+  if (hasPackageJson) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+
+      const usesVue = Boolean(deps.vue || deps.nuxt || deps['@nuxt/kit']);
+      if (usesVue) return 'vue';
+      const usesSvelte = Boolean(deps.svelte || deps['@sveltejs/kit']);
+      if (usesSvelte) return 'svelte';
+      const usesReact = Boolean(deps.react || deps.next);
+      if (usesReact) return 'react';
+    } catch {
+      // chemx-allow: best-effort an unreadable package.json falls through to the hard default framework
+    }
+  }
+
+  // 4. Hard default
+  return 'react';
+};
+
+export const detectFramework = (cwd = process.cwd()) => {
+  return resolveFramework({ cwd });
+};
+
+export const detectTestRunner = (startDir = process.cwd()) => {
+  let curr = path.resolve(startDir);
+  for (;;) {
+    const hasParentDir = Boolean(curr && curr !== path.dirname(curr));
+    if (!hasParentDir) break;
+    const pkgPath = path.join(curr, 'package.json');
+    const hasPackageJson = fs.existsSync(pkgPath);
+    if (hasPackageJson) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+        const usesVitest = Boolean(deps.vitest || (pkg.scripts?.test && pkg.scripts.test.includes('vitest')));
+        if (usesVitest) return 'vitest';
+        const usesJest = Boolean(deps.jest || (pkg.scripts?.test && pkg.scripts.test.includes('jest')));
+        if (usesJest) return 'jest';
+      } catch {
+        // chemx-allow: best-effort an unreadable package.json falls back to the node:test runner
+      }
+      break;
+    }
+    curr = path.dirname(curr);
+  }
+
+  return 'node:test';
+};
+
+const ATOMS_PACKAGES = ['@chemx/x-atoms', '@chemx/atoms', 'x-atoms', '@chem-x/x-atoms'];
+const PALETTE_PACKAGES = ['@chemx/o-command-palette', '@chemx/command-palette', 'o-command-palette', '@chem-x/o-command-palette'];
+
+const resolveLocalAtomsCandidate = (cwd) => {
+  const componentAtomsPath = path.resolve(cwd, 'src/components/atoms');
+  const hasComponentAtoms = fs.existsSync(componentAtomsPath);
+  if (hasComponentAtoms) {
+    return '@/components/atoms';
+  }
+
+  const directAtomsPath = path.resolve(cwd, 'src/atoms');
+  const hasDirectAtoms = fs.existsSync(directAtomsPath);
+  if (hasDirectAtoms) {
+    return '@/atoms';
+  }
+
+  return null;
+};
+
+export const detectInstalledFamily = (cwd = process.cwd()) => {
+  const pkgPath = path.resolve(cwd, 'package.json');
+  const hasPackageJson = fs.existsSync(pkgPath);
+  if (!hasPackageJson) {
+    return { hasAtoms: false, atomsPackage: null, hasPalette: false, palettePackage: null };
+  }
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+
+    const atomsCandidate = ATOMS_PACKAGES.find((name) => Boolean(deps[name]));
+    const paletteCandidate = PALETTE_PACKAGES.find((name) => Boolean(deps[name]));
+
+    const localAtomsCandidate = resolveLocalAtomsCandidate(cwd);
+
+    const resolvedAtomsPackage = atomsCandidate || localAtomsCandidate || null;
+
+    return {
+      hasAtoms: Boolean(resolvedAtomsPackage),
+      atomsPackage: resolvedAtomsPackage,
+      hasPalette: Boolean(paletteCandidate),
+      palettePackage: paletteCandidate || null
+    };
+  } catch {
+    return { hasAtoms: false, atomsPackage: null, hasPalette: false, palettePackage: null };
+  }
+};
+
+const TIER_DIRECTORY_MAPS = {
+  hook: [
+    'src/hooks',
+    'src/composables',
+    'composables',
+    'hooks',
+    'src/lib/hooks',
+    'src'
+  ],
+  view: [
+    'src/views',
+    'src/pages',
+    'src/routes',
+    'src/app',
+    'app',
+    'pages',
+    'views',
+    'src'
+  ],
+  molecule: [
+    'src/components/molecules',
+    'src/components',
+    'src/lib/components',
+    'components',
+    'src'
+  ],
+  atom: [
+    'src/components/atoms',
+    'src/components',
+    'src/lib/components',
+    'components',
+    'src'
+  ],
+  organism: [
+    'src/components/organisms',
+    'src/components',
+    'src/lib/components',
+    'components',
+    'src'
+  ],
+  template: [
+    'src/components/templates',
+    'src/components',
+    'src/lib/components',
+    'components',
+    'src'
+  ]
+};
+
+export const PRESET_DIRECTORY_MAPS = {
+  src: {
+    molecule: 'src/components/molecules',
+    atom: 'src/components/atoms',
+    organism: 'src/components/organisms',
+    template: 'src/components/templates',
+    hook: 'src/hooks',
+    view: 'src/views',
+    service: 'src/services',
+    route: 'src/routes',
+    store: 'src/stores',
+    repo: 'src/repos',
+    util: 'src/utils',
+    spec: 'test/unit'
+  },
+  app: {
+    molecule: 'app/components/molecules',
+    atom: 'app/components/atoms',
+    organism: 'app/components/organisms',
+    template: 'app/components/templates',
+    hook: 'app/composables',
+    view: 'app/pages',
+    service: 'app/services',
+    route: 'server/api',
+    store: 'app/stores',
+    repo: 'server/repos',
+    util: 'app/utils',
+    spec: 'test/unit'
+  },
+  root: {
+    molecule: 'components/molecules',
+    atom: 'components/atoms',
+    organism: 'components/organisms',
+    template: 'components/templates',
+    hook: 'hooks',
+    view: 'pages',
+    service: 'services',
+    route: 'routes',
+    store: 'stores',
+    repo: 'repos',
+    util: 'utils',
+    spec: 'test'
+  },
+  lib: {
+    molecule: 'src/lib/components/molecules',
+    atom: 'src/lib/components/atoms',
+    organism: 'src/lib/components/organisms',
+    template: 'src/lib/components/templates',
+    hook: 'src/lib/hooks',
+    view: 'src/routes',
+    service: 'src/lib/services',
+    route: 'src/routes/api',
+    store: 'src/lib/stores',
+    repo: 'src/lib/repos',
+    util: 'src/lib/utils',
+    spec: 'test'
+  }
+};
+
+export const detectTierBaseDir = (tier, cwd = process.cwd(), presetOverride = null) => {
+  const config = loadProjectConfig(cwd);
+  const activePreset = presetOverride || config.preset;
+
+  const hasPresetDir = Boolean(activePreset && PRESET_DIRECTORY_MAPS[activePreset]?.[tier]);
+  if (hasPresetDir) {
+    return PRESET_DIRECTORY_MAPS[activePreset][tier];
+  }
+
+  const hasConfiguredDir = Boolean(config.dirs && config.dirs[tier]);
+  if (hasConfiguredDir) {
+    const configuredPath = path.resolve(cwd, config.dirs[tier]);
+    const isConfiguredDirPresent = fs.existsSync(configuredPath);
+    if (isConfiguredDirPresent) return config.dirs[tier];
+  }
+
+  const candidates = TIER_DIRECTORY_MAPS[tier] || TIER_DIRECTORY_MAPS.molecule;
+  for (const c of candidates) {
+    const isCandidatePresent = fs.existsSync(path.resolve(cwd, c));
+    if (isCandidatePresent) return c;
+  }
+
+  const hasAppComponents = fs.existsSync(path.resolve(cwd, 'app/components'));
+  if (hasAppComponents) {
+    return PRESET_DIRECTORY_MAPS.app[tier] || 'app/components';
+  }
+
+  return PRESET_DIRECTORY_MAPS.src[tier] || '.';
+};
+
+export const detectJigBaseDir = (kind, { cwd = process.cwd(), preset = null } = {}) => {
+  const config = loadProjectConfig(cwd);
+  const activePreset = preset || config.preset;
+
+  const hasPresetDir = Boolean(activePreset && PRESET_DIRECTORY_MAPS[activePreset]?.[kind]);
+  if (hasPresetDir) {
+    return PRESET_DIRECTORY_MAPS[activePreset][kind];
+  }
+
+  const hasConfiguredDir = Boolean(config.dirs && config.dirs[kind]);
+  if (hasConfiguredDir) {
+    const configuredPath = path.resolve(cwd, config.dirs[kind]);
+    const isConfiguredDirPresent = fs.existsSync(configuredPath);
+    if (isConfiguredDirPresent) return config.dirs[kind];
+  }
+
+  const defaultDirMap = {
+    service: ['src/services', 'app/services', 'services', 'src/lib/services'],
+    route: ['src/routes', 'server/api', 'routes', 'src/routes/api'],
+    store: ['src/stores', 'app/stores', 'stores', 'src/lib/stores'],
+    repo: ['src/repos', 'server/repos', 'repos', 'src/lib/repos'],
+    util: ['src/utils', 'app/utils', 'utils', 'src/lib/utils'],
+    spec: ['test/unit', 'tests/unit', 'test', 'tests']
+  };
+
+  const candidates = defaultDirMap[kind] || [`src/${kind}s`];
+  for (const c of candidates) {
+    const isCandidatePresent = fs.existsSync(path.resolve(cwd, c));
+    if (isCandidatePresent) return c;
+  }
+
+  const hasAppDir = fs.existsSync(path.resolve(cwd, 'app'));
+  if (hasAppDir) {
+    return PRESET_DIRECTORY_MAPS.app[kind] || `app/${kind}s`;
+  }
+
+  return PRESET_DIRECTORY_MAPS.src[kind] || `src/${kind}s`;
+};
+
+const TAILWIND_PACKAGES = [
+  'tailwindcss',
+  '@tailwindcss/vite',
+  '@tailwindcss/postcss',
+  '@tailwindcss/cli'
+];
+
+const SCSS_PACKAGES = ['sass', 'sass-embedded'];
+
+const TAILWIND_CONFIG_NAMES = [
+  'tailwind.config.js',
+  'tailwind.config.ts',
+  'tailwind.config.cjs',
+  'tailwind.config.mjs'
+];
+
+export const detectStylingStack = (cwd = process.cwd()) => {
+  const pkgPath = path.resolve(cwd, 'package.json');
+  let hasTailwind = false;
+  let hasScss = false;
+
+  const hasPackageJson = fs.existsSync(pkgPath);
+  if (hasPackageJson) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+
+      hasTailwind = TAILWIND_PACKAGES.some((pkgName) => Boolean(deps[pkgName]));
+      hasScss = SCSS_PACKAGES.some((pkgName) => Boolean(deps[pkgName]));
+    } catch {
+      // chemx-allow: best-effort an unreadable package.json leaves styling detection to the tailwind config probe
+    }
+  }
+
+  if (!hasTailwind) {
+    hasTailwind = TAILWIND_CONFIG_NAMES.some((cfg) => fs.existsSync(path.resolve(cwd, cfg)));
+  }
+
+  let styleFlavor = 'css';
+  if (hasTailwind) {
+    styleFlavor = 'tailwind';
+  } else if (hasScss) {
+    styleFlavor = 'scss';
+  }
+
+  return { hasTailwind, hasScss, styleFlavor };
+};

package/cli/forge/fixtures/heal/cli/project-markers.js.txt

@@ -0,0 +1,42 @@
+/**
+ * Chemical X Protocol: where a walk for a project root may stop (#2570, #2581).
+ * A project marker (.git, package.json, .chemxrc) ends an upward search. The filesystem root and
+ * the OS temp dir (with its ancestors) are never a project root: a stray /tmp/.chemx or /.chemx
+ * must not capture a temp project that has no marker of its own.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const PROJECT_MARKERS = Object.freeze(['.git', 'package.json', '.chemxrc']);
+
+const realDir = (dir) => {
+  try {
+    return fs.realpathSync(dir);
+  } catch {
+    return path.resolve(dir);
+  }
+};
+
+export const hasProjectMarker = (dir) => PROJECT_MARKERS.some((marker) => fs.existsSync(path.join(dir, marker)));
+
+/** True for the filesystem root, the OS temp dir and every ancestor of the temp dir. */
+export const isForbiddenRoot = (dir) => {
+  const resolved = realDir(dir);
+  const isFsRoot = path.dirname(resolved) === resolved;
+  const rel = path.relative(resolved, realDir(os.tmpdir()));
+  const holdsTempDir = !rel.startsWith('..') && !path.isAbsolute(rel);
+  return isFsRoot || holdsTempDir;
+};
+
+/** True when dir is the OS temp dir or inside it. */
+export const isInsideTempDir = (dir) => {
+  const rel = path.relative(realDir(os.tmpdir()), realDir(dir));
+  return !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+
+/** Text for a refused root, or null when dir may hold a .chemx. */
+export const forbiddenRootRefusal = (dir) => {
+  const isForbidden = isForbiddenRoot(dir);
+  return isForbidden ? `chemx will not use ${dir} as a project root (it is the OS temp dir, an ancestor of it, or the filesystem root); run from a project directory` : null;
+};

package/cli/forge/fixtures/heal/cli/team/coordination-root.js.txt

@@ -0,0 +1,161 @@
+/**
+ * Chemical X Protocol: the coordination root (#2488).
+ * Team tables (tasks, comments, feed, DMs, agents, leases, lock queue, projects) belong in one db per
+ * monorepo, <root>/.chemx/index.db, where root is, from the start directory:
+ *   1. the outermost git superproject, climbing only through registered submodules (.gitmodules
+ *      path or a .git/modules pointer) and from a linked worktree to its main checkout; else
+ *   2. the outermost workspace root (pnpm-workspace.yaml or package.json workspaces) inside the
+ *      nearest checkout; else
+ *   3. the package itself: the nearest checkout, else the first dir on the way up with a project
+ *      marker (.git, package.json, .chemxrc) or an existing .chemx/index.db (the dir the code index
+ *      would use too), else the start dir.
+ * No walk climbs into the OS temp dir, its ancestors or the filesystem root, and a root that lands
+ * there is refused (#2570): a stray /tmp/.chemx never captures a temp project.
+ * CHEMX_PROJECT_ROOT and an MCP projectRoot only choose the start directory; they never move the
+ * root. The code index keeps resolving per project (search-schema.js); package scoping of the
+ * index is part B of #2488.
+ * A spec process (node --test sets NODE_TEST_CONTEXT) is refused any root outside the OS temp dir,
+ * so specs never resolve a real db.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { readWorkspaceGlobs } from '../workspace.js';
+import { hasProjectMarker, isForbiddenRoot, forbiddenRootRefusal } from '../project-markers.js';
+
+const realDir = (dir) => {
+  try {
+    return fs.realpathSync(dir);
+  } catch {
+    return path.resolve(dir);
+  }
+};
+
+export const ancestorsOf = (startDir) => {
+  const dirs = [];
+  let dir = path.resolve(startDir);
+  while (true) {
+    dirs.push(dir);
+    const parent = path.dirname(dir);
+    const isTop = parent === dir;
+    if (isTop) return dirs;
+    dir = parent;
+  }
+};
+
+export const isInsideOrEqual = (outer, inner) => {
+  const rel = path.relative(outer, inner);
+  const isOutside = rel.startsWith('..') || path.isAbsolute(rel);
+  return !isOutside;
+};
+
+// The ancestors a root search may visit: never the temp dir, its ancestors or the filesystem root.
+const searchableAncestors = (startDir) => ancestorsOf(startDir).filter((dir) => !isForbiddenRoot(dir));
+
+const hasGit = (dir) => fs.existsSync(path.join(dir, '.git'));
+const nearestCheckout = (startDir) => searchableAncestors(startDir).find(hasGit) ?? null;
+
+// The gitdir a `.git` FILE points at (submodule or linked worktree), or null for a real .git dir.
+const readGitPointer = (dir) => {
+  try {
+    const gitPath = path.join(dir, '.git');
+    const isPointerFile = fs.statSync(gitPath).isFile();
+    const match = isPointerFile ? /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(gitPath, 'utf-8')) : null;
+    return match ? path.resolve(dir, match[1].trim()) : null;
+  } catch {
+    return null;
+  }
+};
+
+export const listedSubmodulePaths = (dir) => {
+  try {
+    const text = fs.readFileSync(path.join(dir, '.gitmodules'), 'utf-8');
+    return [...text.matchAll(/^\s*path\s*=\s*(.+?)\s*$/gm)].map((match) => match[1].replace(/\\/g, '/'));
+  } catch {
+    return [];
+  }
+};
+
+const WORKTREE_POINTER = /^(.*)[\\/]\.git[\\/]worktrees[\\/][^\\/]+$/;
+
+// A linked worktree coordinates with its main checkout: <main>/.git/worktrees/<name> -> <main>.
+const worktreeMain = (checkout) => {
+  const pointer = readGitPointer(checkout) || '';
+  const match = WORKTREE_POINTER.exec(pointer);
+  return match ? match[1] : null;
+};
+
+const toPosix = (p) => p.split(path.sep).join('/');
+
+// The checkout that registers `checkout` as a submodule, or null. An unrelated repo above (a
+// dotfiles repo in $HOME) is never a superproject.
+const superprojectOf = (checkout) => {
+  const parent = path.dirname(checkout);
+  const outer = parent === checkout ? null : nearestCheckout(parent);
+  if (!outer) return null;
+  const isListed = listedSubmodulePaths(outer).includes(toPosix(path.relative(outer, checkout)));
+  const pointer = readGitPointer(checkout) || '';
+  const isAbsorbed = pointer.startsWith(path.join(outer, '.git', 'modules') + path.sep);
+  const isSubmodule = isListed || isAbsorbed;
+  return isSubmodule ? outer : null;
+};
+
+const outermostSuperproject = (checkout) => {
+  let current = worktreeMain(checkout) ?? checkout;
+  let outer = superprojectOf(current);
+  while (outer) {
+    current = outer;
+    outer = superprojectOf(current);
+  }
+  return current;
+};
+
+const isWorkspaceRoot = (dir) => Boolean(readWorkspaceGlobs(dir));
+
+// Outermost workspace root among the ancestors, never above the nearest checkout's boundary.
+const outermostWorkspace = (startDir, boundary) => {
+  const candidates = searchableAncestors(startDir).filter((dir) => !boundary || isInsideOrEqual(boundary, dir));
+  return candidates.filter(isWorkspaceRoot).pop() ?? null;
+};
+
+const isProjectStop = (dir) => hasProjectMarker(dir) || fs.existsSync(path.join(dir, '.chemx', 'index.db'));
+const firstMarker = (startDir) => searchableAncestors(startDir).find(isProjectStop) ?? null;
+
+const locateRoot = (startDir) => {
+  const checkout = nearestCheckout(startDir);
+  const superproject = checkout ? outermostSuperproject(checkout) : null;
+  const hasSuperproject = Boolean(superproject) && superproject !== checkout;
+  if (hasSuperproject) return { root: superproject, mode: 'superproject' };
+  const workspace = outermostWorkspace(startDir, superproject);
+  if (workspace) return { root: workspace, mode: 'workspace' };
+  const own = superproject || firstMarker(startDir) || path.resolve(startDir);
+  return { root: own, mode: 'standalone' };
+};
+
+export const isSpecProcess = (env = process.env) => Boolean(env.NODE_TEST_CONTEXT);
+
+const specRefusal = (root, env) => {
+  const isSpec = isSpecProcess(env);
+  const isTemp = isInsideOrEqual(realDir(os.tmpdir()), realDir(root));
+  const isRefused = isSpec && !isTemp;
+  return isRefused ? `spec process refused the coordination db under ${root}: specs must build their project in a temp dir` : null;
+};
+
+/**
+ * Why no team db may be opened at root, or null. Every opener of team rows asks this (#2581):
+ * the temp dir and the filesystem root are never a root, and a spec process (node --test) never
+ * opens a db outside the OS temp dir, whichever path it took to get there.
+ */
+export const teamDbRefusal = (root, env = process.env) => forbiddenRootRefusal(root) || specRefusal(root, env);
+
+/**
+ * @param {string} startDir Where the caller runs (cwd, MCP projectRoot, hook root).
+ * @param {{ env?: object }} [options]
+ * @returns {{ root: string, mode: 'superproject'|'workspace'|'standalone', refused: string|null }}
+ */
+export const resolveCoordinationRoot = (startDir = process.cwd(), options = {}) => {
+  const env = options.env || process.env;
+  const located = locateRoot(realDir(startDir));
+  const root = realDir(located.root);
+  return { root, mode: located.mode, refused: teamDbRefusal(root, env) };
+};

package/cli/forge/fixtures/heal/cli/team/usage-reader.js.txt

@@ -0,0 +1,109 @@
+/**
+ * Chemical X Protocol: read a Claude Code workflow run from disk and measure each agent's usage (#2497).
+ * A run lives at ~/.claude/projects/<project>/<session>/subagents/workflows/<wf_id>/ with a journal.jsonl,
+ * agent-<id>.jsonl transcripts and agent-<id>.meta.json files. Guarantee: tokens are exactly what the
+ * transcripts record, counted once per message.id. Not guaranteed: transcripts of agents the host never
+ * wrote (killed before the first reply) are absent, so they are absent here too.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { parseTranscript } from './usage-transcript.js';
+
+const AGENT_FILE_RE = /^agent-(.+)\.jsonl$/;
+
+const isDir = (p) => {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+const listDirs = (p) => {
+  try {
+    return fs.readdirSync(p).map((name) => path.join(p, name)).filter(isDir);
+  } catch {
+    return [];
+  }
+};
+
+/** Find a run dir from a path or a wf_ id. projectsRoot defaults to ~/.claude/projects. */
+export const findRunDir = (idOrDir, projectsRoot = path.join(os.homedir(), '.claude', 'projects')) => {
+  const given = path.resolve(String(idOrDir || ''));
+  const isGivenDir = Boolean(idOrDir) && isDir(given);
+  if (isGivenDir) return given;
+  for (const project of listDirs(projectsRoot)) {
+    for (const session of listDirs(project)) {
+      const candidate = path.join(session, 'subagents', 'workflows', String(idOrDir));
+      if (isDir(candidate)) return candidate;
+    }
+  }
+  return null;
+};
+
+const readJsonLines = (file) => {
+  let text = '';
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    return [];
+  }
+  return text.split('\n').filter(Boolean).map((line) => {
+    try {
+      return JSON.parse(line);
+    } catch {
+      return null;
+    }
+  }).filter(Boolean);
+};
+
+const readJson = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+};
+
+const readJournalLabels = (dir) => {
+  const labels = new Map();
+  for (const event of readJsonLines(path.join(dir, 'journal.jsonl'))) {
+    const isStart = event.type === 'started' && Boolean(event.agentId);
+    if (isStart) labels.set(event.agentId, { label: event.label || '', phase: event.phase || '' });
+  }
+  return labels;
+};
+
+const primaryModel = (buckets) => {
+  const ranked = Object.entries(buckets).sort((a, b) => b[1].calls - a[1].calls);
+  return ranked.length ? ranked[0][0] : 'unknown';
+};
+
+const readAgent = (dir, file, labels) => {
+  const agentId = AGENT_FILE_RE.exec(file)[1];
+  const parsed = parseTranscript(fs.readFileSync(path.join(dir, file), 'utf8'));
+  const meta = readJson(path.join(dir, `agent-${agentId}.meta.json`));
+  const journal = labels.get(agentId) || {};
+  return {
+    agentId,
+    handle: parsed.handle,
+    label: journal.label || meta.description || '',
+    phase: journal.phase || meta.workflowPhase || '',
+    model: primaryModel(parsed.buckets),
+    requestedModel: meta.model || null,
+    ...parsed
+  };
+};
+
+/** Read every agent of a run. Returns null when the run cannot be found. */
+export const readRun = (idOrDir, projectsRoot) => {
+  const dir = findRunDir(idOrDir, projectsRoot);
+  if (!dir) return null;
+  const labels = readJournalLabels(dir);
+  const files = fs.readdirSync(dir).filter((f) => AGENT_FILE_RE.test(f)).sort();
+  const agents = files.map((file) => readAgent(dir, file, labels));
+  const launched = [...labels.keys()];
+  const missing = launched.filter((id) => !agents.some((a) => a.agentId === id));
+  return { runId: path.basename(dir), dir, agents, journalAgents: launched.length, missingTranscripts: missing };
+};