fix(build): improve build command validation, types, and codex integration

CLI improvements:
- Require task description (no misleading default)
- Add --dry-run flag, clarify --execute default
- Add proper types (HarnessResult, PlanStep) to printInteractionLog
- Extract duplicate task resolution logic

Harness improvements:
- Make heuristicPlan generic (not hardcoded to multi-agent harness)
- Implement all plan steps in prompt (not just first one)
- Increase max_tokens from 1200 to 4096

Provider improvements:
- Fix codex binary detection (check codex-sm, codex, codex-cli)
- Use first available binary instead of hardcoded codex-sm
- Fix unsafe type coercion with proper type guard

Wrapper improvements:
- Use exec for full TTY control in claude-code-wrapper.sh
- Fix argument parsing for wrapper-specific flags

Also renames mm-spike paths to build for consistency.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: StackMemory Bot (CLI)

docs/SETUP.md

@@ -97,7 +97,7 @@ CLI equivalents for quick checks:
 
 ```bash
 # Quiet JSON (UI-friendly)
-stackmemory mm-spike --task "Refactor config loader" --json
+stackmemory build --task "Refactor config loader" --json
 
 # Execute implementer and record as frame
 stackmemory skills spike --task "Refactor" --execute --max-iters 3 --json --record-frame

docs/mcp.md

@@ -69,14 +69,14 @@ Response content is a single `text` item containing a JSON string:
 
 ## Notes
 - Implementer `codex` calls `codex-sm` (must be on PATH). Use `--execute` in CLI, or `execute: true` in MCP, to actually run it; otherwise it’s a dry‑run.
-- Audit files are saved to `.stackmemory/mm-spike/spike-<timestamp>.json` to support review/debugging.
+- Audit files are saved to `.stackmemory/build/spike-<timestamp>.json` to support review/debugging.
 - You can compare models:
   - Planner/critic: override with `STACKMEMORY_MM_PLANNER_MODEL` / `STACKMEMORY_MM_REVIEWER_MODEL`.
   - Implementer: set to `claude` to A/B against Codex, or keep `codex` (default).
 
 ## CLI equivalents (for quick checks)
 - Quiet JSON output:
-  - `stackmemory mm-spike --task "Refactor config loader" --json`
+  - `stackmemory build "Refactor config loader" --json`
   - `stackmemory skills spike --task "Refactor config loader" --json`
 - Execute implementer and record as frame:
   - `stackmemory skills spike --task "Refactor" --execute --max-iters 3 --json --record-frame`
@@ -154,7 +154,7 @@ Response (content[0].text is a JSON string):
 Notes:
 - `recordFrame: true` creates a real StackMemory frame + anchors (plan summary, commands, issues, suggestions).
 - `execute: true` actually invokes the implementer; otherwise it’s a dry‑run.
-- Approval IDs are persisted to `.stackmemory/mm-spike/pending.json` so editor restarts don’t lose pending approvals.
+- Approval IDs are persisted to `.stackmemory/build/pending.json` so editor restarts don’t lose pending approvals.
 
 ### Optional helper tools
 - `plan_only`: Returns a plan JSON without running code.

scripts/claude-code-wrapper.sh

@@ -3,62 +3,50 @@
 # Claude Code wrapper with StackMemory integration
 # Usage: Add alias to ~/.zshrc: alias claude='~/Dev/stackmemory/scripts/claude-code-wrapper.sh'
 
-# Check for auto-sync flag
+# Check for auto-sync flag and filter wrapper-specific args
 AUTO_SYNC=false
 SYNC_INTERVAL=5
+CLAUDE_ARGS=()
+
 for arg in "$@"; do
     case $arg in
         --auto-sync)
             AUTO_SYNC=true
-            shift
             ;;
         --sync-interval=*)
             SYNC_INTERVAL="${arg#*=}"
-            shift
+            ;;
+        *)
+            CLAUDE_ARGS+=("$arg")
             ;;
     esac
 done
 
-# Start Linear auto-sync in background if requested
-SYNC_PID=""
+# Start Linear auto-sync in background if requested (survives exec)
 if [ "$AUTO_SYNC" = true ] && [ -n "$LINEAR_API_KEY" ]; then
     echo "🔄 Starting Linear auto-sync (${SYNC_INTERVAL}min intervals)..."
-    (
+    nohup bash -c "
         while true; do
             sleep $((SYNC_INTERVAL * 60))
-            if [ -d ".stackmemory" ]; then
+            if [ -d \"$PWD/.stackmemory\" ]; then
                 stackmemory linear sync --quiet 2>/dev/null || true
             fi
         done
-    ) &
-    SYNC_PID=$!
+    " > /dev/null 2>&1 &
+    disown
 fi
 
-cleanup() {
-    echo "📝 Saving StackMemory context..."
-    
-    # Kill auto-sync if running
-    if [ -n "$SYNC_PID" ] && kill -0 $SYNC_PID 2>/dev/null; then
-        echo "🛑 Stopping auto-sync..."
-        kill $SYNC_PID 2>/dev/null || true
-    fi
-    
-    # Check if in a git repo with stackmemory
-    if [ -d ".stackmemory" ] && [ -f "stackmemory.json" ]; then
-        # Save current context (without sync)
-        stackmemory status 2>/dev/null || true
-        echo "✅ StackMemory context saved"
-    fi
-}
+# Note: Cleanup is now handled by Claude hooks instead of this wrapper
+# See: stackmemory setup-hooks --cleanup
 
-# Set trap for exit signals
-trap cleanup EXIT INT TERM
+# Run Claude Code with exec for full TTY control (interactive mode)
+# This replaces the shell process, ensuring stdin works properly
+# Note: cleanup trap won't run with exec - use Claude hooks for session cleanup instead
 
-# Run Claude Code (try multiple possible command names)
 if command -v claude-code &> /dev/null; then
-    claude-code "$@"
+    exec claude-code "${CLAUDE_ARGS[@]}"
 elif command -v claude &> /dev/null; then
-    claude "$@"
+    exec claude "${CLAUDE_ARGS[@]}"
 else
     echo "❌ Claude Code not found. Please install it first."
     echo "   Visit: https://github.com/anthropics/claude-code"

src/cli/index.ts

@@ -67,9 +67,12 @@ import Database from 'better-sqlite3';
 import { join } from 'path';
 import { existsSync, mkdirSync } from 'fs';
 import inquirer from 'inquirer';
-import chalk from 'chalk';
 import { enableChromaDB } from '../core/config/storage-config.js';
 import { spawn } from 'child_process';
+import type {
+  HarnessResult,
+  PlanStep,
+} from '../orchestrators/multimodal/types.js';
 import { homedir } from 'os';
 
 // Read version from package.json - works from both src/ and dist/src/
@@ -903,16 +906,124 @@ program
     }
   });
 
-function printInteractionLog(
-  meta: {
-    task: string;
-    plannerModel: string;
-    reviewerModel: string;
-    implementer: string;
-    execute: boolean;
-  },
-  result: any
-) {
+// Alias: build (same behavior as mm-spike)
+program
+  .command('build')
+  .description(
+    'Plan + code: planner (Claude), implementer (Codex/Claude), critic (Claude) with optional log/json output'
+  )
+  .argument('[task]', 'Task description (positional)')
+  .option(
+    '-t, --task <desc>',
+    'Task description (required if no positional arg)'
+  )
+  .option(
+    '--planner-model <name>',
+    'Claude model for planning',
+    'claude-3-5-sonnet-latest'
+  )
+  .option(
+    '--reviewer-model <name>',
+    'Claude model for review',
+    'claude-3-5-sonnet-latest'
+  )
+  .option('--execute', 'Execute implementer (default: true)', true)
+  .option('--dry-run', 'Skip execution, show commands only')
+  .option('--implementer <name>', 'codex|claude', 'codex')
+  .option('--max-iters <n>', 'Retry loop iterations', '2')
+  .option('--audit-dir <path>', 'Persist spike results to directory')
+  .option('--record-frame', 'Record as real frame with anchors')
+  .option('--record', 'Record plan & critique into StackMemory context')
+  .option('--json', 'Emit single JSON result (UI-friendly)')
+  .option('--quiet', 'Minimal output')
+  .option('--verbose', 'Verbose sectioned output')
+  .option('--log', 'Pretty print interaction log (default: true)', true)
+  .action(async (taskArg, opts) => {
+    try {
+      // Resolve task from positional arg or --task option
+      const task =
+        typeof taskArg === 'string' && taskArg.length > 0 ? taskArg : opts.task;
+
+      if (!task) {
+        console.error(
+          chalk.red(
+            'Error: Task description required. Provide as argument or --task option.'
+          )
+        );
+        console.error(
+          chalk.gray('  Example: stackmemory build "Add user authentication"')
+        );
+        process.exit(1);
+      }
+
+      const { runSpike } =
+        await import('../orchestrators/multimodal/harness.js');
+      const dryRun = opts.dryRun === true || opts.execute === false;
+      const result = await runSpike(
+        { task, repoPath: process.cwd() },
+        {
+          plannerModel: opts.plannerModel,
+          reviewerModel: opts.reviewerModel,
+          implementer: opts.implementer,
+          maxIters: parseInt(opts.maxIters),
+          dryRun,
+          auditDir: opts.auditDir,
+          recordFrame: Boolean(opts.recordFrame),
+          record: Boolean(opts.record),
+        }
+      );
+
+      if (opts.log) {
+        printInteractionLog(
+          {
+            task,
+            plannerModel: opts.plannerModel,
+            reviewerModel: opts.reviewerModel,
+            implementer: opts.implementer,
+            execute: !dryRun,
+          },
+          result
+        );
+        return;
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(result));
+        return;
+      }
+      if (opts.verbose) {
+        console.log('\n=== Plan ===');
+        console.log(JSON.stringify(result.plan, null, 2));
+        console.log('\n=== Iterations ===');
+        (result.iterations || []).forEach((it, i) => {
+          console.log(`\n[Attempt ${i + 1}] ${it.command}`);
+          console.log('OK:', it.ok);
+          console.log('Critique:', JSON.stringify(it.critique));
+        });
+        console.log('\n=== Implementation ===');
+        console.log(JSON.stringify(result.implementation, null, 2));
+        console.log('\n=== Critique ===');
+        console.log(JSON.stringify(result.critique, null, 2));
+      } else if (!opts.quiet) {
+        console.log(
+          `Plan steps: ${result.plan.steps.length}, Approved: ${result.critique.approved}`
+        );
+      }
+    } catch (error) {
+      console.error('build failed:', (error as Error).message);
+      process.exit(1);
+    }
+  });
+
+interface BuildLogMeta {
+  task: string;
+  plannerModel: string;
+  reviewerModel: string;
+  implementer: string;
+  execute: boolean;
+}
+
+function printInteractionLog(meta: BuildLogMeta, result: HarnessResult): void {
   const divider = chalk.gray(
     '────────────────────────────────────────────────'
   );
@@ -928,65 +1039,55 @@ function printInteractionLog(
   console.log(divider);
 
   // Plan summary
-  if (result?.plan) {
+  if (result.plan) {
     console.log(
       chalk.bold('Plan Summary: '),
       result.plan.summary || '(no summary)'
     );
-    const steps = Array.isArray(result.plan.steps)
-      ? result.plan.steps.slice(0, 6)
-      : [];
+    const steps: PlanStep[] = result.plan.steps.slice(0, 6);
     if (steps.length) {
       console.log(chalk.bold('\nSteps:'));
-      steps.forEach((s: any, idx: number) => {
+      steps.forEach((s, idx) => {
         console.log(`${chalk.gray(String(idx + 1) + '.')} ${s.title || s.id}`);
-        const ac = Array.isArray(s.acceptanceCriteria)
-          ? s.acceptanceCriteria
-          : [];
+        const ac = s.acceptanceCriteria || [];
         if (ac.length) {
-          ac.slice(0, 3).forEach((c: string) =>
-            console.log(chalk.gray(`   - ${c}`))
-          );
+          ac.slice(0, 3).forEach((c) => console.log(chalk.gray(`   - ${c}`)));
           if (ac.length > 3) console.log(chalk.gray('   - ...'));
         }
       });
     }
-    if (Array.isArray(result.plan.risks) && result.plan.risks.length) {
+    if (result.plan.risks?.length) {
       console.log(chalk.bold('\nRisks:'));
       result.plan.risks
         .slice(0, 5)
-        .forEach((r: string) => console.log(chalk.gray(` - ${r}`)));
+        .forEach((r) => console.log(chalk.gray(` - ${r}`)));
     }
   }
 
   console.log(`\n${divider}`);
-  const iters = Array.isArray(result?.iterations) ? result.iterations : [];
+  const iters = result.iterations || [];
   if (iters.length) {
-    iters.forEach((it: any, i: number) => {
+    iters.forEach((it, i) => {
       console.log(chalk.magenta(`Attempt ${i + 1}`));
       console.log(`${chalk.gray('Command:')} ${it.command}`);
       console.log(
         `${chalk.gray('OK:')} ${it.ok ? chalk.green('true') : chalk.red('false')}`
       );
-      const issues = it?.critique?.issues || [];
-      const sugg = it?.critique?.suggestions || [];
+      const issues = it.critique?.issues || [];
+      const sugg = it.critique?.suggestions || [];
       if (issues.length) {
         console.log(chalk.bold('Issues:'));
-        issues
-          .slice(0, 5)
-          .forEach((x: string) => console.log(chalk.red(` - ${x}`)));
+        issues.slice(0, 5).forEach((x) => console.log(chalk.red(` - ${x}`)));
       }
       if (sugg.length) {
         console.log(chalk.bold('Suggestions:'));
-        sugg
-          .slice(0, 5)
-          .forEach((x: string) => console.log(chalk.yellow(` - ${x}`)));
+        sugg.slice(0, 5).forEach((x) => console.log(chalk.yellow(` - ${x}`)));
       }
       console.log(divider);
     });
   }
 
-  const approved = !!result?.critique?.approved;
+  const approved = result.critique?.approved ?? false;
   console.log(
     `${chalk.bold('Final:')} ${
       approved ? chalk.green('Approved') : chalk.yellow('Needs changes')
@@ -999,7 +1100,7 @@ function printInteractionLog(
 program
   .command('pending:list')
   .description(
-    'List pending approval-gated plans (from .stackmemory/mm-spike/pending.json)'
+    'List pending approval-gated plans (from .stackmemory/build/pending.json)'
   )
   .option('--task-contains <substr>', 'Filter tasks containing this substring')
   .option('--older-than-ms <number>', 'Only items older than this age (ms)')
@@ -1012,7 +1113,7 @@ program
       const storePath = path.join(
         process.cwd(),
         '.stackmemory',
-        'mm-spike',
+        'build',
         'pending.json'
       );
       let pending: Record<string, any> = {};