@delegance/claude-autopilot 2.5.0 → 5.0.0-alpha.2

package/src/cli/worker.ts

@@ -0,0 +1,109 @@
+import { readLock, writeLock, deleteLock, isWorkerAlive } from '../core/worker/lockfile.ts';
+import { stopWorker, getWorkerStatus } from '../core/worker/client.ts';
+import { startWorkerServer } from '../core/worker/server.ts';
+import { loadConfig } from '../core/config/loader.ts';
+import type { ReviewEngine } from '../adapters/review-engine/types.ts';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+
+const C = { reset: '\x1b[0m', green: '\x1b[32m', red: '\x1b[31m', yellow: '\x1b[33m', dim: '\x1b[2m', bold: '\x1b[1m' };
+
+export async function runWorker(sub: string | undefined, options: { cwd?: string; configPath?: string } = {}): Promise<number> {
+  const cwd = options.cwd ?? process.cwd();
+  const configPath = options.configPath ?? path.join(cwd, 'guardrail.config.yaml');
+
+  switch (sub) {
+    case 'start':
+      return workerStart(cwd, configPath);
+    case 'stop':
+      return workerStop(cwd);
+    case 'status':
+      return workerStatus(cwd);
+    default:
+      console.error(`${C.red}[guardrail worker] Unknown subcommand: "${sub ?? ''}". Use start|stop|status${C.reset}`);
+      return 1;
+  }
+}
+
+async function workerStart(cwd: string, configPath: string): Promise<number> {
+  const existing = readLock(cwd);
+  if (existing && isWorkerAlive(existing)) {
+    console.log(`${C.yellow}[worker] Already running — pid ${existing.pid} port ${existing.port}${C.reset}`);
+    return 0;
+  }
+
+  let config = { configVersion: 1 as const };
+  if (fs.existsSync(configPath)) {
+    const loaded = await loadConfig(configPath);
+    if (loaded) config = loaded;
+  }
+
+  // Lazy import to avoid loading review engine at CLI startup
+  const { loadAdapter } = await import('../adapters/loader.ts');
+  const { runReviewPhase } = await import('../core/pipeline/review-phase.ts');
+
+  const engineRef = (config as { reviewEngine?: unknown }).reviewEngine;
+  const ref = typeof engineRef === 'string' ? engineRef : (engineRef as { adapter?: string })?.adapter ?? 'auto';
+  const engineOptions = typeof engineRef === 'object' && engineRef !== null
+    ? (engineRef as { options?: Record<string, unknown> }).options
+    : undefined;
+
+  const engine = await loadAdapter({
+    point: 'review-engine',
+    ref,
+    options: engineOptions,
+  });
+
+  const server = await startWorkerServer({
+    cwd,
+    onReview: async (files, cfg) => {
+      const result = await runReviewPhase({ touchedFiles: files, config: cfg, engine: engine as unknown as ReviewEngine });
+      return { findings: result.findings, usage: result.costUSD !== undefined ? { costUSD: result.costUSD } : undefined };
+    },
+  });
+
+  writeLock(cwd, { pid: process.pid, port: server.port, startedAt: new Date().toISOString() });
+
+  const cleanup = () => { deleteLock(cwd); server.close().then(() => process.exit(0)); };
+  process.on('SIGTERM', cleanup);
+  process.on('SIGINT', cleanup);
+
+  console.log(`${C.green}[worker] Started — pid ${process.pid} port ${server.port}${C.reset}`);
+  console.log(`${C.dim}  guardrail run --use-worker   # dispatch review chunks to this worker${C.reset}`);
+
+  await new Promise(() => {}); // keep alive
+  return 0;
+}
+
+async function workerStop(cwd: string): Promise<number> {
+  const lock = readLock(cwd);
+  if (!lock) { console.log('[worker] No worker running'); return 0; }
+  if (!isWorkerAlive(lock)) { deleteLock(cwd); console.log('[worker] Stale lockfile removed'); return 0; }
+  await stopWorker(lock);
+  // Give it 3s to exit, then SIGTERM
+  await new Promise(r => setTimeout(r, 1000));
+  if (isWorkerAlive(lock)) {
+    try { process.kill(lock.pid, 'SIGTERM'); } catch { /* already dead */ }
+  }
+  deleteLock(cwd);
+  console.log(`${C.green}[worker] Stopped${C.reset}`);
+  return 0;
+}
+
+async function workerStatus(cwd: string): Promise<number> {
+  const lock = readLock(cwd);
+  if (!lock) { console.log('[worker] Not running'); return 1; }
+  if (!isWorkerAlive(lock)) { console.log(`[worker] Dead (stale lock — pid ${lock.pid})`); return 1; }
+  try {
+    const status = await getWorkerStatus(lock);
+    console.log(`[worker] Running`);
+    console.log(`  pid:            ${status.pid}`);
+    console.log(`  port:           ${status.port}`);
+    console.log(`  jobs processed: ${status.jobsProcessed}`);
+    console.log(`  uptime:         ${Math.round(status.uptimeMs / 1000)}s`);
+    return 0;
+  } catch {
+    console.log(`[worker] Running (pid ${lock.pid} port ${lock.port}) — status endpoint unreachable`);
+    return 0;
+  }
+}

package/src/core/cache/review-cache.ts

@@ -17,10 +17,10 @@ export interface ReviewCacheOptions {
 }
 
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
-// Prefer env override, then ~/.autopilot-cache to survive across cwd changes and container restarts
+// Prefer env override, then ~/.guardrail-cache to survive across cwd changes and container restarts
 const DEFAULT_CACHE_DIR = process.env.AUTOPILOT_CACHE_DIR
   ? path.join(process.env.AUTOPILOT_CACHE_DIR, 'reviews')
-  : path.join(os.homedir(), '.autopilot-cache', 'reviews');
+  : path.join(os.homedir(), '.guardrail-cache', 'reviews');
 
 export class ReviewCache {
   private readonly cacheDir: string;

package/src/core/chunking/index.ts

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import type { ReviewEngine, ReviewInput } from '../../adapters/review-engine/types.ts';
-import type { AutopilotConfig } from '../config/types.ts';
+import type { GuardrailConfig } from '../config/types.ts';
 import { rankByRisk } from './risk-ranker.ts';
 import { getFileDiffs, formatDiffContent } from '../git/diff-hunks.ts';
 
@@ -14,7 +14,7 @@ export interface ReviewChunk {
 export interface BuildChunksInput {
   touchedFiles: string[];
   strategy: 'auto' | 'single-pass' | 'file-level' | 'diff' | 'auto-diff';
-  chunking?: AutopilotConfig['chunking'];
+  chunking?: GuardrailConfig['chunking'];
   engine: ReviewEngine;
   cwd?: string;
   protectedPaths?: string[];

package/src/core/config/loader.ts

@@ -1,19 +1,19 @@
 import * as fs from 'node:fs/promises';
 import * as yaml from 'js-yaml';
 import Ajv from 'ajv';
-import { AutopilotError } from '../errors.ts';
-import type { AutopilotConfig } from './types.ts';
-import { AUTOPILOT_CONFIG_SCHEMA } from './schema.ts';
+import { GuardrailError } from '../errors.ts';
+import type { GuardrailConfig } from './types.ts';
+import { GUARDRAIL_CONFIG_SCHEMA } from './schema.ts';
 
 const ajv = new Ajv({ allErrors: true, strict: false });
-const validate = ajv.compile(AUTOPILOT_CONFIG_SCHEMA);
+const validate = ajv.compile(GUARDRAIL_CONFIG_SCHEMA);
 
-export async function loadConfig(path: string): Promise<AutopilotConfig> {
+export async function loadConfig(path: string): Promise<GuardrailConfig> {
   let content: string;
   try {
     content = await fs.readFile(path, 'utf8');
   } catch (err) {
-    throw new AutopilotError(`Config file not found: ${path}`, {
+    throw new GuardrailError(`Config file not found: ${path}`, {
       code: 'user_input',
       details: { path, cause: err instanceof Error ? err.message : String(err) },
     });
@@ -23,7 +23,7 @@ export async function loadConfig(path: string): Promise<AutopilotConfig> {
   try {
     parsed = yaml.load(content);
   } catch (err) {
-    throw new AutopilotError(`Invalid YAML in ${path}`, {
+    throw new GuardrailError(`Invalid YAML in ${path}`, {
       code: 'invalid_config',
       details: { path, cause: err instanceof Error ? err.message : String(err) },
     });
@@ -43,11 +43,11 @@ export async function loadConfig(path: string): Promise<AutopilotConfig> {
       return `${loc}: ${e.message ?? 'invalid'}`;
     });
     const summary = errors.slice(0, 5).join('\n  ');
-    throw new AutopilotError(
-      `autopilot.config.yaml is invalid:\n  ${summary}${errors.length > 5 ? `\n  …and ${errors.length - 5} more` : ''}`,
+    throw new GuardrailError(
+      `guardrail.config.yaml is invalid:\n  ${summary}${errors.length > 5 ? `\n  …and ${errors.length - 5} more` : ''}`,
       { code: 'invalid_config', details: { path, errors } },
     );
   }
 
-  return parsed as AutopilotConfig;
+  return parsed as GuardrailConfig;
 }

package/src/core/config/preset-resolver.ts

@@ -1,14 +1,14 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { loadConfig } from './loader.ts';
-import { AutopilotError } from '../errors.ts';
-import type { AutopilotConfig } from './types.ts';
+import { GuardrailError } from '../errors.ts';
+import type { GuardrailConfig } from './types.ts';
 
 const PRESET_ROOT = path.resolve(process.cwd(), 'presets');
 
 export interface ResolvedPreset {
   name: string;
-  config: AutopilotConfig;
+  config: GuardrailConfig;
   stack: string;
 }
 
@@ -17,13 +17,13 @@ export async function resolvePreset(name: string): Promise<ResolvedPreset> {
   try {
     await fs.stat(presetDir);
   } catch {
-    throw new AutopilotError(`Preset not found: ${name}`, {
+    throw new GuardrailError(`Preset not found: ${name}`, {
       code: 'invalid_config',
       details: { name, presetDir },
     });
   }
 
-  const config = await loadConfig(path.join(presetDir, 'autopilot.config.yaml'));
+  const config = await loadConfig(path.join(presetDir, 'guardrail.config.yaml'));
   let stack = '';
   try {
     stack = await fs.readFile(path.join(presetDir, 'stack.md'), 'utf8');
@@ -33,7 +33,7 @@ export async function resolvePreset(name: string): Promise<ResolvedPreset> {
   return { name, config, stack };
 }
 
-export function mergeConfigs(preset: AutopilotConfig, user: AutopilotConfig): AutopilotConfig {
+export function mergeConfigs(preset: GuardrailConfig, user: GuardrailConfig): GuardrailConfig {
   return {
     ...preset,
     ...user,

package/src/core/config/schema.ts

@@ -1,4 +1,4 @@
-export const AUTOPILOT_CONFIG_SCHEMA = {
+export const GUARDRAIL_CONFIG_SCHEMA = {
   $schema: 'http://json-schema.org/draft-07/schema#',
   type: 'object',
   required: ['configVersion'],
@@ -64,10 +64,111 @@ export const AUTOPILOT_CONFIG_SCHEMA = {
       },
       additionalProperties: false,
     },
-    cost: { type: 'object' },
+    policy: {
+      type: 'object',
+      properties: {
+        failOn: { enum: ['critical', 'warning', 'note', 'none'] },
+        newOnly: { type: 'boolean' },
+        baselinePath: { type: 'string' },
+      },
+      additionalProperties: false,
+    },
+    pipeline: {
+      type: 'object',
+      properties: {
+        runReviewOnStaticFail: { type: 'boolean' },
+        runReviewOnTestFail: { type: 'boolean' },
+      },
+      additionalProperties: false,
+    },
+    cost: {
+      type: 'object',
+      properties: {
+        maxPerRun: { type: 'number' },
+        estimateBeforeRun: { type: 'boolean' },
+        pricing: { type: 'object' },
+      },
+      additionalProperties: false,
+    },
+    brand: {
+      type: 'object',
+      properties: {
+        colorsFrom: { type: 'string' },
+        colors: { type: 'array', items: { type: 'string' } },
+        fonts: { type: 'array', items: { type: 'string' } },
+        componentLibrary: {
+          oneOf: [
+            { type: 'string' },
+            {
+              type: 'object',
+              properties: {
+                tokens: { type: 'string' },
+                guide: { type: 'string' },
+              },
+              additionalProperties: false,
+            },
+          ],
+        },
+      },
+      additionalProperties: false,
+    },
+    'schema-alignment': {
+      type: 'object',
+      properties: {
+        enabled: { type: 'boolean' },
+        migrationGlobs: { type: 'array', items: { type: 'string', minLength: 1 } },
+        layerRoots: {
+          type: 'object',
+          properties: {
+            types: { type: 'array', items: { type: 'string' }, minItems: 1 },
+            api: { type: 'array', items: { type: 'string' }, minItems: 1 },
+            ui: { type: 'array', items: { type: 'string' }, minItems: 1 },
+          },
+          additionalProperties: false,
+        },
+        llmCheck: { type: 'boolean' },
+        severity: { enum: ['warning', 'error'] },
+      },
+      additionalProperties: false,
+    },
     cache: { type: 'object' },
     persistence: { type: 'object' },
     concurrency: { type: 'object' },
+    council: {
+      type: 'object',
+      required: ['models', 'synthesizer'],
+      additionalProperties: false,
+      properties: {
+        models: {
+          type: 'array',
+          minItems: 2,
+          items: {
+            type: 'object',
+            required: ['adapter', 'model', 'label'],
+            additionalProperties: false,
+            properties: {
+              adapter: { type: 'string' },
+              model: { type: 'string' },
+              label: { type: 'string' },
+            },
+          },
+        },
+        synthesizer: {
+          type: 'object',
+          required: ['adapter', 'model', 'label'],
+          additionalProperties: false,
+          properties: {
+            adapter: { type: 'string' },
+            model: { type: 'string' },
+            label: { type: 'string' },
+          },
+        },
+        timeout_ms: { type: 'number' },
+        min_successful_responses: { type: 'number' },
+        parallel_input_max_tokens: { type: 'number' },
+        synthesis_input_max_tokens: { type: 'number' },
+      },
+    },
   },
   definitions: {
     adapterRef: {

package/src/core/config/types.ts

@@ -1,3 +1,5 @@
+import type { SchemaAlignmentConfig } from '../schema-alignment/types.ts';
+
 export interface AdapterReference {
   adapter: string;
   options?: Record<string, unknown>;
@@ -7,7 +9,7 @@ export type AdapterRef = string | AdapterReference;
 
 export type StaticRuleReference = string | { adapter: string; options?: Record<string, unknown> };
 
-export interface AutopilotConfig {
+export interface GuardrailConfig {
   configVersion: 1;
   preset?: string;
   reviewEngine?: AdapterRef;
@@ -36,8 +38,61 @@ export interface AutopilotConfig {
     parallelism?: number;
     rateLimitBackoff?: 'exp' | 'linear' | 'none';
   };
-  cost?: Record<string, unknown>;
+  policy?: {
+    /** Severity threshold for exit code 1. Default: 'critical'. Use 'none' to always pass. */
+    failOn?: 'critical' | 'warning' | 'note' | 'none';
+    /** Only report findings not present in the committed baseline. Default: false. */
+    newOnly?: boolean;
+    /** Path to baseline file relative to cwd. Default: .guardrail-baseline.json */
+    baselinePath?: string;
+  };
+  pipeline?: {
+    /**
+     * When true, run the LLM review phase even if the static-rules phase reports `fail`
+     * (i.e. finds a critical). Default: true. Set to false to skip only the review
+     * phase on static-fail — the tests phase still runs regardless.
+     *
+     * Users that explicitly configure a review engine typically expect it to run — the
+     * bugs the LLM is best at (IDOR, TOCTOU, CORS, off-by-one, rate limits) often sit
+     * in the same commit as something a static rule already flagged. This flag only
+     * gates the review phase, mirroring `runReviewOnTestFail`.
+     */
+    runReviewOnStaticFail?: boolean;
+    /**
+     * When true, run the LLM review phase even if the tests phase reports `fail`.
+     * Default: false — failing tests usually indicate broken code, not code to review.
+     * This flag only gates the review phase; the tests phase itself always runs.
+     */
+    runReviewOnTestFail?: boolean;
+  };
+  cost?: {
+    /** Abort review phase if estimated spend exceeds this amount (USD). */
+    maxPerRun?: number;
+    /** Print token estimate before starting LLM review. Default: false. */
+    estimateBeforeRun?: boolean;
+    /** Per-model token price overrides (input/output per 1M tokens). */
+    pricing?: Record<string, { inputPer1M: number; outputPer1M: number }>;
+  };
+  brand?: {
+    /** Path to tailwind.config.{ts,js} — auto-extracts theme.colors as canonical palette */
+    colorsFrom?: string;
+    /** Explicit canonical color values (hex/rgb/hsl). Merged with colorsFrom. */
+    colors?: string[];
+    /** Canonical font family names */
+    fonts?: string[];
+    /** Path to design system component library (informational, for future LLM review) */
+    componentLibrary?: string | { tokens?: string; guide?: string };
+  };
+  'schema-alignment'?: SchemaAlignmentConfig;
   cache?: Record<string, unknown>;
   persistence?: Record<string, unknown>;
   concurrency?: Record<string, unknown>;
+  council?: {
+    models: Array<{ adapter: string; model: string; label: string }>;
+    synthesizer: { adapter: string; model: string; label: string };
+    timeout_ms?: number;
+    min_successful_responses?: number;
+    parallel_input_max_tokens?: number;
+    synthesis_input_max_tokens?: number;
+  };
 }

package/src/core/council/config.ts

@@ -0,0 +1,71 @@
+// src/core/council/config.ts
+import { GuardrailError } from '../errors.ts';
+import type { CouncilConfig, CouncilModelEntry } from './types.ts';
+
+const SUPPORTED_ADAPTERS = new Set(['claude', 'openai']);
+
+export function parseCouncilConfig(raw: Record<string, unknown>): CouncilConfig {
+  const models = raw['models'] as Array<Record<string, string>> | undefined;
+  const synthRaw = raw['synthesizer'] as Record<string, string> | undefined;
+  const timeoutMs = (raw['timeout_ms'] as number | undefined) ?? 30000;
+  const minSuccessful = (raw['min_successful_responses'] as number | undefined) ?? 1;
+  const parallelInputMaxTokens = (raw['parallel_input_max_tokens'] as number | undefined) ?? 8000;
+  const synthesisInputMaxTokens = (raw['synthesis_input_max_tokens'] as number | undefined) ?? 12000;
+
+  if (!Array.isArray(models) || models.length < 2) {
+    throw new GuardrailError('council.models must have at least 2 entries', { code: 'invalid_config' });
+  }
+
+  if (!synthRaw?.['adapter'] || !synthRaw['model'] || !synthRaw['label']) {
+    throw new GuardrailError('council.synthesizer requires adapter, model, and label', { code: 'invalid_config' });
+  }
+
+  if (timeoutMs < 5000) {
+    throw new GuardrailError(`council.timeout_ms must be >= 5000, got ${timeoutMs}`, { code: 'invalid_config' });
+  }
+
+  if (minSuccessful < 1 || minSuccessful > models.length) {
+    throw new GuardrailError(
+      `council.min_successful_responses must be 1–${models.length}, got ${minSuccessful}`,
+      { code: 'invalid_config' },
+    );
+  }
+
+  for (const entry of [...models, synthRaw]) {
+    if (!SUPPORTED_ADAPTERS.has(entry['adapter']!)) {
+      throw new GuardrailError(
+        `council: unknown adapter "${entry['adapter']}" — supported: ${[...SUPPORTED_ADAPTERS].join(', ')}`,
+        { code: 'invalid_config' },
+      );
+    }
+  }
+
+  const seen = new Set<string>();
+  for (const m of models) {
+    if (seen.has(m['label']!)) {
+      throw new GuardrailError(`council.models: duplicate label "${m['label']}"`, { code: 'invalid_config' });
+    }
+    seen.add(m['label']!);
+  }
+
+  const parsedModels: CouncilModelEntry[] = models.map(m => ({
+    adapter: m['adapter'] as 'claude' | 'openai',
+    model: m['model']!,
+    label: m['label']!,
+  }));
+
+  const synthesizer: CouncilModelEntry = {
+    adapter: synthRaw['adapter'] as 'claude' | 'openai',
+    model: synthRaw['model']!,
+    label: synthRaw['label']!,
+  };
+
+  return {
+    models: parsedModels,
+    synthesizer,
+    timeoutMs,
+    minSuccessfulResponses: minSuccessful,
+    parallelInputMaxTokens,
+    synthesisInputMaxTokens,
+  };
+}

package/src/core/council/context.ts

@@ -0,0 +1,17 @@
+const CHARS_PER_TOKEN = 4;
+
+export function windowContext(text: string, maxTokens: number): string {
+  const estimated = Math.ceil(text.length / CHARS_PER_TOKEN);
+  if (estimated <= maxTokens) return text;
+
+  const maxChars = maxTokens * CHARS_PER_TOKEN;
+  // Reserve budget for the marker so the final output stays within maxTokens.
+  // Use a conservative upper bound of the formatted marker (the digit count of
+  // charsDropped is computed from text length to avoid circular dependency).
+  const markerOverhead = `<!-- [council: truncated ${text.length} chars] -->\n`.length;
+  const effectiveMaxChars = Math.max(0, maxChars - markerOverhead);
+  const charsDropped = text.length - effectiveMaxChars;
+  const marker = `<!-- [council: truncated ${charsDropped} chars] -->\n`;
+  process.stderr.write(`[council] context truncated: dropped ${charsDropped} chars to fit ${maxTokens} token budget\n`);
+  return marker + text.slice(charsDropped);
+}

package/src/core/council/runner.ts

@@ -0,0 +1,83 @@
+import * as crypto from 'node:crypto';
+import { windowContext } from './context.ts';
+import type { CouncilConfig, CouncilResult, ModelResponse } from './types.ts';
+import type { CouncilAdapter } from '../../adapters/council/types.ts';
+
+async function consultWithTimeout(
+  adapter: CouncilAdapter,
+  prompt: string,
+  context: string,
+  timeoutMs: number,
+): Promise<ModelResponse> {
+  const start = Date.now();
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    const text = await Promise.race([
+      adapter.consult(prompt, context),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error('timeout')), timeoutMs);
+      }),
+    ]);
+    return { label: adapter.label, status: 'ok', text, latencyMs: Date.now() - start };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return message === 'timeout'
+      ? { label: adapter.label, status: 'timeout', error: 'timed out', latencyMs: Date.now() - start }
+      : { label: adapter.label, status: 'error', error: message, latencyMs: Date.now() - start };
+  } finally {
+    // Always clear the timer to avoid keeping the event loop alive after the
+    // adapter resolves/rejects. Long-running hosts (MCP server) would accumulate
+    // dangling timers for the full timeoutMs otherwise.
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export async function runCouncil(
+  config: CouncilConfig,
+  adapters: CouncilAdapter[],
+  synthesizer: CouncilAdapter,
+  prompt: string,
+  contextDoc: string,
+): Promise<CouncilResult> {
+  const run_id = crypto.randomUUID();
+  const context = windowContext(contextDoc, config.parallelInputMaxTokens);
+
+  const responses = await Promise.all(
+    adapters.map(a => consultWithTimeout(a, prompt, context, config.timeoutMs))
+  );
+
+  const successful = responses.filter(r => r.status === 'ok');
+
+  if (successful.length < config.minSuccessfulResponses) {
+    return { schema_version: 1, run_id, status: 'failed', prompt, responses };
+  }
+
+  const responseSections = successful
+    .map(r => `### ${r.label}\n${r.text}`)
+    .join('\n\n');
+
+  const synthesisDoc = `${contextDoc}\n\n---\n\n${responseSections}`;
+  const synthesisCtx = windowContext(synthesisDoc, config.synthesisInputMaxTokens);
+  const synthesisPrompt = [
+    `You have received responses from multiple technical advisors on the following question:\n\n## Original Question\n\n${prompt}`,
+    `## Advisor Responses\n\n${responseSections}`,
+    'Based on these responses, provide a synthesis: areas of agreement, key disagreements, and your final recommendation.',
+  ].join('\n\n');
+
+  // Synthesizer shares the same per-call timeout as model calls so a hung
+  // synthesizer API doesn't block the whole command indefinitely.
+  const synthResponse = await consultWithTimeout(
+    synthesizer,
+    synthesisPrompt,
+    synthesisCtx,
+    config.timeoutMs,
+  );
+  // status:'ok' means the synthesizer call itself completed without error.
+  // Empty text is valid (e.g. the --no-synthesize stub that intentionally
+  // returns ''); only treat actual failures/timeouts as partial.
+  if (synthResponse.status === 'ok') {
+    const synthesis = { label: synthesizer.label, text: synthResponse.text ?? '', latencyMs: synthResponse.latencyMs };
+    return { schema_version: 1, run_id, status: 'success', prompt, responses, synthesis };
+  }
+  return { schema_version: 1, run_id, status: 'partial', prompt, responses };
+}

package/src/core/council/types.ts

@@ -0,0 +1,45 @@
+// adapter is a closed union — extending to a new provider requires an intentional
+// code change in config.ts and cli/council.ts
+export interface CouncilModelEntry {
+  adapter: 'claude' | 'openai';
+  model: string;
+  label: string;
+}
+
+export interface CouncilConfig {
+  models: CouncilModelEntry[];
+  synthesizer: CouncilModelEntry;
+  timeoutMs: number;
+  minSuccessfulResponses: number;
+  parallelInputMaxTokens: number;
+  synthesisInputMaxTokens: number;
+}
+
+export type ModelResponseStatus = 'ok' | 'timeout' | 'error';
+
+export interface ModelResponse {
+  label: string;
+  status: ModelResponseStatus;
+  text?: string;
+  error?: string;
+  latencyMs: number;
+}
+
+export interface SynthesisResponse {
+  label: string;
+  text: string;
+  latencyMs: number;
+}
+
+export type CouncilStatus = 'success' | 'partial' | 'failed';
+
+export interface CouncilResult {
+  // snake_case: wire-format field, consistent with MCP handler schema_version convention
+  schema_version: 1;
+  // snake_case: wire-format field
+  run_id: string;
+  status: CouncilStatus;
+  prompt: string;
+  responses: ModelResponse[];
+  synthesis?: SynthesisResponse;
+}