@smartmemory/compose 0.1.1-beta → 0.1.3-beta

package/lib/import.js

@@ -9,7 +9,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSy
 import { join, relative, extname, basename } from 'node:path';
 
 import { runAndNormalize } from './result-normalizer.js';
-import { ClaudeSDKConnector } from '../server/connectors/claude-sdk-connector.js';
+import { StratumMcpClient } from './stratum-mcp-client.js';
 
 // ---------------------------------------------------------------------------
 // File tree scanner
@@ -116,12 +116,11 @@ function readKeyFiles(cwd, maxContentSize = 8000) {
  * Scan a project and generate a structured analysis.
  *
  * @param {object} opts
- * @param {string}   [opts.cwd]              - Working directory
- * @param {Function} [opts.connectorFactory] - Override connector (for testing)
+ * @param {string}                 [opts.cwd]      - Working directory
+ * @param {StratumMcpClient}       [opts.stratum]  - Pre-connected client (testing)
  */
 export async function runImport(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
-  const getConnector = opts.connectorFactory ?? (() => new ClaudeSDKConnector({ cwd }));
 
   console.log('Scanning project...\n');
 
@@ -205,15 +204,29 @@ Write the full analysis to \`docs/discovery/project-analysis.md\`.
 
 Return JSON: { "summary": string, "features": [{"code": string, "name": string, "status": string}], "artifact": "docs/discovery/project-analysis.md" }`;
 
-  const connector = getConnector();
-  const { result } = await runAndNormalize(connector, prompt, {
-    output_contract: 'AnalysisResult',
-    output_fields: [
-      { name: 'summary', type: 'string' },
-      { name: 'features', type: 'array' },
-      { name: 'artifact', type: 'string' },
-    ],
-  });
+  let stratum = opts.stratum;
+  let ownsStratum = false;
+  if (!stratum) {
+    stratum = new StratumMcpClient();
+    await stratum.connect({ cwd });
+    ownsStratum = true;
+  }
+
+  let result;
+  try {
+    ({ result } = await runAndNormalize(null, prompt, {
+      step_id: 'import_analyze',
+      agent:   'claude',
+      output_contract: 'AnalysisResult',
+      output_fields: {
+        summary:  'string',
+        features: 'array',
+        artifact: 'string',
+      },
+    }, { stratum, cwd }));
+  } finally {
+    if (ownsStratum) await stratum.close();
+  }
 
   // 6. Verify the analysis was written
   const analysisPath = join(cwd, 'docs', 'discovery', 'project-analysis.md');

package/lib/inject-schema.js

@@ -0,0 +1,21 @@
+/**
+ * inject-schema.js — Append a JSON-Schema instruction block to an agent prompt
+ * so the response includes a structured JSON code-block at the end.
+ */
+
+/**
+ * @param {string} prompt
+ * @param {object} schema  JSON Schema object
+ * @returns {string}
+ */
+export function injectSchema(prompt, schema) {
+  return (
+    `${prompt}\n\n` +
+    `IMPORTANT: After completing the task, include a JSON code block at the very end ` +
+    `of your response matching this schema:\n` +
+    '```json\n' +
+    `${JSON.stringify(schema, null, 2)}\n` +
+    '```\n' +
+    `The JSON block must be the last thing in your response.`
+  );
+}

package/lib/new.js

@@ -12,33 +12,15 @@ import { join, basename } from 'node:path';
 
 import { StratumMcpClient } from './stratum-mcp-client.js';
 import { runAndNormalize } from './result-normalizer.js';
+import { installFactoryShim } from './connector-factory-shim.js';
 import { buildStepPrompt, buildRetryPrompt, buildGateContext } from './step-prompt.js';
 import { promptGate } from './gate-prompt.js';
 import { VisionWriter } from './vision-writer.js';
 
 import { validateStep } from './step-validator.js';
 
-import { ClaudeSDKConnector } from '../server/connectors/claude-sdk-connector.js';
-import { CodexConnector } from '../server/connectors/codex-connector.js';
-
-// ---------------------------------------------------------------------------
-// Agent registry (same as build.js)
-// ---------------------------------------------------------------------------
-
-const DEFAULT_AGENTS = new Map([
-  ['claude', (opts) => new ClaudeSDKConnector(opts)],
-  ['codex', (opts) => new CodexConnector(opts)],
-]);
-
-function defaultConnectorFactory(agentType, opts) {
-  const factory = DEFAULT_AGENTS.get(agentType);
-  if (!factory) throw new Error(`Unknown agent type: ${agentType}`);
-  return factory(opts);
-}
-
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
+// STRAT-DEDUP-AGENTRUN-V3: connectors live in stratum-mcp; runAndNormalize
+// dispatches via stratum.agentRun(...) directly.
 
 /**
  * Run the product kickoff pipeline.
@@ -48,12 +30,10 @@ function defaultConnectorFactory(agentType, opts) {
  * @param {string}   [opts.cwd]              - Working directory (default: process.cwd())
  * @param {string}   [opts.projectName]      - Project name override
  * @param {boolean}  [opts.skipResearch]     - Skip the research step
- * @param {Function} [opts.connectorFactory] - Override agent connector creation (for testing)
  * @param {object}   [opts.gateOpts]         - Options for gate prompt (input/output streams)
  */
 export async function runNew(intent, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
-  const getConnector = opts.connectorFactory ?? defaultConnectorFactory;
   const projectName = opts.projectName ?? basename(cwd);
   const skipResearch = opts.skipResearch ?? false;
 
@@ -116,9 +96,13 @@ export async function runNew(intent, opts = {}) {
   const visionWriter = new VisionWriter(dataDir);
   const itemId = await visionWriter.ensureFeatureItem(projectName, projectName);
 
-  // Stratum MCP client
-  const stratum = new StratumMcpClient();
-  await stratum.connect({ cwd });
+  // Stratum MCP client (test override permitted via opts.stratum)
+  const stratum = opts.stratum ?? new StratumMcpClient();
+  if (!opts.stratum) await stratum.connect({ cwd });
+
+  if (opts.connectorFactory && !opts.stratum) {
+    installFactoryShim(stratum, opts.connectorFactory, cwd);
+  }
 
   try {
     console.log(`Starting product kickoff for "${projectName}"...`);
@@ -144,19 +128,18 @@ export async function runNew(intent, opts = {}) {
 
         const agentType = response.agent ?? 'claude';
         const prompt = buildStepPrompt(response, context);
-        const connector = getConnector(agentType, { cwd });
-        const { result } = await runAndNormalize(connector, prompt, response);
+        const { result } = await runAndNormalize(null, prompt, response, { stratum, cwd });
 
         // Agent-as-validator: if step has validate config, check the artifact
         const valConfig = validateConfigs.get(stepId);
         if (valConfig) {
           console.log(`  ✓ Validating ${stepId}...`);
-          const valConnector = getConnector('claude', { cwd });
           const { valid, issues } = await validateStep({
             artifact: valConfig.artifact,
             criteria: valConfig.criteria,
             stepId,
-            connector: valConnector,
+            stratum,
+            cwd,
           });
           if (!valid) {
             console.log(`  ✗ Validation failed:`);
@@ -167,8 +150,8 @@ export async function runNew(intent, opts = {}) {
               issues.map(i => `- ${i}`).join('\n') + '\n\n' +
               `Update the file in place. Do not skip any issue.\n\n` +
               `## Context\nWorking directory: ${cwd}\nProject: ${projectName}`;
-            const fixConnector = getConnector('claude', { cwd });
-            await runAndNormalize(fixConnector, fixPrompt, response);
+            const fixDispatch = { ...response, agent: 'claude' };
+            await runAndNormalize(null, fixPrompt, fixDispatch, { stratum, cwd });
           }
         }
 
@@ -224,7 +207,6 @@ export async function runNew(intent, opts = {}) {
         // Agent Q&A callback for interactive gate — with full workflow context
         const gatePreamble = buildGateContext(response, context, null);
         const askAgent = async (question, artifactPath) => {
-          const connector = getConnector('claude', { cwd });
           const fileRef = artifactPath
             ? `Read the file "${artifactPath}" and answer`
             : `Look at the project files in the working directory and answer`;
@@ -233,12 +215,8 @@ export async function runNew(intent, opts = {}) {
             `${fileRef} this question concisely:\n\n` +
             `${question}\n\n` +
             `Keep your answer brief — 2-3 sentences max.`;
-          const parts = [];
-          for await (const event of connector.run(qaPrompt, {})) {
-            if (event.type === 'assistant' && event.content) parts.push(event.content);
-            if (event.type === 'result' && event.content && parts.length === 0) parts.push(event.content);
-          }
-          return parts.join('') || '(no answer)';
+          const text = await stratum.runAgentText('claude', qaPrompt, { cwd });
+          return text || '(no answer)';
         };
 
         const { outcome, rationale } = await promptGate(response, {
@@ -266,7 +244,7 @@ export async function runNew(intent, opts = {}) {
         console.log(`[sub-flow] ${childFlowName}...`);
 
         const childResult = await executeChildFlow(
-          response, stratum, getConnector, context,
+          response, stratum, context,
           visionWriter, itemId, opts.gateOpts ?? {}
         );
 
@@ -285,13 +263,12 @@ export async function runNew(intent, opts = {}) {
           violations.map(v => `- ${v}`).join('\n') + '\n\n' +
           `Fix every issue. Do not skip any.\n\n` +
           `## Context\nWorking directory: ${cwd}\nProject: ${projectName}`;
-        const fixConnector = getConnector(fixAgent, { cwd });
-        await runAndNormalize(fixConnector, fixPrompt, response);
+        const fixDispatch = { ...response, agent: fixAgent };
+        await runAndNormalize(null, fixPrompt, fixDispatch, { stratum, cwd });
 
         console.log(`  ↻ Retrying ${stepId} (${agentType})`);
         const prompt = buildRetryPrompt(response, violations, context);
-        const connector = getConnector(agentType, { cwd });
-        const { result } = await runAndNormalize(connector, prompt, response);
+        const { result } = await runAndNormalize(null, prompt, response, { stratum, cwd });
 
         response = await stratum.stepDone(
           response.flow_id, response.step_id,
@@ -341,7 +318,7 @@ export async function runNew(intent, opts = {}) {
 // ---------------------------------------------------------------------------
 
 async function executeChildFlow(
-  flowDispatch, stratum, getConnector, context,
+  flowDispatch, stratum, context,
   visionWriter, itemId, gateOpts
 ) {
   let resp = flowDispatch.child_step;
@@ -353,10 +330,8 @@ async function executeChildFlow(
       console.log(`  [${childFlowName}] ${resp.step_id}...`);
       await visionWriter.updateItemPhase(itemId, `${childFlowName}:${resp.step_id}`);
 
-      const agentType = resp.agent ?? 'claude';
       const prompt = buildStepPrompt(resp, context);
-      const connector = getConnector(agentType, { cwd: context.cwd });
-      const { result } = await runAndNormalize(connector, prompt, resp);
+      const { result } = await runAndNormalize(null, prompt, resp, { stratum, cwd: context.cwd });
 
       resp = await stratum.stepDone(
         childFlowId, resp.step_id,
@@ -381,13 +356,12 @@ async function executeChildFlow(
         violations.map(v => `- ${v}`).join('\n') + '\n\n' +
         `Fix every issue.\n\n` +
         `## Context\nWorking directory: ${context.cwd}\nProject: ${context.projectName}`;
-      const fixConnector = getConnector(fixAgent, { cwd: context.cwd });
-      await runAndNormalize(fixConnector, fixPrompt, resp);
+      const fixDispatch = { ...resp, agent: fixAgent };
+      await runAndNormalize(null, fixPrompt, fixDispatch, { stratum, cwd: context.cwd });
 
       console.log(`  [${childFlowName}] ↻ Retrying ${resp.step_id} (${stepAgent})`);
       const prompt = buildRetryPrompt(resp, violations, context);
-      const connector = getConnector(stepAgent, { cwd: context.cwd });
-      const { result } = await runAndNormalize(connector, prompt, resp);
+      const { result } = await runAndNormalize(null, prompt, resp, { stratum, cwd: context.cwd });
 
       resp = await stratum.stepDone(
         resp.flow_id ?? childFlowId, resp.step_id,
@@ -398,7 +372,7 @@ async function executeChildFlow(
       const nestedParentFlowId = resp.parent_flow_id;
       const nestedParentStepId = resp.parent_step_id;
       const nestedResult = await executeChildFlow(
-        resp, stratum, getConnector, context,
+        resp, stratum, context,
         visionWriter, itemId, gateOpts
       );
       resp = await stratum.stepDone(nestedParentFlowId, nestedParentStepId, nestedResult);

package/lib/result-normalizer.js

@@ -6,9 +6,12 @@
  * accumulates text, and extracts structured JSON from the response.
  */
 
-import { injectSchema } from '../server/connectors/agent-connector.js';
+import { randomUUID } from 'node:crypto';
+import { injectSchema } from './inject-schema.js';
 import { CliProgress } from './cli-progress.js';
 import { calculateCost } from './model-pricing.js';
+import { resolveAgentConfig } from './agent-string.js';
+import { normalizeReviewResult } from './review-normalize.js';
 
 // ---------------------------------------------------------------------------
 // Error classes
@@ -146,26 +149,50 @@ export class AgentTimeoutError extends Error {
   }
 }
 
-export async function runAndNormalize(connector, prompt, stepDispatch, opts = {}) {
+/**
+ * STRAT-DEDUP-AGENTRUN-V3: `runAndNormalize` is now a thin wrapper around the
+ * Python connector tier exposed through `stratum_agent_run`. Events arrive as
+ * BuildStreamEvent envelopes via MCP progress notifications; we subscribe with
+ * `stratum.onEvent(correlationId, '_agent_run', handler)` and translate the
+ * envelopes back into the legacy stream-writer shape so downstream consumers
+ * (build-stream-writer, cockpit) keep working unchanged.
+ *
+ * The first `connector` arg is intentionally ignored — kept only so the 18
+ * call-sites do not all need to be edited in a single sweep. New required opt:
+ * `opts.stratum` — the StratumMcpClient instance.
+ */
+export async function runAndNormalize(_connectorIgnored, prompt, stepDispatch, opts = {}) {
   const progress = opts.progress;
   const streamWriter = opts.streamWriter;
-  const onToolUse = opts.onToolUse ?? null; // passive tap — Item 193
-  const maxDurationMs = opts.maxDurationMs ?? null; // null = no timeout
+  const onToolUse = opts.onToolUse ?? null;
+  const maxDurationMs = opts.maxDurationMs ?? null;
+  const stratum = opts.stratum;
+
+  if (!stratum || typeof stratum.agentRun !== 'function') {
+    throw new AgentError(
+      'runAndNormalize requires opts.stratum (a connected StratumMcpClient). ' +
+      'Pass stratum: stratumClient at the call-site.'
+    );
+  }
+
+  const stepId = stepDispatch.step_id ?? 'unknown';
+  const agentType = stepDispatch.agent ?? 'claude';
+  const cfg = resolveAgentConfig(agentType);
+
   const outputFields = stepDispatch.output_fields;
   const hasSchema = outputFields && typeof outputFields === 'object' && Object.keys(outputFields).length > 0;
-
   let actualPrompt = prompt;
   let schema = null;
-
   if (hasSchema) {
     schema = outputFieldsToJsonSchema(outputFields);
     actualPrompt = injectSchema(prompt, schema);
   }
 
-  const textParts = [];
+  const correlationId = `${stepDispatch.flow_id ?? 'noflow'}:${stepId}:${randomUUID()}`;
+  const subStepId = '_agent_run';
   const startTime = Date.now();
 
-  // Accumulate usage events across all connector events
+  const textParts = [];
   const usageTotals = {
     input_tokens: 0,
     output_tokens: 0,
@@ -175,157 +202,148 @@ export async function runAndNormalize(connector, prompt, stepDispatch, opts = {}
     model: null,
   };
 
-  // Set up timeout timer if configured
-  let timeoutTimer = null;
   let timedOut = false;
+  let userInterruptAction = null;
+  let timeoutHandle = null;
+
+  // Subscribe BEFORE calling agentRun — events fire during the call.
+  const unsub = stratum.onEvent(correlationId, subStepId, (env) => {
+    if (!env || env.schema_version !== '0.2.5') return;
+    const m = env.metadata ?? {};
+    switch (env.kind) {
+      case 'agent_relay':
+        if (m.role === 'assistant' && typeof m.text === 'string' && m.text.length > 0) {
+          textParts.push(m.text);
+          if (streamWriter) streamWriter.write({ type: 'assistant', content: m.text });
+        }
+        break;
+      case 'tool_use_summary': {
+        const tool = m.tool;
+        if (tool) {
+          if (streamWriter) {
+            streamWriter.write({ type: 'tool_use', tool, input: m.input ?? {} });
+          }
+          if (onToolUse) onToolUse({ tool, input: m.input ?? {}, timestamp: Date.now() });
+          if (progress) {
+            const detail = m.input?.command ?? m.input?.pattern ?? m.input?.query ?? m.input?.file_path ?? '';
+            progress.toolUse(tool, detail);
+          }
+        }
+        if (m.summary) {
+          if (streamWriter) {
+            streamWriter.write({ type: 'tool_use_summary', summary: m.summary, output: m.output ?? '' });
+          }
+          if (progress) progress.toolSummary(m.summary);
+        }
+        break;
+      }
+      case 'step_usage': {
+        const inTok  = m.input_tokens ?? 0;
+        const outTok = m.output_tokens ?? 0;
+        const ccit   = m.cache_creation_input_tokens ?? 0;
+        const crit   = m.cache_read_input_tokens ?? 0;
+        usageTotals.input_tokens               += inTok;
+        usageTotals.output_tokens              += outTok;
+        usageTotals.cache_creation_input_tokens += ccit;
+        usageTotals.cache_read_input_tokens     += crit;
+        if (m.model) usageTotals.model = m.model;
+        const stepCost = m.cost_usd != null
+          ? m.cost_usd
+          : calculateCost(m.model, inTok, outTok, ccit, crit);
+        usageTotals.cost_usd += stepCost;
+        if (streamWriter) {
+          streamWriter.write({
+            type: 'usage',
+            input_tokens: inTok,
+            output_tokens: outTok,
+            cache_creation_input_tokens: ccit,
+            cache_read_input_tokens: crit,
+            cost_usd: stepCost,
+            model: m.model ?? null,
+          });
+        }
+        break;
+      }
+      default:
+        break;
+    }
+  });
+
   if (maxDurationMs) {
-    timeoutTimer = setTimeout(() => {
+    timeoutHandle = setTimeout(() => {
       timedOut = true;
-      try { connector.interrupt(); } catch { /* best effort */ }
+      stratum.cancelAgentRun(correlationId).catch(() => {});
     }, maxDurationMs);
   }
 
-  // Wire up skip/retry interrupt from CLI key press
-  let userInterrupted = false;
-  const onInterrupt = () => {
-    userInterrupted = true;
-    try { connector.interrupt(); } catch { /* best effort */ }
-  };
-  if (progress?.on) progress.on('interrupt', onInterrupt);
+  let onInterrupt = null;
+  if (progress?.on) {
+    onInterrupt = () => {
+      userInterruptAction = progress.consumeAction?.() ?? 'skip';
+      stratum.cancelAgentRun(correlationId).catch(() => {});
+    };
+    progress.on('interrupt', onInterrupt);
+  }
 
+  let runResult;
   try {
-  for await (const event of connector.run(actualPrompt, {})) {
-    // Check for timeout after each event
-    if (timedOut) {
-      const stepId = stepDispatch.step_id ?? 'unknown';
-      throw new AgentTimeoutError(stepId, Date.now() - startTime);
-    }
-    // Check for user interrupt (skip/retry)
-    if (userInterrupted) {
-      const stepId = stepDispatch.step_id ?? 'unknown';
-      throw new UserInterruptError(stepId, progress?.consumeAction() ?? 'skip');
-    }
-    if (progress) {
-      progress.debug(`event type=${event.type} keys=${Object.keys(event).join(',')}`);
-    } else if (process.env.COMPOSE_DEBUG) {
-      process.stderr.write(`  [event] type=${event.type} keys=${Object.keys(event).join(',')}\n`);
-    }
-    if (event.type === 'error') {
-      // build_error is written by build.js catch blocks, not here — avoids duplicate events
-      throw new AgentError(event.message);
-    }
-    if (event.type === 'assistant' && event.content) {
-      textParts.push(event.content);
-      if (streamWriter) {
-        streamWriter.write({ type: 'assistant', content: event.content });
-      }
-    }
-    if (event.type === 'result' && event.content) {
-      // Result contains the final aggregated text — use it if we got nothing from blocks
-      if (textParts.length === 0) {
-        textParts.push(event.content);
-      }
-    }
-    // Forward tool_use to build stream (before progress logging)
-    if (streamWriter && event.type === 'tool_use' && event.tool) {
-      streamWriter.write({ type: 'tool_use', tool: event.tool, input: event.input });
-    }
-    // Passive tap — notify caller of each tool_use without altering event flow (Item 193)
-    if (onToolUse && event.type === 'tool_use' && event.tool) {
-      onToolUse({ tool: event.tool, input: event.input, timestamp: Date.now() });
-    }
-    // Progress logging — show tool calls so the user sees activity
-    if (event.type === 'tool_use' && event.tool) {
-      const detail = event.input?.command
-        ?? event.input?.pattern
-        ?? event.input?.query
-        ?? event.input?.file_path
-        ?? '';
-      if (progress) {
-        progress.toolUse(event.tool, detail);
-      } else {
-        const short = typeof detail === 'string' && detail.length > 60
-          ? detail.slice(0, 57) + '...'
-          : detail;
-        process.stderr.write(`    ↳ ${event.tool}${short ? ': ' + short : ''}\n`);
-      }
-    }
-    // Forward tool_use_summary to build stream (COMP-OBS-STREAM)
-    if (streamWriter && event.type === 'tool_use_summary') {
-      streamWriter.write({ type: 'tool_use_summary', summary: event.summary, output: event.output });
-    }
-    if (event.type === 'tool_use_summary' && event.summary) {
-      if (progress) {
-        progress.toolSummary(event.summary);
-      } else {
-        const short = event.summary.length > 80
-          ? event.summary.slice(0, 77) + '...'
-          : event.summary;
-        process.stderr.write(`    ↳ ${short}\n`);
-      }
-    }
-    // Forward tool_progress to build stream (COMP-OBS-STREAM)
-    if (streamWriter && event.type === 'tool_progress') {
-      streamWriter.write({ type: 'tool_progress', tool: event.tool, elapsed: event.elapsed });
-    }
-    if (event.type === 'tool_progress' && event.tool) {
-      if (progress) {
-        progress.toolProgress(event.tool, event.elapsed);
-      } else {
-        process.stderr.write(`    ↳ ${event.tool} (${Math.round(event.elapsed)}s)\n`);
-      }
-    }
-    // Accumulate usage events (COMP-OBS-COST)
-    if (event.type === 'usage') {
-      usageTotals.input_tokens += event.input_tokens ?? 0;
-      usageTotals.output_tokens += event.output_tokens ?? 0;
-      usageTotals.cache_creation_input_tokens += event.cache_creation_input_tokens ?? 0;
-      usageTotals.cache_read_input_tokens += event.cache_read_input_tokens ?? 0;
-      if (event.model) usageTotals.model = event.model;
-      // If the connector already computed cost_usd, use it; otherwise calculate
-      const stepCost = event.cost_usd != null
-        ? event.cost_usd
-        : calculateCost(
-            event.model,
-            event.input_tokens ?? 0,
-            event.output_tokens ?? 0,
-            event.cache_creation_input_tokens ?? 0,
-            event.cache_read_input_tokens ?? 0,
-          );
-      usageTotals.cost_usd += stepCost;
-      // Forward per-step usage to build stream
-      if (streamWriter) {
-        streamWriter.write({
-          type: 'usage',
-          input_tokens: event.input_tokens ?? 0,
-          output_tokens: event.output_tokens ?? 0,
-          cache_creation_input_tokens: event.cache_creation_input_tokens ?? 0,
-          cache_read_input_tokens: event.cache_read_input_tokens ?? 0,
-          cost_usd: stepCost,
-          model: event.model ?? null,
-        });
-      }
-    }
-  }
+    runResult = await stratum.agentRun(agentType, actualPrompt, {
+      modelID:          cfg.modelID ?? undefined,
+      allowedTools:     cfg.allowedTools ?? undefined,
+      disallowedTools:  cfg.disallowedTools ?? undefined,
+      thinking:         cfg.thinking ?? undefined,
+      effort:           cfg.effort ?? undefined,
+      cwd:              opts.cwd ?? undefined,
+      correlationId,
+    });
+  } catch (err) {
+    if (timedOut) throw new AgentTimeoutError(stepId, Date.now() - startTime);
+    if (userInterruptAction) throw new UserInterruptError(stepId, userInterruptAction);
+    throw new AgentError(err?.message ?? 'Agent run failed');
   } finally {
-    if (timeoutTimer) clearTimeout(timeoutTimer);
-    if (progress?.removeListener) progress.removeListener('interrupt', onInterrupt);
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+    if (onInterrupt && progress?.removeListener) progress.removeListener('interrupt', onInterrupt);
+    unsub();
   }
 
-  // If we broke out of the loop due to timeout, throw
-  if (timedOut) {
-    const stepId = stepDispatch.step_id ?? 'unknown';
-    throw new AgentTimeoutError(stepId, Date.now() - startTime);
-  }
+  if (timedOut) throw new AgentTimeoutError(stepId, Date.now() - startTime);
+  if (userInterruptAction) throw new UserInterruptError(stepId, userInterruptAction);
 
-  const text = textParts.join('');
+  const text = (runResult && typeof runResult.text === 'string' && runResult.text.length > 0)
+    ? runResult.text
+    : textParts.join('');
 
   if (progress) {
     progress.debug(`normalizer: textParts=${textParts.length}, text length=${text.length}`);
     if (text.length > 0) progress.debug(`text preview: ${text.slice(0, 300)}`);
   } else if (process.env.COMPOSE_DEBUG) {
-    process.stderr.write(`  [normalizer] textParts count: ${textParts.length}, text length: ${text.length}\n`);
-    if (text.length > 0) process.stderr.write(`  [normalizer] text preview: ${text.slice(0, 300)}\n`);
+    process.stderr.write(`  [normalizer] textParts=${textParts.length}, text length=${text.length}\n`);
+  }
+
+  // review_mode hook — MUST be before the !hasSchema early return (MF-3 in blueprint).
+  // Parallel lens steps often have empty output_fields (hasSchema=false), but review
+  // normalization must still run. The Stratum server validates the post-normalize result
+  // via `ensure` expressions after stratum_step_done — not against raw text.
+  if (opts.reviewMode === true) {
+    const reviewAgentType = agentType; // already resolved from stepDispatch.agent at line 178
+    const reviewModelId = usageTotals.model ?? cfg.modelID ?? null;
+    const repairFn = stratum
+      ? async (repairPrompt) => {
+          const repairResult = await stratum.agentRun(reviewAgentType, repairPrompt, {
+            modelID: cfg.modelID ?? undefined,
+            cwd: opts.cwd ?? undefined,
+          });
+          return repairResult?.text ?? '';
+        }
+      : undefined;
+    const reviewResult = await normalizeReviewResult(text, {
+      agentType: reviewAgentType,
+      modelId: reviewModelId,
+      confidenceGate: opts.confidenceGate ?? 7,
+      lens: opts.lens ?? 'general',
+      repairFn,
+    });
+    return { text, result: reviewResult, usage: usageTotals };
   }
 
   if (!hasSchema) {
@@ -334,8 +352,6 @@ export async function runAndNormalize(connector, prompt, stepDispatch, opts = {}
 
   const result = extractJson(text);
   if (result === null) {
-    // Agent did its work but didn't return structured JSON.
-    // Log a warning and return a fallback — don't crash the pipeline.
     if (progress) {
       progress.warn('Could not extract JSON from agent output, using fallback');
     } else {