@geraldmaron/construct 1.0.21 → 1.0.23

package/lib/model-registry.mjs

@@ -20,17 +20,14 @@ import path from 'node:path';
  * 1. Environment variables (CX_MODEL_*): Emergency overrides
  * 2. User config (~/.construct/config.env): Personal defaults
  * 3. Registry (specialists/registry.json): Project recommendations
- * 4. Built-in defaults: Last resort fallbacks
- * 
- * Primary resolution path. All code must use this function.
+ *
+ * Construct ships with NO implicit model defaults (ADR-0027,
+ * tests/model-router-no-defaults.test.mjs). When none of the three sources
+ * resolves a tier, that tier returns null with source 'not configured'.
+ * Callers must surface a clear remediation hint rather than silently
+ * substituting a vendor-specific default.
  */
 
-const BUILTIN_DEFAULTS = {
-  reasoning: 'anthropic/claude-3-5-sonnet',
-  standard: 'anthropic/claude-3-haiku',
-  fast: 'anthropic/claude-3-haiku',
-};
-
 const ENV_PREFIX = 'CX_MODEL';
 
 // ---------------------------------------------------------------------------
@@ -86,28 +83,30 @@ export function resolveModelTiers(options = {}) {
       }
     }
     
-    // Built-in default
-    result[tier] = BUILTIN_DEFAULTS[tier];
-    sources[tier] = 'default';
+    // No source resolved this tier — leave null + 'not configured' so callers
+    // can surface a clear remediation hint. Aligns with the wired path
+    // (lib/model-router.mjs:resolveTierAssignments) and the no-defaults
+    // contract locked in by tests/model-router-no-defaults.test.mjs.
+
+    result[tier] = null;
+    sources[tier] = 'not configured';
   }
-  
-  // Validation
+
   const configured = Object.values(result).filter(Boolean).length;
-  
+
   if (strict && configured < 3) {
     const missing = Object.entries(result)
       .filter(([, v]) => !v)
       .map(([k]) => k);
     errors.push(`Missing configuration for tiers: ${missing.join(', ')}`);
   }
-  
+
   return {
     models: result,
     sources,
     configured,
     complete: configured === 3,
     errors: errors.length > 0 ? errors : null,
-    defaultsUsed: Object.values(sources).filter(s => s === 'default').length,
   };
 }
 
@@ -117,7 +116,7 @@ export function resolveModelTiers(options = {}) {
 
 export function getModelForTier(tier, options = {}) {
   const resolved = resolveModelTiers(options);
-  return resolved.models[tier] || BUILTIN_DEFAULTS[tier];
+  return resolved.models[tier];
 }
 
 export function getModelSource(tier, options = {}) {
@@ -131,12 +130,15 @@ export function getModelSource(tier, options = {}) {
 
 export function validateModelTiers(options = {}) {
   const resolved = resolveModelTiers({ ...options, strict: true });
-  
+  const unconfigured = Object.entries(resolved.sources)
+    .filter(([, source]) => source === 'not configured')
+    .map(([tier]) => tier);
+
   return {
     valid: resolved.complete && !resolved.errors,
     errors: resolved.errors,
-    warnings: resolved.defaultsUsed > 0 
-      ? [`Using ${resolved.defaultsUsed} built-in default(s). Consider configuring custom models.`]
+    warnings: unconfigured.length > 0
+      ? [`Unconfigured tier${unconfigured.length === 1 ? '' : 's'}: ${unconfigured.join(', ')}. Run 'construct models --apply' or set CX_MODEL_<TIER>.`]
       : [],
     resolution: resolved,
   };
@@ -144,25 +146,30 @@ export function validateModelTiers(options = {}) {
 
 export function formatModelStatus(options = {}) {
   const resolved = resolveModelTiers(options);
-  
+
   let output = 'Model Configuration:\n\n';
-  
+
   for (const tier of ['reasoning', 'standard', 'fast']) {
     const model = resolved.models[tier];
     const source = resolved.sources[tier];
-    const icon = source === 'default' ? '⚠' : '✓';
-    
-    output += `${icon} ${tier.padEnd(10)} ${model}\n`;
+    const icon = source === 'not configured' ? '⚠' : '✓';
+    const display = model ?? '(not configured)';
+
+    output += `${icon} ${tier.padEnd(10)} ${display}\n`;
     output += `  Source: ${source}\n\n`;
   }
-  
-  if (resolved.defaultsUsed > 0) {
-    output += '\nNote: Using built-in defaults. To customize:\n';
-    output += '  export CX_MODEL_REASONING=your-model\n';
-    output += '  export CX_MODEL_STANDARD=your-model\n';
-    output += '  export CX_MODEL_FAST=your-model\n';
+
+  const unconfigured = Object.entries(resolved.sources)
+    .filter(([, source]) => source === 'not configured')
+    .map(([tier]) => tier);
+  if (unconfigured.length > 0) {
+    output += `\nUnconfigured: ${unconfigured.join(', ')}. To configure:\n`;
+    output += '  construct models --apply        (interactive, picks from available providers)\n';
+    output += '  export CX_MODEL_REASONING=...   (env override)\n';
+    output += '  export CX_MODEL_STANDARD=...\n';
+    output += '  export CX_MODEL_FAST=...\n';
   }
-  
+
   return output;
 }
 

package/lib/observation-store.mjs

@@ -238,8 +238,12 @@ export async function addObservation(rootDir, {
       return record;
     }
     await client.close();
-  } catch {
-    // Fall through to local vector storage
+  } catch (err) {
+    // A reachable backend that still fails to store (dimension drift, auth, transient
+    // network) must not look identical to "no backend configured" — surface it, then
+    // preserve the observation in the local index so the write never silently vanishes.
+
+    process.stderr.write(`[observation-store] SQL store failed; kept observation in local index: ${err?.message || err}\n`);
   }
 
   // Fallback: local JSON vector index with hashing-bow-v1.

package/lib/opencode-config.mjs

@@ -48,7 +48,7 @@ export function sanitizeOpenCodeConfig(config) {
 
 export function writeOpenCodeConfig(config, file = findOpenCodeConfigPath()) {
   // Treat the canonical home config as the default target; any explicit path
-  // outside the canonical home dir (e.g. project-scoped .opencode/config.json)
+  // outside the canonical home dir (e.g. project-scoped .opencode/opencode.json)
   // is honored as-is so per-project sync writes to the right tree.
 
   const canonical = getCanonicalOpenCodeConfigPath();

package/lib/orchestration/events.mjs

@@ -0,0 +1,66 @@
+/**
+ * lib/orchestration/events.mjs — in-process run lifecycle event bus.
+ *
+ * The orchestration runtime persists runs to a store and appends durable JSONL
+ * traces, but has no live pub/sub a server can stream from. This is that
+ * primitive: a process-local EventEmitter keyed by runId so an HTTP SSE handler
+ * can subscribe to a single run's transitions (planned → running → per-task →
+ * completed) and forward them to a thin client. Events are lightweight status
+ * deltas — never task output or any credential — so the stream stays cheap and
+ * secret-free; clients fetch full run records (envelope-guarded) for outputs.
+ *
+ * Process-local by design: it streams runs executing in THIS process. Durable,
+ * cross-process history lives in the run store and the trace log.
+ */
+
+import { EventEmitter } from 'node:events';
+
+const bus = new EventEmitter();
+bus.setMaxListeners(0);
+
+function channel(runId) {
+  return `run:${runId}`;
+}
+
+/**
+ * Emit a run lifecycle event. Stamps runId + an ISO timestamp; callers pass a
+ * small status delta (type, status, taskId, role, executor, error).
+ *
+ * @param {string} runId
+ * @param {object} event
+ */
+export function emitRunEvent(runId, event = {}) {
+  if (!runId) return;
+  bus.emit(channel(runId), { runId, at: new Date().toISOString(), ...event });
+}
+
+/**
+ * Subscribe to one run's events.
+ *
+ * @param {string} runId
+ * @param {(event:object)=>void} handler
+ * @returns {() => void} unsubscribe
+ */
+export function onRunEvent(runId, handler) {
+  const ch = channel(runId);
+  bus.on(ch, handler);
+  return () => bus.off(ch, handler);
+}
+
+// Cooperative, between-task cancellation. executeRun checks this before each
+// task and stops cleanly if set — an honest soft cancel (it cannot abort a
+// model call already in flight), not a forced kill.
+
+const cancelled = new Set();
+
+export function requestCancel(runId) {
+  if (runId) cancelled.add(runId);
+}
+
+export function isCancelRequested(runId) {
+  return cancelled.has(runId);
+}
+
+export function clearCancel(runId) {
+  cancelled.delete(runId);
+}

package/lib/orchestration/runtime.mjs

@@ -35,12 +35,16 @@ import { routeRequest } from '../orchestration-policy.mjs';
 import { resolveExecution } from '../embedded-contract/execution.mjs';
 import { detectHostCapabilities } from '../host-capabilities.mjs';
 import { loadProjectConfig } from '../config/project-config.mjs';
+import { CHAIN_OF_THOUGHT_MODES } from '../config/schema.mjs';
 import { newTraceId, newSpanId, emitTraceEvent } from '../worker/trace.mjs';
 import { resolveRunStore } from './store.mjs';
 import { runTaskViaProvider, INLINE, PROVIDER, WORKER_BACKEND_SET } from './worker.mjs';
+import { emitRunEvent, isCancelRequested, clearCancel } from './events.mjs';
 
 export const WORKER_BACKENDS = WORKER_BACKEND_SET;
 export const DEFAULT_WORKER_BACKEND = INLINE;
+export const CHAIN_OF_THOUGHT = CHAIN_OF_THOUGHT_MODES;
+export const DEFAULT_CHAIN_OF_THOUGHT = 'hidden';
 
 const RUNTIME_SEMANTICS = 'The inline worker backend owns planning, sequencing, handoff state, persistence, and observability, and prepares each specialist task for a downstream executor. It does not perform specialist LLM reasoning itself; tasks reaching status "prepared" are ready for a worker backend or host to execute. The provider worker backend executes specialist reasoning via the configured model and records real output as task.output.';
 
@@ -97,6 +101,7 @@ function buildTasks(route) {
     status: 'queued',
     executor: null,
     output: null,
+    reasoning: null,
     error: null,
     startedAt: null,
     finishedAt: null,
@@ -112,6 +117,16 @@ function resolveWorkerBackend({ explicit, run, config }) {
   return WORKER_BACKENDS.includes(candidate) ? candidate : DEFAULT_WORKER_BACKEND;
 }
 
+// Chain-of-thought disclosure is a deployment concern (ADR-0030): an explicit
+// option wins, then the run's recorded mode, then config
+// (orchestration.chainOfThought), then the hidden default. An unknown value
+// falls back to hidden — specialist reasoning is never surfaced by guess.
+
+function resolveChainOfThought({ explicit, run, config }) {
+  const candidate = explicit || run?.chainOfThought || config?.orchestration?.chainOfThought || DEFAULT_CHAIN_OF_THOUGHT;
+  return CHAIN_OF_THOUGHT.includes(candidate) ? candidate : DEFAULT_CHAIN_OF_THOUGHT;
+}
+
 function loadConfig(cwd, env) {
   try {
     return loadProjectConfig(cwd, env).config || {};
@@ -147,6 +162,7 @@ export async function planRun(request = {}, { env = process.env, cwd = process.c
   const runId = newRunId();
   const now = new Date().toISOString();
   const workerBackend = resolveWorkerBackend({ config });
+  const chainOfThought = resolveChainOfThought({ config });
 
   // Construct owns a specialist task sequence only when the contract resolves to
   // orchestrated execution; prompt-only and host-direct own none, and the run
@@ -162,6 +178,7 @@ export async function planRun(request = {}, { env = process.env, cwd = process.c
     request: { summary: truncate(text, 200), workflowType, requestedStrategy },
     hostRole: resolveHostRole(host),
     workerBackend,
+    chainOfThought,
     execution: pickExecution(execData),
     plan: {
       intent: route.intent,
@@ -182,6 +199,7 @@ export async function planRun(request = {}, { env = process.env, cwd = process.c
     rootDir: cwd, env, traceId, spanId: newSpanId(), eventType: 'task_graph.created',
     metadata: { runId, executionMode: run.execution.executionMode, specialists: run.plan.specialists, workerBackend: run.workerBackend },
   });
+  emitRunEvent(runId, { type: 'planned', status: 'planned', executionMode: run.execution.executionMode, taskCount: tasks.length });
   return run;
 }
 
@@ -198,25 +216,29 @@ function prepareTaskInline(task) {
 // task is recorded (status `failed`, task.error) and does not abort the run, so
 // one specialist failure cannot lose the work of the others.
 
-async function executeTaskViaProvider(task, run, env, fetchImpl) {
+async function executeTaskViaProvider(task, run, env, fetchImpl, chainOfThought) {
   try {
     const result = await runTaskViaProvider({
       task, run,
       model: run.execution?.selectedModel,
       provider: run.execution?.selectedProvider,
-      env, fetchImpl,
+      env, fetchImpl, chainOfThought,
     });
     task.output = result.output;
     task.executor = `provider:${result.provider}:${result.model}`;
     task.status = 'done';
     task.finishedAt = new Date().toISOString();
-    return true;
+
+    // `surface` attaches reasoning to the task so every display surface renders
+    // it; `telemetry_only` keeps it off the task (recorded only in the trace).
+    if (chainOfThought === 'surface' && result.reasoning) task.reasoning = result.reasoning;
+    return { ok: true, reasoning: result.reasoning || '' };
   } catch (err) {
     task.executor = `provider:error`;
     task.error = { code: err.code || 'PROVIDER_EXECUTION_FAILED', message: err.message };
     task.status = 'failed';
     task.finishedAt = new Date().toISOString();
-    return false;
+    return { ok: false, reasoning: '' };
   }
 }
 
@@ -240,33 +262,51 @@ export async function executeRun(cwd, runId, { env = process.env, workerBackend
   }
 
   const backend = resolveWorkerBackend({ explicit: workerBackend, run, config });
+  const chainOfThought = resolveChainOfThought({ run, config });
   run.workerBackend = backend;
+  run.chainOfThought = chainOfThought;
   run.status = 'running';
   run.updatedAt = new Date().toISOString();
   await store.saveRun(run);
+  emitRunEvent(runId, { type: 'running', status: 'running', workerBackend: backend });
 
   let anyFailed = false;
+  let cancelled = false;
   for (const task of run.tasks) {
+    if (isCancelRequested(runId)) { cancelled = true; break; }
     task.status = 'running';
     task.startedAt = new Date().toISOString();
     emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.started', role: task.role, taskId: task.id, metadata: { runId, workerBackend: backend } });
+    emitRunEvent(runId, { type: 'task', taskId: task.id, role: task.role, status: 'running' });
 
+    let taskReasoning = '';
     if (backend === PROVIDER) {
-      const ok = await executeTaskViaProvider(task, run, env, fetchImpl);
-      if (!ok) anyFailed = true;
+      const res = await executeTaskViaProvider(task, run, env, fetchImpl, chainOfThought);
+      if (!res.ok) anyFailed = true;
+      taskReasoning = res.reasoning;
     } else {
       prepareTaskInline(task);
     }
 
-    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.completed', role: task.role, taskId: task.id, metadata: { runId, status: task.status } });
+    // telemetry_only records reasoning to the trace without ever surfacing it to
+    // a display; surface keeps it off the trace (it rides on task.reasoning).
+    const completedMeta = { runId, status: task.status };
+    if (chainOfThought === 'telemetry_only' && taskReasoning) {
+      completedMeta.reasoning = taskReasoning;
+      completedMeta.reasoningChars = taskReasoning.length;
+    }
+    emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'worker.completed', role: task.role, taskId: task.id, metadata: completedMeta });
+    emitRunEvent(runId, { type: 'task', taskId: task.id, role: task.role, status: task.status, executor: task.executor, ...(task.reasoning ? { reasoning: task.reasoning } : {}), ...(task.error ? { error: task.error } : {}) });
     run.updatedAt = new Date().toISOString();
     await store.saveRun(run);
   }
 
-  run.status = anyFailed ? 'completed-with-failures' : 'completed';
+  run.status = cancelled ? 'cancelled' : (anyFailed ? 'completed-with-failures' : 'completed');
   run.updatedAt = new Date().toISOString();
   await store.saveRun(run);
+  clearCancel(runId);
   emitTraceEvent({ rootDir: cwd, env, traceId: run.traceId, spanId: newSpanId(), eventType: 'lifecycle.completed', metadata: { runId, status: run.status, tasks: run.tasks.length } });
+  emitRunEvent(runId, { type: 'completed', status: run.status });
   return run;
 }
 
@@ -278,6 +318,26 @@ export async function runOrchestration(request = {}, { env = process.env, cwd =
   return executeRun(cwd, planned.runId, { env, workerBackend, fetchImpl });
 }
 
+/**
+ * Start a run for a thin client: plan + persist synchronously, then execute in
+ * the BACKGROUND (not awaited) so the caller gets a runId immediately and tracks
+ * progress via the event stream / run store. Execution failures are caught and
+ * surfaced as a terminal `error` run event rather than an unhandled rejection.
+ *
+ * @param {object} request
+ * @param {object} [opts]   { env, cwd, workerBackend, fetchImpl }
+ * @returns {Promise<object>} the planned run (status `planned`)
+ */
+export async function startRun(request = {}, { env = process.env, cwd = process.cwd(), workerBackend = null, fetchImpl } = {}) {
+  const planned = await planRun(request, { env, cwd });
+  Promise.resolve()
+    .then(() => executeRun(cwd, planned.runId, { env, workerBackend, fetchImpl }))
+    .catch((err) => {
+      emitRunEvent(planned.runId, { type: 'error', status: 'error', error: { code: err.code || 'RUN_FAILED', message: err.message } });
+    });
+  return planned;
+}
+
 /**
  * The structured metadata a host adapter consumes for runtime-backed integration.
  */
@@ -292,12 +352,13 @@ export function hostAdapterMetadata(run) {
     executionMode: e.executionMode,
     constructCapabilitiesActive: e.constructCapabilitiesActive,
     workerBackend: run.workerBackend,
+    chainOfThought: run.chainOfThought ?? null,
     hostRole: run.hostRole,
     degraded: e.degraded,
     degradationReason: e.degradationReason,
     selectedProvider: e.selectedProvider,
     selectedModel: e.selectedModel,
-    tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor })),
+    tasks: (run.tasks || []).map((t) => ({ id: t.id, role: t.role, status: t.status, executor: t.executor, reasoning: t.reasoning ?? null })),
     warnings: run.warnings || [],
     semantics: run.semantics,
     executionSemantics: run.executionSemantics,

package/lib/orchestration/worker.mjs

@@ -32,6 +32,12 @@ export const WORKER_BACKEND_SET = [INLINE, PROVIDER];
 
 const MAX_OUTPUT_TOKENS = 2048;
 
+// Extended-thinking budget requested only when a caller opts into reasoning
+// capture (chainOfThought !== 'hidden'). Anthropic requires budget_tokens < the
+// turn's max_tokens, so the budget is added on top of the output ceiling.
+
+const REASONING_BUDGET_TOKENS = 1024;
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 const PROMPTS_DIR = join(HERE, '..', '..', 'specialists', 'prompts');
 
@@ -46,6 +52,20 @@ function isAnthropic(provider, model) {
   return /anthropic|claude/i.test(provider || '') || /claude/i.test(model || '');
 }
 
+// Extended-thinking shape is model-specific. Opus 4.8 / 4.7 REJECT the legacy
+// `{type:'enabled', budget_tokens}` form with a 400 and require adaptive
+// thinking; Opus 4.6 and Sonnet 4.6 recommend adaptive too. Only genuinely
+// older models (Sonnet 4.5 and earlier) still take the budget form. On adaptive
+// models `display:'summarized'` is required, or returned thinking blocks carry
+// empty text. (Source: claude-api skill — extended/adaptive thinking; ADR-0030.)
+
+function anthropicThinkingConfig(model) {
+  const adaptive = /(opus-4-(?:[6-9]|\d\d)|sonnet-4-(?:[6-9]|\d\d))/i.test(model || '');
+  return adaptive
+    ? { type: 'adaptive', display: 'summarized' }
+    : { type: 'enabled', budget_tokens: REASONING_BUDGET_TOKENS };
+}
+
 // Key resolution mirrors provider-extract: env first, then the two cheap dotenv
 // files, and only when the caller did not inject an explicit env. A caller that
 // passes its own env object (embedded callers, tests) is authoritative and
@@ -93,39 +113,62 @@ async function bodyExcerpt(res) {
   }
 }
 
-async function callAnthropic({ model, apiKey, system, user, fetchImpl }) {
+// OpenRouter normalizes reasoning into a plaintext `reasoning` string and/or a
+// structured `reasoning_details` array (text / summary / encrypted entries). We
+// read the plaintext first, then assemble any readable detail entries; encrypted
+// carriers have no displayable text and are skipped.
+
+function extractOpenRouterReasoning(message) {
+  if (typeof message.reasoning === 'string' && message.reasoning.trim()) return message.reasoning.trim();
+  const details = Array.isArray(message.reasoning_details) ? message.reasoning_details : [];
+  return details.map((d) => d?.text || d?.summary || '').filter(Boolean).join('\n').trim();
+}
+
+async function callAnthropic({ model, apiKey, system, user, fetchImpl, reasoning }) {
+  const thinking = reasoning ? anthropicThinkingConfig(model) : null;
+  const body = {
+    model: model.replace(/^anthropic\//, ''),
+    max_tokens: thinking ? MAX_OUTPUT_TOKENS + REASONING_BUDGET_TOKENS : MAX_OUTPUT_TOKENS,
+    system,
+    messages: [{ role: 'user', content: [{ type: 'text', text: user }] }],
+  };
+  if (thinking) body.thinking = thinking;
   const res = await fetchImpl('https://api.anthropic.com/v1/messages', {
     method: 'POST',
     headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
-    body: JSON.stringify({
-      model: model.replace(/^anthropic\//, ''),
-      max_tokens: MAX_OUTPUT_TOKENS,
-      system,
-      messages: [{ role: 'user', content: [{ type: 'text', text: user }] }],
-    }),
+    body: JSON.stringify(body),
   });
   if (!res.ok) {
     throw providerError('PROVIDER_EXECUTION_FAILED', `Anthropic specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and ANTHROPIC_API_KEY, or set orchestration.workerBackend to "inline".');
   }
   const data = await res.json();
-  return (data.content || []).filter((b) => b && b.type === 'text').map((b) => b.text).join('');
+  const blocks = data.content || [];
+  const output = blocks.filter((b) => b && b.type === 'text').map((b) => b.text).join('');
+  const thought = blocks.filter((b) => b && b.type === 'thinking').map((b) => b.thinking || '').join('').trim();
+  return { output, reasoning: thought };
 }
 
-async function callOpenRouter({ model, apiKey, system, user, fetchImpl }) {
+async function callOpenRouter({ model, apiKey, system, user, fetchImpl, reasoning }) {
+  const body = {
+    model: model.replace(/^openrouter\//, ''),
+    max_tokens: MAX_OUTPUT_TOKENS,
+    messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
+  };
+  // Enable reasoning when wanted; explicitly exclude it otherwise — some models
+  // (e.g. Gemini) return reasoning by default, which would leak in hidden mode.
+  // An empty `{}` is a no-op on OpenRouter; `{enabled:true}` is the on switch.
+  body.reasoning = reasoning ? { enabled: true } : { exclude: true };
   const res = await fetchImpl('https://openrouter.ai/api/v1/chat/completions', {
     method: 'POST',
-    headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', 'HTTP-Referer': 'https://github.com/construct' },
-    body: JSON.stringify({
-      model: model.replace(/^openrouter\//, ''),
-      max_tokens: MAX_OUTPUT_TOKENS,
-      messages: [{ role: 'system', content: system }, { role: 'user', content: user }],
-    }),
+    headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', 'HTTP-Referer': 'https://github.com/geraldmaron/construct' },
+    body: JSON.stringify(body),
   });
   if (!res.ok) {
     throw providerError('PROVIDER_EXECUTION_FAILED', `OpenRouter specialist execution failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and OPENROUTER_API_KEY, or set orchestration.workerBackend to "inline".');
   }
   const data = await res.json();
-  return data.choices?.[0]?.message?.content || '';
+  const message = data.choices?.[0]?.message || {};
+  return { output: message.content || '', reasoning: reasoning ? extractOpenRouterReasoning(message) : '' };
 }
 
 /**
@@ -138,9 +181,12 @@ async function callOpenRouter({ model, apiKey, system, user, fetchImpl }) {
  * @param {string} [opts.provider]      resolved provider id (selects the API)
  * @param {Record<string,string>} [opts.env]
  * @param {Function} [opts.fetchImpl]   injectable fetch (for tests)
- * @returns {Promise<{output:string, model:string, provider:string, characters:number}>}
+ * @param {string} [opts.chainOfThought] reasoning disclosure mode: `hidden` (default,
+ *        no reasoning requested) | `surface` | `telemetry_only` (both request and
+ *        return the model's reasoning for the caller to display or record)
+ * @returns {Promise<{output:string, reasoning:string, model:string, provider:string, characters:number}>}
  */
-export async function runTaskViaProvider({ task, run, model, provider = null, env = process.env, fetchImpl = globalThis.fetch } = {}) {
+export async function runTaskViaProvider({ task, run, model, provider = null, env = process.env, fetchImpl = globalThis.fetch, chainOfThought = 'hidden' } = {}) {
   if (!model) throw providerError('PROVIDER_MODEL_UNRESOLVED', 'Provider worker backend selected but no model resolved.', 'Configure the model tier registry so a model resolves, or set orchestration.workerBackend to "inline".');
   if (typeof fetchImpl !== 'function') throw providerError('PROVIDER_NO_FETCH', 'No fetch implementation available for provider execution.', 'Run on a runtime with global fetch (Node 18+) or inject fetchImpl.');
 
@@ -153,13 +199,15 @@ export async function runTaskViaProvider({ task, run, model, provider = null, en
 
   const system = loadPersona(task?.role);
   const user = buildUserPrompt({ task, run });
-  const output = anthropic
-    ? await callAnthropic({ model, apiKey, system, user, fetchImpl })
-    : await callOpenRouter({ model, apiKey, system, user, fetchImpl });
+  const wantsReasoning = chainOfThought !== 'hidden';
+  const { output, reasoning } = anthropic
+    ? await callAnthropic({ model, apiKey, system, user, fetchImpl, reasoning: wantsReasoning })
+    : await callOpenRouter({ model, apiKey, system, user, fetchImpl, reasoning: wantsReasoning });
 
   const text = output || '';
   return {
     output: text,
+    reasoning: wantsReasoning ? (reasoning || '') : '',
     model,
     provider: anthropic ? 'anthropic' : 'openrouter',
     characters: text.length,

package/lib/orchestration-policy.mjs

@@ -370,9 +370,9 @@ export function formatOverlaySelection(roleFlavors) {
 export function detectRiskFlags(request = '') {
   const text = String(request).toLowerCase();
   return {
-    architecture: containsAny(text, ['architecture', 'interface contract', 'api contract', 'dependency', 'module boundary', 'data model', 'indexing', 'retrieval design']),
-    security: containsAny(text, ['security', 'permission', 'secret', 'privacy', 'payment', 'authentication', 'authorization']),
-    dataIntegrity: containsAny(text, ['migration', 'data', 'sync', 'consistency', 'state']),
+    architecture: containsAny(text, ['architecture', 'interface contract', 'api contract', 'dependency', 'module boundary', 'data model', 'indexing', 'retrieval design', 'terraform', 'infrastructure', 'iac', 'provisioning', 'blast radius', 'rollout', 'deployment strategy']),
+    security: containsAny(text, ['security', 'permission', 'secret', 'privacy', 'payment', 'authentication', 'authorization', 'credential', 'oidc', 'iam', 'access token']),
+    dataIntegrity: containsAny(text, ['migration', 'data', 'sync', 'consistency', 'state', 'tfstate', 'drift']),
     ui: containsAny(text, ['ui', 'ux', 'design system', 'screen', 'layout', 'visual', 'onboarding']) && !containsAny(text, ['requirements']),
     docs: containsAny(text, ['docs', 'readme', 'runbook', 'adr']),
     ai: containsAny(text, ['llm', ' agent', 'prompt', 'rag', 'model behavior', 'retrieval', 'embedding', 'vector']),
@@ -594,6 +594,30 @@ export function buildDispatchPlan({ track, intent, specialists = [] }) {
   return `Plan: ${phases.join(' → ')}.`;
 }
 
+// Format active flavor overlays into a one-line trace, e.g.
+//   "Overlays: architect=platform (matched kubernetes, infra), engineer=ai (matched llm, agent)"
+
+export function formatOverlayTrace(roleFlavors = {}, request = '') {
+  const text = String(request).toLowerCase();
+  const active = Object.entries(roleFlavors).filter(([, flavor]) => flavor);
+  if (active.length === 0) return '';
+  const FLAVOR_KEYWORDS = {
+    architect: ['agent', 'rag', 'retrieval', 'embedding', 'integration', 'webhook', 'warehouse', 'schema', 'sso', 'rbac', 'platform', 'kubernetes', 'infra'],
+    productManager: ['platform', 'api', 'enterprise', 'ai product', 'agent', 'growth', 'activation'],
+    qa: ['agent', 'prompt', 'api', 'sdk', 'pipeline', 'etl', 'ui', 'ux', 'accessibility'],
+    security: ['prompt injection', 'privacy', 'pii', 'dependency', 'cloud', 'iam', 'auth', 'xss', 'csrf'],
+    dataAnalyst: ['experiment', 'a/b', 'telemetry', 'metric', 'funnel'],
+    dataEngineer: ['vector', 'embedding', 'warehouse', 'pipeline', 'etl', 'pgvector'],
+    engineer: ['llm', 'agent', 'rag', 'kubernetes', 'k8s', 'terraform', 'infra', 'docker', 'pipeline', 'etl', 'data model'],
+  };
+  const parts = active.map(([role, flavor]) => {
+    const kws = (FLAVOR_KEYWORDS[role] || []).filter((kw) => text.includes(kw));
+    const matched = kws.slice(0, 3).join(', ');
+    return matched ? `${role}=${flavor} (matched ${matched})` : `${role}=${flavor}`;
+  });
+  return `Overlays: ${parts.join(', ')}`;
+}
+
 export function routeRequest(options = {}) {
   const intent = classifyIntent(options.request);
   const riskFlags = detectRiskFlags(options.request);