@covibes/zeroshot 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,3 +1,85 @@
+# [3.0.0](https://github.com/covibes/zeroshot/compare/v2.1.0...v3.0.0) (2025-12-29)
+
+
+### Bug Fixes
+
+* **isolation:** replace busy-wait with async/await for parallel copy ([c8afbf0](https://github.com/covibes/zeroshot/commit/c8afbf00927ce939af633406c47a928507c339c4)), closes [#21](https://github.com/covibes/zeroshot/issues/21)
+* **security:** escape shell arguments in Docker commands ([43476ad](https://github.com/covibes/zeroshot/commit/43476adfb3c67634d478b4dd53d52a6afb42b297))
+* shell injection prevention and test reliability improvements ([45254f7](https://github.com/covibes/zeroshot/commit/45254f7f75b027ba43f6e16fa3668960d4b77f97))
+* **status-footer:** use decimal display for interpolated metrics ([#26](https://github.com/covibes/zeroshot/issues/26)) ([73ce673](https://github.com/covibes/zeroshot/commit/73ce67376078f97faefe6724e32ff34619f33374))
+
+
+### Features
+
+* **cli:** change default model ceiling to opus ([#28](https://github.com/covibes/zeroshot/issues/28)) ([1810be3](https://github.com/covibes/zeroshot/commit/1810be3a6a2cbfbb4d3aefa711c32f9ff9718f5a))
+* **cli:** change default model ceiling to opus + fix worktree flag cascade ([#29](https://github.com/covibes/zeroshot/issues/29)) ([eaa30b0](https://github.com/covibes/zeroshot/commit/eaa30b06baf381c4fb7306d08fcd2d4e980de002))
+* **cli:** consolidate StatusFooter for logs -f mode + add blinking agent indicator ([fe2722d](https://github.com/covibes/zeroshot/commit/fe2722d157e04048b56368e2c0ffcd7052604f36))
+* real-time metrics via interpolation + maxModel cost ceiling ([#24](https://github.com/covibes/zeroshot/issues/24)) ([f1db466](https://github.com/covibes/zeroshot/commit/f1db46691eca592de67e399aca18f6db3e94d628)), closes [#21](https://github.com/covibes/zeroshot/issues/21)
+* **settings:** replace defaultModel with maxModel cost ceiling ([#25](https://github.com/covibes/zeroshot/issues/25)) ([9877dad](https://github.com/covibes/zeroshot/commit/9877dadad890f78b3af1404b0341da392f6f4bb7)), closes [#23](https://github.com/covibes/zeroshot/issues/23)
+* **validation:** add Phase 5 template variable validation ([#27](https://github.com/covibes/zeroshot/issues/27)) ([5e5e7c6](https://github.com/covibes/zeroshot/commit/5e5e7c6ab2a11ba23a3600d101a9c9c7de02569e))
+
+
+### Performance Improvements
+
+* **isolation:** optimize startup with 4 key improvements ([f28f89c](https://github.com/covibes/zeroshot/commit/f28f89c36ac98c341484124bbaffee745818dffa)), closes [#20](https://github.com/covibes/zeroshot/issues/20) [#21](https://github.com/covibes/zeroshot/issues/21) [#22](https://github.com/covibes/zeroshot/issues/22) [#23](https://github.com/covibes/zeroshot/issues/23) [#20](https://github.com/covibes/zeroshot/issues/20) [#21](https://github.com/covibes/zeroshot/issues/21) [#22](https://github.com/covibes/zeroshot/issues/22) [#23](https://github.com/covibes/zeroshot/issues/23)
+
+
+### BREAKING CHANGES
+
+* None
+* **settings:** defaultModel setting renamed to maxModel
+* defaultModel setting renamed to maxModel
+
+* feat(status-footer): implement real-time metrics via interpolation
+
+Replace blocking 1s metrics polling with background sampling + interpolation:
+- Sample actual metrics every 500ms (non-blocking background)
+- Display updates every 100ms (10 fps - appears continuous)
+- Values smoothly drift toward targets via lerp (15% per tick)
+- CPU and RAM interpolate; Network is cumulative (no interpolation)
+
+Result: Real-time seeming monitoring while reducing actual polling.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+
+* feat(debug-workflow): harden investigator/fixer/tester for senior-dev quality
+
+Implements 7 hardening changes to ensure debug-workflow produces
+trustworthy output without manual code review:
+
+**Investigator:**
+- Structured rootCauses schema requiring proof each is fundamental
+- Mandatory similarPatternLocations field from codebase-wide scan
+- Prompt requires documenting WHY each cause is root (not symptom)
+
+**Fixer:**
+- Mandatory root cause mapping (each cause → specific fix)
+- Mandatory test addition with escape hatch for valid justifications
+- Must fix ALL similar pattern locations, not just original failure
+
+**Tester:**
+- Structured verification schema with commandResult, rootCauseVerification,
+  similarLocationVerification, testVerification, regressionCheck
+- Comprehensive checklist: A (command), B (root causes), C (similar locs),
+  D (test quality), E (regression via smart tiering)
+- Explicit forbidden rationalizations and approval criteria
+
+Result: Workflow now blocks incomplete work, band-aid fixes, missing tests,
+and ignored similar bugs. Output can be trusted.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+
+# [2.1.0](https://github.com/covibes/zeroshot/compare/v2.0.0...v2.1.0) (2025-12-29)
+
+
+### Features
+
+* add first-run wizard and update checker ([c93cdfe](https://github.com/covibes/zeroshot/commit/c93cdfec65f05ce5b1ed4583b5ec0a23fcf56f31)), closes [#17](https://github.com/covibes/zeroshot/issues/17)
+
 # [2.0.0](https://github.com/covibes/zeroshot/compare/v1.5.0...v2.0.0) (2025-12-29)
 
 

package/README.md

@@ -70,10 +70,11 @@ gh auth login
 zeroshot run 123               # Run on GitHub issue
 zeroshot run "Add dark mode"   # Run from description
 
-# Automation levels (cascading: --ship → --pr → --isolation)
-zeroshot run 123 --isolation   # Docker isolation, no PR
-zeroshot run 123 --pr          # Isolation + PR (human reviews)
-zeroshot run 123 --ship        # Isolation + PR + auto-merge (full automation)
+# Automation levels (cascading: --ship → --pr → --worktree)
+zeroshot run 123 --docker      # Docker isolation (full container)
+zeroshot run 123 --worktree    # Git worktree isolation (lightweight)
+zeroshot run 123 --pr          # Worktree + PR (human reviews)
+zeroshot run 123 --ship        # Worktree + PR + auto-merge (full automation)
 
 # Background mode
 zeroshot run 123 -d            # Detached/daemon
@@ -331,13 +332,23 @@ zeroshot resume cluster-bold-panther
 
 ---
 
-## Docker Isolation
+## Isolation Modes
+
+### Git Worktree (Default for --pr/--ship)
+
+```bash
+zeroshot 123 --worktree
+```
+
+Lightweight isolation using git worktree. Creates a separate working directory with its own branch. Fast (<1s setup), no Docker required. Auto-enabled with `--pr` and `--ship`.
+
+### Docker Container
 
 ```bash
-zeroshot 123 --isolation
+zeroshot 123 --docker
 ```
 
-Runs in a fresh container. Your workspace stays untouched. Good for risky experiments.
+Full isolation in a fresh container. Your workspace stays untouched. Good for risky experiments or parallel agents.
 
 ---
 
@@ -356,7 +367,7 @@ Runs in a fresh container. Your workspace stays untouched. Good for risky experi
 | `claude: command not found`   | `npm i -g @anthropic-ai/claude-code && claude auth login`            |
 | `gh: command not found`       | [Install GitHub CLI](https://cli.github.com/)                        |
 | CLI frozen for minutes        | Normal - agents use JSON schema output, can't stream partial results |
-| `--isolation` fails           | Docker must be running: `docker ps` to verify                        |
+| `--docker` fails              | Docker must be running: `docker ps` to verify                        |
 | Cluster stuck                 | `zeroshot resume <id>` to continue with guidance                     |
 | Agent keeps failing           | Check `zeroshot logs <id>` for actual error                          |
 | `zeroshot: command not found` | `npm install -g @covibes/zeroshot`                                   |

package/cli/index.js

@@ -386,7 +386,7 @@ Examples:
   ${chalk.cyan('zeroshot run 123')}                    Run cluster and attach to first agent
   ${chalk.cyan('zeroshot run 123 -d')}                 Run cluster in background (detached)
   ${chalk.cyan('zeroshot run "Implement feature X"')}  Run cluster on plain text task
-  ${chalk.cyan('zeroshot run 123 --isolation')}        Run in Docker container (safe for e2e tests)
+  ${chalk.cyan('zeroshot run 123 --docker')}           Run in Docker container (safe for e2e tests)
   ${chalk.cyan('zeroshot task run "Fix the bug"')}     Run single-agent background task
   ${chalk.cyan('zeroshot list')}                       List all tasks and clusters
   ${chalk.cyan('zeroshot task list')}                  List tasks only
@@ -400,17 +400,18 @@ Examples:
   ${chalk.cyan('zeroshot kill <id>')}                  Kill a running task or cluster
   ${chalk.cyan('zeroshot purge')}                      Kill all processes and delete all data (with confirmation)
   ${chalk.cyan('zeroshot purge -y')}                   Purge everything without confirmation
-  ${chalk.cyan('zeroshot settings')}                   Show/manage zeroshot settings (default model, config, etc.)
-  ${chalk.cyan('zeroshot settings set <key> <val>')}   Set a setting (e.g., defaultModel haiku)
+  ${chalk.cyan('zeroshot settings')}                   Show/manage zeroshot settings (maxModel, config, etc.)
+  ${chalk.cyan('zeroshot settings set <key> <val>')}   Set a setting (e.g., maxModel haiku)
   ${chalk.cyan('zeroshot config list')}                List available cluster configs
   ${chalk.cyan('zeroshot config show <name>')}         Visualize a cluster config (agents, triggers, flow)
   ${chalk.cyan('zeroshot export <id>')}                Export cluster conversation to file
 
-Automation levels (cascading: --ship → --pr → --isolation):
+Automation levels (cascading: --ship → --pr → --worktree):
   ${chalk.yellow('zeroshot run 123')}            → Local run, no isolation
-  ${chalk.yellow('zeroshot run 123 --isolation')} → Docker isolation, no PR
-  ${chalk.yellow('zeroshot run 123 --pr')}       → Isolation + PR (human reviews)
-  ${chalk.yellow('zeroshot run 123 --ship')}     → Isolation + PR + auto-merge (full automation)
+  ${chalk.yellow('zeroshot run 123 --docker')}   → Docker isolation, no PR
+  ${chalk.yellow('zeroshot run 123 --worktree')} → Git worktree isolation, no PR
+  ${chalk.yellow('zeroshot run 123 --pr')}       → Worktree + PR (human reviews)
+  ${chalk.yellow('zeroshot run 123 --ship')}     → Worktree + PR + auto-merge (full automation)
   ${chalk.yellow('zeroshot task run')}           → Single-agent background task (simpler, faster)
 
 Shell completion:
@@ -423,18 +424,18 @@ program
   .command('run <input>')
   .description('Start a multi-agent cluster (auto-detects GitHub issue or plain text)')
   .option('--config <file>', 'Path to cluster config JSON (default: conductor-bootstrap)')
-  .option('-m, --model <model>', 'Model for all agents: opus, sonnet, haiku (default: from config)')
-  .option('--isolation', 'Run cluster inside Docker container (for e2e testing)')
+  .option('--docker', 'Run cluster inside Docker container (full isolation)')
+  .option('--worktree', 'Use git worktree for isolation (lightweight, no Docker required)')
   .option(
-    '--isolation-image <image>',
-    'Docker image for isolation (default: zeroshot-cluster-base)'
+    '--docker-image <image>',
+    'Docker image for --docker mode (default: zeroshot-cluster-base)'
   )
   .option(
     '--strict-schema',
     'Enforce JSON schema via CLI (no live streaming). Default: live streaming with local validation'
   )
-  .option('--pr', 'Create PR for human review (auto-enables --isolation)')
-  .option('--ship', 'Full automation: isolation + PR + auto-merge')
+  .option('--pr', 'Create PR for human review (uses worktree isolation by default, use --docker for Docker)')
+  .option('--ship', 'Full automation: worktree isolation + PR + auto-merge (use --docker for Docker)')
   .option('--workers <n>', 'Max sub-agents for worker to spawn in parallel', parseInt)
   .option('-d, --detach', 'Run in background (default: attach to first agent)')
   .addHelpText(
@@ -449,15 +450,23 @@ Input formats:
   )
   .action(async (inputArg, options) => {
     try {
-      // Cascading flag implications: --ship → --pr → --isolation
-      // --ship = full automation (isolation + PR + auto-merge)
+      // Cascading flag implications: --ship → --pr → worktree (unless --docker)
+      // --ship = full automation (worktree isolation + PR + auto-merge)
       if (options.ship) {
         options.pr = true;
-        options.isolation = true;
+        // Use worktree by default, Docker only if explicitly requested
+        if (!options.docker) {
+          options.worktree = true;
+        }
+      }
+      // --pr = PR for human review (worktree by default, Docker if requested)
+      if (options.pr && !options.docker && !options.worktree) {
+        options.worktree = true;
       }
-      // --pr = PR for human review (auto-enables isolation)
-      if (options.pr) {
-        options.isolation = true;
+
+      // Mutual exclusivity: --docker explicitly disables worktree
+      if (options.docker) {
+        options.worktree = false;
       }
 
       // Auto-detect input type
@@ -485,7 +494,8 @@ Input formats:
       // This gives users clear, actionable error messages upfront
       const preflightOptions = {
         requireGh: !!input.issue, // gh CLI required when fetching GitHub issues
-        requireDocker: options.isolation, // Docker required for isolation mode
+        requireDocker: options.docker, // Docker required for --docker mode
+        requireGit: options.worktree, // Git required for worktree isolation
         quiet: process.env.CREW_DAEMON === '1', // Suppress success in daemon mode
       };
       requirePreflight(preflightOptions);
@@ -503,8 +513,8 @@ Input formats:
         const clusterId = generateName('cluster');
 
         // Output cluster ID and help
-        if (options.isolation) {
-          console.log(`Started ${clusterId} (isolated)`);
+        if (options.docker) {
+          console.log(`Started ${clusterId} (docker)`);
         } else {
           console.log(`Started ${clusterId}`);
         }
@@ -533,10 +543,10 @@ Input formats:
             ...process.env,
             CREW_DAEMON: '1',
             CREW_CLUSTER_ID: clusterId,
-            CREW_MODEL: options.model || '',
-            CREW_ISOLATION: options.isolation ? '1' : '',
-            CREW_ISOLATION_IMAGE: options.isolationImage || '',
+            CREW_DOCKER: options.docker ? '1' : '',
+            CREW_DOCKER_IMAGE: options.dockerImage || '',
             CREW_PR: options.pr ? '1' : '',
+            CREW_WORKTREE: options.worktree ? '1' : '',
             CREW_WORKERS: options.workers?.toString() || '',
             CREW_CWD: targetCwd, // Explicit CWD for orchestrator
           },
@@ -587,8 +597,10 @@ Input formats:
 
       // In foreground mode, show startup info
       if (!process.env.CREW_DAEMON) {
-        if (options.isolation) {
-          console.log(`Starting ${clusterId} (isolated)`);
+        if (options.docker) {
+          console.log(`Starting ${clusterId} (docker)`);
+        } else if (options.worktree) {
+          console.log(`Starting ${clusterId} (worktree)`);
         } else {
           console.log(`Starting ${clusterId}`);
         }
@@ -596,17 +608,6 @@ Input formats:
         console.log(chalk.dim('Ctrl+C to stop following (cluster keeps running)\n'));
       }
 
-      // Override model (CLI > settings > config)
-      const modelOverride = process.env.CREW_MODEL || options.model || settings.defaultModel;
-      if (modelOverride) {
-        for (const agent of config.agents) {
-          // Only override if agent doesn't already specify a model
-          if (!agent.model || modelOverride) {
-            agent.model = modelOverride;
-          }
-        }
-      }
-
       // Apply strictSchema setting to all agents (CLI > env > settings)
       const strictSchema =
         options.strictSchema || process.env.CREW_STRICT_SCHEMA === '1' || settings.strictSchema;
@@ -623,8 +624,9 @@ Input formats:
       const startOptions = {
         cwd: targetCwd, // Target working directory for agents
         isolation:
-          options.isolation || process.env.CREW_ISOLATION === '1' || settings.defaultIsolation,
-        isolationImage: options.isolationImage || process.env.CREW_ISOLATION_IMAGE || undefined,
+          options.docker || process.env.CREW_DOCKER === '1' || settings.defaultDocker,
+        isolationImage: options.dockerImage || process.env.CREW_DOCKER_IMAGE || undefined,
+        worktree: options.worktree || process.env.CREW_WORKTREE === '1',
         autoPr: options.pr || process.env.CREW_PR === '1',
         autoMerge: process.env.CREW_MERGE === '1',
         autoPush: process.env.CREW_PUSH === '1',
@@ -822,10 +824,6 @@ taskCmd
   .command('run <prompt>')
   .description('Run a single-agent background task')
   .option('-C, --cwd <path>', 'Working directory for task')
-  .option(
-    '-m, --model <model>',
-    'Model to use: opus, sonnet, haiku (default: sonnet or ANTHROPIC_MODEL env)'
-  )
   .option('-r, --resume <sessionId>', 'Resume a specific Claude session')
   .option('-c, --continue', 'Continue the most recent session')
   .option(
@@ -1269,11 +1267,23 @@ program
             clusterStates.set(c.id, c.state);
           }
 
-          // Track agent states from AGENT_LIFECYCLE messages (cross-process compatible)
-          const agentStates = new Map(); // agent -> { state, timestamp }
-
-          // Track if status line is currently displayed (to clear before printing logs)
-          let statusLineShown = false;
+          // === STATUS FOOTER: Live agent monitoring (same as foreground mode) ===
+          // Shows CPU, memory, network metrics for all agents at bottom of terminal
+          let statusFooter = null;
+          if ((options.follow || options.watch) && process.stdout.isTTY) {
+            statusFooter = new StatusFooter({
+              refreshInterval: 1000,
+              enabled: true,
+            });
+            // Set first cluster as the active one (for display purposes)
+            if (allClusters.length > 0) {
+              statusFooter.setCluster(allClusters[0].id);
+              statusFooter.setClusterState(clusterStates.get(allClusters[0].id) || 'running');
+            }
+            // Set module-level reference so safePrint/safeWrite route through footer
+            activeStatusFooter = statusFooter;
+            statusFooter.start();
+          }
 
           // Buffered message handler - collects messages and sorts by timestamp
           const flushMessages = () => {
@@ -1287,19 +1297,46 @@ program
               if (msg.topic === 'AGENT_OUTPUT' && msg.sender) {
                 sendersWithOutput.add(msg.sender);
               }
-              // Track agent state from AGENT_LIFECYCLE messages
-              if (msg.topic === 'AGENT_LIFECYCLE' && msg.sender && msg.content?.data?.state) {
-                agentStates.set(msg.sender, {
-                  state: msg.content.data.state,
-                  model: msg.sender_model, // sender_model is always set by agent-wrapper._publish
-                  timestamp: msg.timestamp || Date.now(),
-                });
-              }
 
-              // Clear status line before printing message
-              if (statusLineShown) {
-                process.stdout.write('\r' + ' '.repeat(120) + '\r');
-                statusLineShown = false;
+              // Update StatusFooter from polled AGENT_LIFECYCLE messages (cross-process)
+              if (msg.topic === 'AGENT_LIFECYCLE' && statusFooter) {
+                const data = msg.content?.data || {};
+                const event = data.event;
+                const agentId = data.agent || msg.sender;
+
+                if (event === 'STARTED') {
+                  statusFooter.updateAgent({
+                    id: agentId,
+                    state: 'idle',
+                    pid: null,
+                    iteration: data.iteration || 0,
+                  });
+                } else if (event === 'TASK_STARTED') {
+                  statusFooter.updateAgent({
+                    id: agentId,
+                    state: 'executing',
+                    pid: statusFooter.agents.get(agentId)?.pid || null,
+                    iteration: data.iteration || 0,
+                  });
+                } else if (event === 'PROCESS_SPAWNED') {
+                  // Got the PID - update the agent with it for CPU/memory metrics
+                  const current = statusFooter.agents.get(agentId) || { state: 'executing', iteration: 0 };
+                  statusFooter.updateAgent({
+                    id: agentId,
+                    state: current.state,
+                    pid: data.pid,
+                    iteration: current.iteration,
+                  });
+                } else if (event === 'TASK_COMPLETED' || event === 'TASK_FAILED') {
+                  statusFooter.updateAgent({
+                    id: agentId,
+                    state: 'idle',
+                    pid: null,
+                    iteration: data.iteration || 0,
+                  });
+                } else if (event === 'STOPPED') {
+                  statusFooter.removeAgent(agentId);
+                }
               }
 
               const isActive = clusterStates.get(msg.cluster_id) === 'running';
@@ -1322,51 +1359,6 @@ program
           // Flush buffer every 250ms
           const flushInterval = setInterval(flushMessages, 250);
 
-          // Blinking status indicator (follow/watch mode) - uses AGENT_LIFECYCLE state
-          let blinkState = false;
-          let statusInterval = null;
-          if (options.follow || options.watch) {
-            statusInterval = setInterval(() => {
-              blinkState = !blinkState;
-
-              // Get active agents from tracked states
-              const activeList = [];
-              for (const [agentId, info] of agentStates.entries()) {
-                // Agent is active if not idle and not stopped
-                if (info.state !== 'idle' && info.state !== 'stopped') {
-                  activeList.push({
-                    id: agentId,
-                    state: info.state,
-                    model: info.model,
-                  });
-                }
-              }
-
-              // Build status line - only show when agents are actively working
-              if (activeList.length > 0) {
-                const indicator = blinkState ? chalk.yellow('●') : chalk.dim('○');
-                const agents = activeList
-                  .map((a) => {
-                    // Show state only for non-standard states (error, etc.)
-                    const showState = a.state === 'error';
-                    const stateLabel = showState ? chalk.red(` (${a.state})`) : '';
-                    // Always show model
-                    const modelLabel = a.model ? chalk.dim(` [${a.model}]`) : '';
-                    return getColorForSender(a.id)(a.id) + modelLabel + stateLabel;
-                  })
-                  .join(', ');
-                process.stdout.write(`\r${indicator} Active: ${agents}` + ' '.repeat(20));
-                statusLineShown = true;
-              } else {
-                // Clear status line when no agents actively working
-                if (statusLineShown) {
-                  process.stdout.write('\r' + ' '.repeat(60) + '\r');
-                  statusLineShown = false;
-                }
-              }
-            }, 500);
-          }
-
           for (const clusterInfo of allClusters) {
             const cluster = quietOrchestrator.getCluster(clusterInfo.id);
             if (cluster) {
@@ -1399,13 +1391,13 @@ program
 
           keepProcessAlive(() => {
             clearInterval(flushInterval);
-            if (statusInterval) clearInterval(statusInterval);
             flushMessages();
             stopPollers.forEach((stop) => stop());
             stopWatching();
-            // Clear status line on exit
-            if (statusLineShown) {
-              process.stdout.write('\r' + ' '.repeat(120) + '\r');
+            // Stop status footer and restore terminal
+            if (statusFooter) {
+              statusFooter.stop();
+              activeStatusFooter = null;
             }
             // Restore terminal title
             restoreTerminalTitle();
@@ -2833,6 +2825,48 @@ settingsCmd.action(() => {
   console.log('');
 });
 
+// Update command
+program
+  .command('update')
+  .description('Update zeroshot to the latest version')
+  .option('--check', 'Check for updates without installing')
+  .action(async (options) => {
+    const {
+      getCurrentVersion,
+      fetchLatestVersion,
+      isNewerVersion,
+      runUpdate,
+    } = require('./lib/update-checker');
+
+    const currentVersion = getCurrentVersion();
+    console.log(chalk.dim(`Current version: ${currentVersion}`));
+    console.log(chalk.dim('Checking for updates...'));
+
+    const latestVersion = await fetchLatestVersion();
+
+    if (!latestVersion) {
+      console.error(chalk.red('Failed to check for updates. Check your internet connection.'));
+      process.exit(1);
+    }
+
+    console.log(chalk.dim(`Latest version:  ${latestVersion}`));
+
+    if (!isNewerVersion(currentVersion, latestVersion)) {
+      console.log(chalk.green('\n✓ You are already on the latest version!'));
+      return;
+    }
+
+    console.log(chalk.yellow(`\n📦 Update available: ${currentVersion} → ${latestVersion}`));
+
+    if (options.check) {
+      console.log(chalk.dim('\nRun `zeroshot update` to install the update.'));
+      return;
+    }
+
+    const success = await runUpdate();
+    process.exit(success ? 0 : 1);
+  });
+
 // Config visualization commands
 const configCmd = program.command('config').description('Manage and visualize cluster configs');
 
@@ -4319,7 +4353,8 @@ function printMessage(msg, showClusterId = false, watchMode = false, isActive =
 // Main async entry point
 async function main() {
   // First-run setup wizard (blocks on first use only)
-  const isQuiet = process.argv.includes('-q') || process.argv.includes('--quiet');
+  // CRITICAL: Auto-enable quiet mode in test environment to prevent stdin hangs
+  const isQuiet = process.argv.includes('-q') || process.argv.includes('--quiet') || process.env.NODE_ENV === 'test';
   await checkFirstRun({ quiet: isQuiet });
 
   // Check for updates (non-blocking if offline)

package/cli/lib/first-run.js

@@ -3,7 +3,7 @@
  *
  * Interactive setup on first use:
  * - Welcome banner
- * - Default model selection (sonnet/opus/haiku)
+ * - Max model ceiling selection (sonnet/opus/haiku)
  * - Auto-update preference
  * - Marks setup as complete
  */
@@ -45,13 +45,13 @@ function createReadline() {
  */
 function promptModel(rl) {
   return new Promise((resolve) => {
-    console.log('Which Claude model should agents use by default?\n');
-    console.log('  1) sonnet  - Fast & capable (recommended)');
-    console.log('  2) opus    - Most capable, slower');
-    console.log('  3) haiku   - Fastest, for simple tasks\n');
+    console.log('What is the maximum model agents can use? (cost ceiling)\n');
+    console.log('  1) sonnet  - Agents can use sonnet or haiku (recommended)');
+    console.log('  2) opus    - Agents can use opus, sonnet, or haiku');
+    console.log('  3) haiku   - Agents can only use haiku (lowest cost)\n');
 
-    rl.question('Enter 1, 2, or 3 [1]: ', (answer) => {
-      const choice = answer.trim() || '1';
+    rl.question('Enter 1, 2, or 3 [2]: ', (answer) => {
+      const choice = answer.trim() || '2';
       switch (choice) {
         case '2':
           resolve('opus');
@@ -95,8 +95,8 @@ function printComplete(settings) {
 ╚═══════════════════════════════════════════════════════════════╝
 
 Your settings:
-  • Default model: ${settings.defaultModel}
-  • Auto-updates:  ${settings.autoCheckUpdates ? 'enabled' : 'disabled'}
+  • Max model:    ${settings.maxModel} (agents can use this model or lower)
+  • Auto-updates: ${settings.autoCheckUpdates ? 'enabled' : 'disabled'}
 
 Change anytime with: zeroshot settings set <key> <value>
 
@@ -144,9 +144,9 @@ async function checkFirstRun(options = {}) {
   const rl = createReadline();
 
   try {
-    // Model selection
+    // Model ceiling selection
     const model = await promptModel(rl);
-    settings.defaultModel = model;
+    settings.maxModel = model;
 
     // Auto-update preference
     const autoUpdate = await promptAutoUpdate(rl);

package/cli/lib/update-checker.js

@@ -225,10 +225,11 @@ async function checkForUpdates(options = {}) {
 
 module.exports = {
   checkForUpdates,
-  // Exported for testing
+  // Exported for testing and CLI update command
   getCurrentVersion,
   isNewerVersion,
   fetchLatestVersion,
+  runUpdate,
   shouldCheckForUpdates,
   CHECK_INTERVAL_MS,
 };