amicus 3.0.0 → 3.1.1

package/src/utils/model-descriptor.js

@@ -0,0 +1,72 @@
+/**
+ * Model-descriptor grammar + RouteResult factories (#61).
+ * Pure string classification — no I/O, no provider lookups. The resolver
+ * (gateway-router.js) consumes Descriptors and returns RouteResults.
+ */
+'use strict';
+
+const GATEWAY_MODES = ['auto', 'direct', 'openrouter'];
+const OR_PREFIX = 'openrouter/';
+
+/**
+ * Classify a raw model string into a normalized descriptor.
+ * Grammar:
+ *   - `openrouter/<vendor>/<model>`  -> openrouter-literal (explicit force-OR)
+ *   - `<vendor>/<model...>`          -> canonical (policy-routed)
+ *   - known no-slash alias            -> alias (resolution deferred to caller)
+ *   - anything else                   -> invalid (incl. unknown no-slash token)
+ * @param {string} raw
+ * @param {{aliases: Object<string,string>}} ctx
+ * @returns {{raw:string, kind:string, vendor?:string, model?:string, isExplicitOpenRouter:boolean, error?:string}}
+ */
+function parseDescriptor(raw, ctx = {}) {
+  const aliases = ctx.aliases || {};
+  const trimmed = typeof raw === 'string' ? raw.trim() : '';
+  if (!trimmed) {
+    return { raw, kind: 'invalid', isExplicitOpenRouter: false, error: 'Empty model identifier' };
+  }
+  if (trimmed.startsWith(OR_PREFIX)) {
+    const rest = trimmed.slice(OR_PREFIX.length);
+    const parts = rest.split('/');
+    if (parts.length < 2 || !parts[0] || !parts.slice(1).join('/')) {
+      return { raw: trimmed, kind: 'invalid', isExplicitOpenRouter: true,
+        error: `Malformed OpenRouter model id '${trimmed}' (expected openrouter/vendor/model)` };
+    }
+    return { raw: trimmed, kind: 'openrouter-literal', vendor: parts[0],
+      model: parts.slice(1).join('/'), isExplicitOpenRouter: true };
+  }
+  if (trimmed.includes('/')) {
+    const parts = trimmed.split('/');
+    if (parts.length < 2 || !parts[0] || !parts.slice(1).join('/')) {
+      return { raw: trimmed, kind: 'invalid', isExplicitOpenRouter: false,
+        error: `Malformed model id '${trimmed}' (expected vendor/model)` };
+    }
+    return { raw: trimmed, kind: 'canonical', vendor: parts[0],
+      model: parts.slice(1).join('/'), isExplicitOpenRouter: false };
+  }
+  if (Object.prototype.hasOwnProperty.call(aliases, trimmed)) {
+    return { raw: trimmed, kind: 'alias', isExplicitOpenRouter: false };
+  }
+  return { raw: trimmed, kind: 'invalid', isExplicitOpenRouter: false,
+    error: `Unknown model alias '${trimmed}'. Run 'amicus setup' to configure aliases, or use a vendor/model id.` };
+}
+
+/** @returns {{kind:'resolved', model:string, gateway:string, executableId:string, provenance:object, notice?:string}} */
+function resolved({ model, gateway, executableId, provenance, notice }) {
+  const out = { kind: 'resolved', model, gateway, executableId, provenance: provenance || {} };
+  if (notice) { out.notice = notice; }
+  return out;
+}
+
+/** @returns {{kind:'selection_required', requested:string, suggestions:Array}} */
+function selectionRequired({ requested, suggestions }) {
+  return { kind: 'selection_required', requested, suggestions: suggestions || [] };
+}
+
+/** @returns {{kind:'error', type:'model_route_error', ...}} */
+function routeError({ field, requested, reason, preferredGateway, suggestions }) {
+  return { kind: 'error', type: 'model_route_error', field: field || 'model',
+    requested, reason, preferredGateway, suggestions: suggestions || [] };
+}
+
+module.exports = { GATEWAY_MODES, parseDescriptor, resolved, selectionRequired, routeError };

package/src/utils/model-fetcher.js

@@ -7,22 +7,22 @@
 
 const https = require('https');
 
-/** Hardcoded Anthropic models (no public listing endpoint) */
+/**
+ * Hardcoded Anthropic models (no public listing endpoint). This is the
+ * DIRECT-API floor only — Fable is OpenRouter-only (see curated-models.js
+ * DIVERGENT_VENDORS / CARDLESS 'fable' entry, which has no `anthropic` route)
+ * and must never appear here: classifyModel() returns 'valid' on a floor HIT
+ * before it ever checks `authoritative`, so listing an OR-only model here
+ * would mislabel a direct-API request for it as valid.
+ */
 const ANTHROPIC_MODELS = [
-  { id: 'anthropic/claude-opus-4-6', name: 'Claude Opus 4.6', contextLength: null, pricing: null },
-  { id: 'anthropic/claude-sonnet-4-6', name: 'Claude Sonnet 4.6', contextLength: null, pricing: null },
+  { id: 'anthropic/claude-opus-4-8', name: 'Claude Opus 4.8', contextLength: null, pricing: null },
+  { id: 'anthropic/claude-sonnet-5', name: 'Claude Sonnet 5', contextLength: null, pricing: null },
   { id: 'anthropic/claude-haiku-4-5', name: 'Claude Haiku 4.5', contextLength: null, pricing: null },
-  { id: 'anthropic/claude-sonnet-4-5', name: 'Claude Sonnet 4.5', contextLength: null, pricing: null },
-  { id: 'anthropic/claude-3-5-haiku', name: 'Claude 3.5 Haiku', contextLength: null, pricing: null }
+  { id: 'anthropic/claude-sonnet-4-6', name: 'Claude Sonnet 4.6', contextLength: null, pricing: null }
 ];
 
-const PROVIDER_FAMILY_NAMES = {
-  openrouter: 'OpenRouter',
-  google: 'Google',
-  openai: 'OpenAI',
-  anthropic: 'Anthropic',
-  deepseek: 'DeepSeek'
-};
+const { PROVIDER_FAMILY_NAMES } = require('./provider-registry');
 
 /** Provider API configs for fetching model lists */
 const PROVIDER_FETCH_CONFIG = {
@@ -82,7 +82,20 @@ const PROVIDER_FETCH_CONFIG = {
         pricing: null
       }));
     }
-  }
+  },
+  anthropic: {
+    url: 'https://api.anthropic.com/v1/models',
+    authHeader: (key) => ({ 'x-api-key': key, 'anthropic-version': '2023-06-01' }),
+    normalize: (body) => {
+      const data = JSON.parse(body);
+      return (data.data || []).map(m => ({
+        id: `anthropic/${m.id}`,
+        name: m.display_name || m.id,
+        contextLength: null,
+        pricing: null,
+      }));
+    },
+  },
 };
 
 const FETCH_TIMEOUT_MS = 5000;
@@ -95,7 +108,14 @@ const FETCH_TIMEOUT_MS = 5000;
  */
 function fetchModelsFromProvider(provider, key) {
   if (provider === 'anthropic') {
-    return Promise.resolve(ANTHROPIC_MODELS);
+    // No key -> hardcoded floor, no network. With a key -> try live, fall back to floor.
+    // Floor-fallback rows are tagged authoritative:false (#61 4.3) so classifyModel
+    // never hard-blocks a miss against a stale/hardcoded list -- it returns
+    // 'unknown' instead. Rows from a successful live fetch are NOT tagged (they
+    // are authoritative). Map to new objects; never mutate ANTHROPIC_MODELS in place.
+    if (!key) { return Promise.resolve(ANTHROPIC_MODELS.map(r => ({ ...r, authoritative: false }))); }
+    return fetchViaConfig('anthropic', key).then(rows =>
+      (rows.length > 0 ? rows : ANTHROPIC_MODELS.map(r => ({ ...r, authoritative: false }))));
   }
 
   const config = PROVIDER_FETCH_CONFIG[provider];
@@ -103,6 +123,18 @@ function fetchModelsFromProvider(provider, key) {
     return Promise.resolve([]);
   }
 
+  return fetchViaConfig(provider, key);
+}
+
+/**
+ * Perform the HTTPS fetch + normalize for a single configured provider.
+ * Resolves to `[]` on any non-200 response, network error, timeout, or parse error.
+ * @param {string} provider - Key into PROVIDER_FETCH_CONFIG
+ * @param {string} key - API key
+ * @returns {Promise<Array>} Normalized model rows, or [] on any failure
+ */
+function fetchViaConfig(provider, key) {
+  const config = PROVIDER_FETCH_CONFIG[provider];
   const url = config.buildUrl ? config.buildUrl(key) : config.url;
   const headers = config.authHeader(key);
 

package/src/utils/model-input-default.js

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * @module model-input-default
+ * Shared "no --model given" default-lookup, extracted so it lives in exactly
+ * one place (#61 Task 6.2 review follow-up): both the CLI's resolveLaunchModel
+ * (start-helpers.js) and the MCP amicus_start handler (mcp-server.js) need to
+ * fall back to the configured default before handing a model off to
+ * resolveRouteForLaunch — without it, an omitted model reaches
+ * resolveRouteForLaunch as undefined -> parseDescriptor(undefined) -> an
+ * `invalid` descriptor, breaking the common "no --model" launch case.
+ * A leaf module (no other src/ module requires/mocks it), so introducing it
+ * doesn't reshape any existing jest.doMock('../src/utils/route-launch', ...)
+ * or jest.doMock('../src/utils/config', ...) call shape.
+ */
+
+/**
+ * Resolve the raw model input for a launch: an explicit value (including one
+ * a caller may have already normalized) passes through unchanged; otherwise
+ * falls back to the configured default.
+ * @param {string|null|undefined} inputModel
+ * @returns {string|undefined} inputModel as-is, the configured default, or
+ *   undefined if neither exists (the caller decides how to report that).
+ */
+function resolveModelInputOrDefault(inputModel) {
+  if (inputModel !== undefined && inputModel !== null) { return inputModel; }
+  const { loadConfig } = require('./config');
+  const cfg = loadConfig();
+  return (cfg && cfg.default) ? cfg.default : undefined;
+}
+
+module.exports = { resolveModelInputOrDefault };

package/src/utils/model-validator.js

@@ -7,10 +7,7 @@
  */
 
 const readline = require('readline');
-const { fetchModelsFromProvider } = require('./model-fetcher');
-const { readApiKeyValues } = require('./api-key-store');
 const { loadConfig, saveConfig, getConfigPath } = require('./config');
-const { logger } = require('./logger');
 
 /**
  * Normalize a model ID to include the provider prefix.
@@ -33,54 +30,6 @@ const ALIAS_SEARCH_TERMS = {
   'deepseek': 'deepseek',
 };
 
-/**
- * Validate a direct-API fallback model exists on the provider.
- * Returns silently if valid. On failure: prompts (interactive) or throws (headless).
- *
- * @param {string} resolvedModel - e.g. 'google/gemini-3.1-flash-lite-preview'
- * @param {string} alias - Original alias name (e.g. 'gemini')
- * @param {object} [options]
- * @param {boolean} [options.headless] - If true, throw instead of prompting
- * @returns {Promise<string>} Confirmed model string
- */
-async function validateDirectModel(resolvedModel, alias, options = {}) {
-  const parts = resolvedModel.split('/');
-  if (parts.length < 2) { return resolvedModel; }
-
-  const provider = parts[0];
-  const modelId = parts.slice(1).join('/');
-
-  const keys = readApiKeyValues();
-  const providerKey = keys[provider];
-  if (!providerKey) { return resolvedModel; }
-
-  let models;
-  try {
-    models = await fetchModelsFromProvider(provider, providerKey);
-  } catch (err) {
-    logger.debug({ msg: 'Model fetch failed, skipping validation', error: err.message });
-    return resolvedModel;
-  }
-
-  if (!models || models.length === 0) { return resolvedModel; }
-
-  const found = models.some(m => m.id === resolvedModel || m.id === modelId);
-  if (found) { return resolvedModel; }
-
-  const relevant = filterRelevantModels(models, alias);
-
-  if (options.headless || !process.stdin.isTTY) {
-    const list = relevant.slice(0, 10).map(m => `  ${normalizeModelId(provider, m.id)}`).join('\n');
-    throw new Error(
-      `Model '${modelId}' not found on ${provider} API.\n` +
-      `Available models:\n${list}\n` +
-      `Fix with: amicus setup --add-alias ${alias}=${relevant[0] ? normalizeModelId(provider, relevant[0].id) : 'provider/model'}`
-    );
-  }
-
-  return promptModelSelection(relevant, alias, provider, modelId);
-}
-
 /**
  * Filter models to those relevant to the alias
  * @param {Array<{id: string, name: string}>} models
@@ -101,54 +50,83 @@ function filterRelevantModels(models, alias) {
   return filtered.slice(0, 15);
 }
 
-/** Interactive prompt — ask user to pick from available models */
-async function promptModelSelection(models, alias, provider, failedModelId) {
-  process.stderr.write(`\n  Model '${failedModelId}' not found on ${provider} API.\n`);
-  process.stderr.write('  Available models:\n');
-  models.forEach((m, i) => {
-    const label = (m.name && m.name !== m.id) ? `${m.name} (${m.id})` : m.id;
-    process.stderr.write(`    ${i + 1}. ${label}\n`);
+/**
+ * Interactive alternatives picker for a direct-model miss (#61 Task 6.3, spec
+ * Decision 10). Presents `selectionResult.suggestions` (built upstream by
+ * route-launch.js's buildSuggestions) as a labeled numbered menu and lets the
+ * user pick one, or cancel. Uses the same readline + persist pattern (same
+ * save-with-malformed-config guard) as other model pickers in this module,
+ * adapted to the `{model, gateway, note}` suggestion shape instead of
+ * provider `{id, name}` rows.
+ *
+ * Never auto-selects — even a single suggestion still requires an explicit
+ * pick. Cancellation (empty input, an out-of-range number, or no suggestions
+ * to offer) always throws; the caller (resolveLaunchModel) is expected to
+ * catch and translate that into a "cancelled" stderr message + exit(1).
+ *
+ * @param {{requested: string, suggestions: Array<{model:string, gateway:string, note?:string}>}} selectionResult
+ * @param {string|undefined} alias - alias to persist the choice under, if any
+ * @returns {Promise<{model: string, gateway: string}>}
+ */
+async function promptRouteSelection(selectionResult, alias) {
+  const suggestions = (selectionResult && Array.isArray(selectionResult.suggestions))
+    ? selectionResult.suggestions : [];
+  const requested = selectionResult && selectionResult.requested;
+
+  process.stderr.write(`\n  Model '${requested}' isn't available on the direct API.\n`);
+
+  if (suggestions.length === 0) {
+    process.stderr.write('  No alternatives available.\n\n');
+    throw new Error('Model selection cancelled.');
+  }
+
+  process.stderr.write('  Alternatives:\n');
+  suggestions.forEach((s, i) => {
+    const note = s && s.note ? ` — ${s.note}` : '';
+    process.stderr.write(`    ${i + 1}. ${s && s.model}  [${s && s.gateway}]${note}\n`);
   });
   process.stderr.write('\n');
 
   const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
 
   const answer = await new Promise(resolve => {
-    rl.question(`  Select a model (1-${models.length}) or press Enter to cancel: `, resolve);
+    rl.question(`  Select (1-${suggestions.length}) or Enter to cancel: `, resolve);
   });
   rl.close();
 
   const idx = parseInt(answer, 10) - 1;
-  if (isNaN(idx) || idx < 0 || idx >= models.length) {
+  if (isNaN(idx) || idx < 0 || idx >= suggestions.length) {
     throw new Error('Model selection cancelled.');
   }
 
-  const selected = models[idx];
-  const newModel = normalizeModelId(provider, selected.id);
-
-  let config = loadConfig();
-  if (!config) {
-    const fs = require('fs');
-    const configPath = getConfigPath();
-    if (fs.existsSync(configPath)) {
-      throw new Error(
-        `Cannot save model selection: config file at ${configPath} is malformed. ` +
-        'Fix it manually or run \'amicus setup\'.'
-      );
+  const chosen = suggestions[idx];
+  const newModel = chosen.model;
+
+  if (alias) {
+    let config = loadConfig();
+    if (!config) {
+      const fs = require('fs');
+      const configPath = getConfigPath();
+      if (fs.existsSync(configPath)) {
+        throw new Error(
+          `Cannot save model selection: config file at ${configPath} is malformed. ` +
+          'Fix it manually or run \'amicus setup\'.'
+        );
+      }
+      config = {};
+    }
+    if (!config.aliases) { config.aliases = {}; }
+    config.aliases[alias] = newModel;
+    try {
+      saveConfig(config);
+      process.stderr.write(`  Saved: ${alias} -> ${newModel}\n`);
+    } catch (err) {
+      process.stderr.write(`  Warning: Could not save selection (${err.message}). Using for this session only.\n`);
     }
-    config = {};
-  }
-  if (!config.aliases) { config.aliases = {}; }
-  config.aliases[alias] = newModel;
-  try {
-    saveConfig(config);
-    process.stderr.write(`  Saved: ${alias} → ${newModel}\n`);
-  } catch (err) {
-    process.stderr.write(`  Warning: Could not save selection (${err.message}). Using for this session only.\n`);
   }
-  process.stderr.write(`  (To change later: amicus setup --add-alias ${alias}=...)\n\n`);
+  process.stderr.write('\n');
 
-  return newModel;
+  return { model: newModel, gateway: chosen.gateway };
 }
 
 /**
@@ -204,4 +182,10 @@ async function warnIfNotInCatalog(model) {
   }
 }
 
-module.exports = { validateDirectModel, filterRelevantModels, normalizeModelId, validateAgainstCatalog, warnIfNotInCatalog };
+module.exports = {
+  filterRelevantModels,
+  normalizeModelId,
+  validateAgainstCatalog,
+  warnIfNotInCatalog,
+  promptRouteSelection,
+};

package/src/utils/provider-registry.js

@@ -0,0 +1,57 @@
+/**
+ * Provider-capability registry — the single source of truth for provider
+ * identity, credentials, direct-vs-gateway role, and display names.
+ * The historical maps (PROVIDER_ENV_MAP, PROVIDER_KEY_MAP, KNOWN_PROVIDERS,
+ * PROVIDER_FAMILY_NAMES) are DERIVED from PROVIDERS below so they can never
+ * drift apart again. Leaf module: requires nothing internal (no circular deps).
+ */
+'use strict';
+
+/**
+ * @typedef {Object} ProviderDescriptor
+ * @property {string} id            provider id (namespace)
+ * @property {string} envVar        env var holding the key
+ * @property {string} keyDisplayName human name used in missing-key errors
+ * @property {string} familyName    short name used for optgroup grouping
+ * @property {boolean} direct        can be a DIRECT route target (false for the gateway)
+ * @property {boolean} gateway       is the OpenRouter gateway itself
+ * @property {boolean} hasLiveFetch  has a live GET /models endpoint
+ * @property {string} authJsonKey    key used in OpenCode auth.json
+ */
+
+/** @type {ProviderDescriptor[]} */
+const PROVIDERS = [
+  { id: 'openrouter', envVar: 'OPENROUTER_API_KEY',            keyDisplayName: 'OpenRouter',    familyName: 'OpenRouter', direct: false, gateway: true,  hasLiveFetch: true,  authJsonKey: 'openrouter' },
+  { id: 'google',     envVar: 'GOOGLE_GENERATIVE_AI_API_KEY', keyDisplayName: 'Google Gemini', familyName: 'Google',     direct: true,  gateway: false, hasLiveFetch: true,  authJsonKey: 'google' },
+  { id: 'openai',     envVar: 'OPENAI_API_KEY',               keyDisplayName: 'OpenAI',        familyName: 'OpenAI',     direct: true,  gateway: false, hasLiveFetch: true,  authJsonKey: 'openai' },
+  { id: 'anthropic',  envVar: 'ANTHROPIC_API_KEY',            keyDisplayName: 'Anthropic',     familyName: 'Anthropic',  direct: true,  gateway: false, hasLiveFetch: true,  authJsonKey: 'anthropic' },
+  { id: 'deepseek',   envVar: 'DEEPSEEK_API_KEY',             keyDisplayName: 'DeepSeek',      familyName: 'DeepSeek',   direct: true,  gateway: false, hasLiveFetch: true,  authJsonKey: 'deepseek' },
+];
+
+const _byId = new Map(PROVIDERS.map(p => [p.id, p]));
+
+/** @param {string} id @returns {ProviderDescriptor|undefined} */
+function getProvider(id) { return _byId.get(id); }
+
+/** @param {string} id @returns {boolean} true only for direct-route vendors (never the gateway) */
+function isDirectProvider(id) { const p = _byId.get(id); return !!p && p.direct; }
+
+/** @returns {string[]} ids of direct-route vendors (excludes openrouter) */
+function listDirectProviders() { return PROVIDERS.filter(p => p.direct).map(p => p.id); }
+
+// --- Derived compatibility maps (do not hand-edit; edit PROVIDERS above) ---
+const PROVIDER_ENV_MAP = Object.fromEntries(PROVIDERS.map(p => [p.id, p.envVar]));
+const PROVIDER_KEY_MAP = Object.fromEntries(PROVIDERS.map(p => [p.id, { key: p.envVar, name: p.keyDisplayName }]));
+const KNOWN_PROVIDERS = PROVIDERS.map(p => p.id);
+const PROVIDER_FAMILY_NAMES = Object.fromEntries(PROVIDERS.map(p => [p.id, p.familyName]));
+
+module.exports = {
+  PROVIDERS,
+  getProvider,
+  isDirectProvider,
+  listDirectProviders,
+  PROVIDER_ENV_MAP,
+  PROVIDER_KEY_MAP,
+  KNOWN_PROVIDERS,
+  PROVIDER_FAMILY_NAMES,
+};

package/src/utils/quick-picks.js

@@ -10,7 +10,7 @@
 
 'use strict';
 
-const { getFamilies, toDefaultAliases } = require('./curated-models');
+const { getFamilies, toDefaultAliases, toCanonicalDefault } = require('./curated-models');
 
 const MARKER_RE = /(-preview|-exp|-beta|-latest|:free)+$/;
 
@@ -67,13 +67,21 @@ function resolveQuickPicks(catalog) {
 
 /**
  * Seed map for fresh configs: static defaults overlaid with live family
- * openrouter routes (cardless aliases stay pinned).
+ * routes (cardless aliases stay pinned). The overlaid route is run through
+ * `toCanonicalDefault` so a direct-capable vendor (e.g. google, openai)
+ * lands as bare `vendor/model` (direct-first via the gateway router)
+ * instead of the raw `openrouter/<vendor>/<rest>` pick — otherwise a fresh
+ * `amicus setup` with a live catalog would silently defeat the direct-first
+ * default `toDefaultAliases()` establishes. Gateway-only vendors are
+ * returned unchanged by `toCanonicalDefault`.
  * @returns {Object<string,string>}
  */
 function toLiveSeedAliases(catalog) {
   const seeds = toDefaultAliases();
   for (const r of resolveQuickPicks(catalog || [])) {
-    if (r.source === 'live' && r.routes.openrouter) { seeds[r.alias] = r.routes.openrouter; }
+    if (r.source === 'live' && r.routes.openrouter) {
+      seeds[r.alias] = toCanonicalDefault(r.routes.openrouter);
+    }
   }
   return seeds;
 }

package/src/utils/result-schema-rebuild.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * @module result-schema-rebuild
+ * Rebuild run/wave documents from persisted session directories (as opposed to
+ * `result-schema.js`'s builders, which assemble a document from in-memory
+ * state right after a run/wave finishes). Split out of result-schema.js to
+ * stay under the 300-line size gate (#61 whole-branch review housekeeping) —
+ * re-exported from result-schema.js so every existing caller's import path is
+ * unaffected.
+ *
+ * `buildRunResult`/`buildWaveResult` are required LAZILY inside each function
+ * body (not at module load time) so this file can depend on result-schema.js
+ * without a circular-require ordering hazard: result-schema.js requires this
+ * module too (to re-export these two functions), and a top-level require here
+ * would see result-schema.js's exports mid-assembly (see result-schema.js's
+ * module doc for why abort-result.js already avoids the same trap).
+ */
+
+/**
+ * Rebuild a run document from a persisted session directory.
+ * @param {string} project - Project dir
+ * @param {string} taskId
+ * @returns {object} run document
+ * @throws {Error} if the session does not exist or metadata.json is missing/corrupt
+ */
+function buildRunResultFromSession(project, taskId) {
+  const fs = require('fs');
+  const path = require('path');
+  const { resolveExistingSessionDir } = require('../session-manager');
+  const { buildRunResult } = require('./result-schema');
+  const sessionDir = resolveExistingSessionDir(project, taskId);
+  const metaPath = path.join(sessionDir, 'metadata.json');
+  if (!fs.existsSync(metaPath)) {
+    throw new Error(`Session ${taskId} not found`);
+  }
+  let metadata;
+  try {
+    metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Session ${taskId}: metadata is corrupt (${err.message})`);
+  }
+  const summaryPath = path.join(sessionDir, 'summary.md');
+  const summary = fs.existsSync(summaryPath) ? fs.readFileSync(summaryPath, 'utf-8') : null;
+  return buildRunResult({ taskId, metadata, summary, sessionDir });
+}
+
+/**
+ * Rebuild a wave document. Prefers the stored wave.json (written atomically at
+ * fanout exit); falls back to a live rebuild from leg sessions (e.g. after a
+ * hard kill of the fanout process).
+ * @param {string} project
+ * @param {string} waveId
+ * @returns {object} wave document
+ * @throws {Error} if the wave session does not exist or metadata.json is missing/corrupt
+ */
+function buildWaveResultFromSession(project, waveId) {
+  const fs = require('fs');
+  const path = require('path');
+  const { resolveExistingSessionDir } = require('../session-manager');
+  const { buildRunResult, buildWaveResult } = require('./result-schema');
+  const waveDir = resolveExistingSessionDir(project, waveId);
+  const wavePath = path.join(waveDir, 'wave.json');
+  if (fs.existsSync(wavePath)) {
+    try {
+      return JSON.parse(fs.readFileSync(wavePath, 'utf-8'));
+    } catch {
+      // Corrupt wave.json (e.g. hard-kill mid-write) — fall through to live rebuild
+    }
+  }
+  const metaPath = path.join(waveDir, 'metadata.json');
+  if (!fs.existsSync(metaPath)) {
+    throw new Error(`Wave ${waveId} not found`);
+  }
+  let meta;
+  try {
+    meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Wave ${waveId}: metadata is corrupt (${err.message})`);
+  }
+  const legs = (meta.legs || []).map((legId) => {
+    try { return buildRunResultFromSession(project, legId); }
+    catch (err) {
+      const { logger } = require('./logger');
+      logger.warn('Failed to rebuild leg session; using unknown stub', { legId, error: err.message });
+      return buildRunResult({ taskId: legId, metadata: { status: 'unknown', parentWave: waveId } });
+    }
+  });
+  return buildWaveResult({
+    waveId,
+    legs,
+    promptMeta: meta.promptMeta || null,
+    createdAt: meta.createdAt || null,
+    completedAt: meta.completedAt || null,
+  });
+}
+
+module.exports = { buildRunResultFromSession, buildWaveResultFromSession };