compound-agent 1.7.4 → 1.8.0

package/dist/cli.js

@@ -8,7 +8,7 @@ import { z } from 'zod';
 import * as fs from 'fs/promises';
 import { readFile, mkdir, appendFile, writeFile, chmod, rm, rename, readdir } from 'fs/promises';
 import { createRequire } from 'module';
-import { execSync, execFileSync, spawn } from 'child_process';
+import { execSync, spawnSync, execFileSync, spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
 import chalk5 from 'chalk';
@@ -3132,7 +3132,7 @@ function checkBeadsAvailable() {
   } catch {
     return {
       available: false,
-      message: "Beads CLI not found. Recommended for full workflow (issue tracking, deps, TDD pipeline). Install: https://github.com/Nathandela/beads"
+      message: "Beads CLI not found. Recommended for full workflow (issue tracking, deps, TDD pipeline).\nInstall: curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash\nOr run: ca install-beads"
     };
   }
 }
@@ -3313,7 +3313,7 @@ This project uses compound-agent for session memory via **CLI commands**.
 | Command | Purpose |
 |---------|---------|
 | \`npx ca search "query"\` | Search lessons - MUST call before architectural decisions; use anytime you need context |
-| \`npx ca knowledge "query"\` | Ask the project docs any question - MUST call before architectural decisions; use freely |
+| \`npx ca knowledge "query"\` | Semantic search over project docs - MUST call before architectural decisions; use keyword phrases, not questions |
 | \`npx ca learn "insight"\` | Capture lessons - use AFTER corrections or discoveries |
 | \`npx ca list\` | List all stored lessons |
 | \`npx ca show <id>\` | Show details of a specific lesson |
@@ -3680,6 +3680,8 @@ function printBeadsFullStatus(check) {
     if (check.initialized) {
       console.log(`  Beads health:       ${check.healthy ? "OK" : `issues found${check.healthMessage ? ` \u2014 ${check.healthMessage}` : ""}`}`);
     }
+  } else if (check.healthMessage) {
+    console.log(`                      ${check.healthMessage}`);
   }
 }
 function printScopeStatus(scope) {
@@ -5694,7 +5696,7 @@ npx ca loop                    # Generate infinity loop script for autonomous pr
 npx ca loop --epics epic-1 epic-2
 npx ca loop --output my-loop.sh
 npx ca loop --max-retries 5
-npx ca loop --model claude-opus-4-6
+npx ca loop --model claude-opus-4-6[1m]
 npx ca loop --force            # Overwrite existing script
 \`\`\`
 
@@ -9434,6 +9436,8 @@ var LESSON_COUNT_WARNING_THRESHOLD = 20;
 var AGE_FLAG_THRESHOLD_DAYS = 90;
 var ISO_DATE_PREFIX_LENGTH = 10;
 var AVG_DECIMAL_PLACES = 1;
+var DEFAULT_LOOP_MODEL = "claude-opus-4-6[1m]";
+var MODEL_PATTERN = /^[a-zA-Z0-9_.:[\]/-]+$/;
 
 // src/commands/management-helpers.ts
 function formatLessonHuman(lesson) {
@@ -9651,7 +9655,7 @@ async function runDoctor(repoRoot) {
     checks.push(pnpmCheck);
   }
   const beadsResult = checkBeadsAvailable();
-  checks.push(beadsResult.available ? { name: "Beads CLI", status: "pass" } : { name: "Beads CLI", status: "warn", fix: "Install beads: https://github.com/Nathandela/beads" });
+  checks.push(beadsResult.available ? { name: "Beads CLI", status: "pass" } : { name: "Beads CLI", status: "warn", fix: "Run: ca install-beads" });
   checks.push(checkGitignoreHealth(repoRoot) ? { name: ".gitignore health", status: "pass" } : { name: ".gitignore health", status: "warn", fix: "Run: npx ca setup --update" });
   const docPath = join(repoRoot, "docs", "compound", "README.md");
   checks.push(existsSync(docPath) ? { name: "Usage documentation", status: "pass" } : { name: "Usage documentation", status: "warn", fix: "Run: npx ca setup" });
@@ -9986,14 +9990,13 @@ var FETCH_TIMEOUT_MS = 3e3;
 var CACHE_FILENAME = "update-check.json";
 async function fetchLatestVersion(packageName = "compound-agent") {
   try {
-    const res = await fetch(`https://registry.npmjs.org/${packageName}`, {
-      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
-    });
+    const res = await fetch(
+      `https://registry.npmjs.org/-/package/${packageName}/dist-tags`,
+      { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) }
+    );
     if (!res.ok) return null;
     const data = await res.json();
-    const tags = data["dist-tags"];
-    if (typeof tags !== "object" || tags === null) return null;
-    const latest = tags["latest"];
+    const latest = data["latest"];
     return typeof latest === "string" ? latest : null;
   } catch {
     return null;
@@ -10027,13 +10030,41 @@ async function checkForUpdate(cacheDir) {
     return null;
   }
 }
+function isMajorUpdate(current, latest) {
+  return parseInt(latest.split(".")[0], 10) > parseInt(current.split(".")[0], 10);
+}
 function formatUpdateNotification(current, latest) {
-  return `Update available: ${current} -> ${latest}
-Run: pnpm update --latest compound-agent`;
+  const label = isMajorUpdate(current, latest) ? "Major update" : "Update available";
+  const warning = isMajorUpdate(current, latest) ? "\n  May contain breaking changes -- check the changelog." : "";
+  return [
+    `${label}: ${current} -> ${latest}${warning}`,
+    `Run: npm update -g compound-agent        (global)`,
+    `     pnpm add -D compound-agent@latest   (dev dependency)`
+  ].join("\n");
+}
+function formatUpdateNotificationMarkdown(current, latest) {
+  const urgency = isMajorUpdate(current, latest) ? " (MAJOR - may contain breaking changes)" : "";
+  return `
+---
+# Update Available
+compound-agent v${latest} is available (current: v${current})${urgency}.
+Run: \`npm update -g compound-agent\` (global) or \`pnpm add -D compound-agent@latest\` (dev dependency)
+`;
+}
+function shouldCheckForUpdate() {
+  if (!process.stdout.isTTY) return false;
+  if (process.env["CI"]) return false;
+  if (process.env["NO_UPDATE_NOTIFIER"]) return false;
+  if (process.env["NODE_ENV"] === "test") return false;
+  return true;
 }
 function semverGt(a, b) {
   const parse = (v) => {
-    const parts = v.split(".").map((n) => parseInt(n, 10) || 0);
+    const clean = v.split("-")[0];
+    const parts = clean.split(".").map((n) => {
+      const num = parseInt(n, 10);
+      return isNaN(num) ? 0 : num;
+    });
     return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
   };
   const [aMaj, aMin, aPat] = parse(a);
@@ -10048,7 +10079,7 @@ function readCache(cachePath) {
     if (Date.now() - stat.mtimeMs > CACHE_TTL_MS) return null;
     const raw = readFileSync(cachePath, "utf-8");
     const data = JSON.parse(raw);
-    if (!data.latest) return null;
+    if (typeof data.latest !== "string" || !data.latest) return null;
     return data;
   } catch {
     return null;
@@ -10067,7 +10098,7 @@ var TRUST_LANGUAGE_TEMPLATE = `# Compound Agent Active
 | Command | Purpose |
 |---------|---------|
 | \`npx ca search "query"\` | Search lessons - MUST call before architectural decisions; use anytime you need context |
-| \`npx ca knowledge "query"\` | Ask the project docs any question - MUST call before architectural decisions; use freely |
+| \`npx ca knowledge "query"\` | Semantic search over project docs - MUST call before architectural decisions; use keyword phrases, not questions |
 | \`npx ca learn "insight"\` | Capture lessons - call AFTER corrections or discoveries |
 
 ## Core Constraints
@@ -10167,15 +10198,11 @@ ${formattedLessons}
   if (cookitSection !== null) {
     output += cookitSection;
   }
-  if (!process.stdout.isTTY) {
+  if (!process.stdout.isTTY && !process.env["CI"] && !process.env["NO_UPDATE_NOTIFIER"]) {
     try {
       const updateResult = await checkForUpdate(join(root, ".claude", ".cache"));
       if (updateResult?.updateAvailable) {
-        output += `
----
-# Update Available
-compound-agent v${updateResult.latest} is available (current: v${updateResult.current}). Run \`pnpm update --latest compound-agent\` to update.
-`;
+        output += formatUpdateNotificationMarkdown(updateResult.current, updateResult.latest);
       }
     } catch {
     }
@@ -10905,70 +10932,59 @@ function registerVerifyGatesCommand(program) {
 }
 
 // src/changelog-data.ts
-var CHANGELOG_RECENT = `## [1.7.4] - 2026-03-11
+var CHANGELOG_RECENT = `## [1.8.0] - 2026-03-15
 
 ### Added
 
-- **Research-enriched phase skills**: Applied insights from 3 PhD-level research documents (Science of Decomposition, Architecture Under Uncertainty, Emergent Behavior in Composed Systems) across all 6 core phase skills:
-  - **Architect**: reversibility analysis (Baldwin & Clark), change volatility, 6-subagent convoy (added STPA control structure analyst + structural-semantic gap analyst), implicit interface contracts (threading, backpressure, delivery guarantees), organizational alignment (Team Topologies), multi-criteria validation gate (structural/semantic/organizational/economic), assumption capture with fitness functions and re-decomposition triggers
-  - **Spec-dev**: Cynefin classification (Clear/Complicated/Complex), composition EARS templates (timeout/retry interactions), change volatility assessment
-  - **Plan**: boundary stability check, Last Responsible Moment identification, change coupling prevention
-  - **Work**: Fowler technical debt quadrant (only Prudent/Deliberate accepted), composition boundary verification with metastable failure checks
-  - **Review**: composition-specific reviewers (boundary-reviewer, control-structure-reviewer, observability-reviewer), architect assumption validation
-  - **Compound**: decomposition quality assessment, assumption tracking (predicted vs actual), emergence root cause classification (Garlan/STPA/phase transition)
-- **Lint graduation in compound phase**: The compound phase (step 10) now spawns a \`lint-classifier\` subagent that classifies each captured insight as LINTABLE, PARTIAL, or NOT_LINTABLE. High-confidence lintable insights are promoted to beads tasks under a "Linting Improvement" epic with self-contained rule specifications. Two rule classes: Class A (native \`rules.json\` \u2014 regex/glob) and Class B (external linter \u2014 AST analysis).
-- **Linter detection module** (\`src/lint/\`): Scans repos for ESLint (flat + legacy configs including TypeScript variants), Ruff (including \`pyproject.toml\`), Clippy, golangci-lint, ast-grep, and Semgrep. Exported from the package as \`detectLinter()\`, \`LinterInfoSchema\`, \`LinterNameSchema\`.
-- **Lint-classifier agent template**: Ships via \`npx ca init\` to \`.claude/agents/compound/lint-classifier.md\`. Includes 7 few-shot examples, Class A/B routing, and linter-aware task creation.
+- **\`ca improve\` command**: Generates a bash script that autonomously improves the codebase using \`improve/*.md\` program files. Each program defines what to improve, how to find work, and how to validate changes. Options: \`--topics\` (filter specific topics), \`--max-iters\` (iterations per topic, default 5), \`--time-budget\` (total seconds, 0=unlimited), \`--model\`, \`--force\`, \`--dry-run\`. Includes \`ca improve init\` subcommand to scaffold an example program file.
+- **\`ca watch\` command**: Tails and pretty-prints live trace JSONL from infinity loop and improvement loop sessions. Supports \`--epic <id>\` to watch a specific epic, \`--improve\` to watch improvement loop traces, and \`--no-follow\` to print existing trace and exit. Formats tool calls, thinking blocks, token usage, and result markers into a compact, color-coded stream.
 
 ### Fixed
 
-- **PhD research output path**: \`/compound:get-a-phd\` now writes user-generated research to \`docs/research/\` instead of \`docs/compound/research/\`. The \`docs/compound/\` directory is reserved for shipped library content; project-specific research no longer pollutes it. Overlap scanning checks both directories.
+- **\`git clean\` scoping in improvement loop**: Bare \`git clean -fd\` on rollback was removing all untracked files including the script's own log directory, causing crashes. All three rollback paths now use \`git clean -fd -e "$LOG_DIR/"\` to exclude agent logs.
+- **Embedded dirty-worktree guard fallthrough**: In embedded mode (when improvement loop runs inside \`ca loop --improve\`), setting \`IMPROVE_RESULT=1\` on a dirty worktree did not prevent the loop body from executing. Restructured to use \`if/else\` so the loop body only runs inside the \`else\` branch.
+- **\`ca watch --improve\` ignoring \`.latest\` symlink**: The \`--improve\` code path had inline logic that only did reverse filename sort, bypassing the \`.latest\` symlink that the improvement loop maintains. Refactored \`findLatestTraceFile()\` with a \`prefix\` parameter to unify both code paths.
+- **\`--topics\` flag ignored in \`get_topics()\`**: The \`TOPIC_FILTER\` variable from the CLI \`--topics\` flag was not used in the generated bash \`get_topics()\` function, causing all topics to run regardless of filtering.
+- **Update-check hardening**: Switched to a lightweight npm registry endpoint, added CI environment guards, and corrected the update command shown to users.
 
-## [1.7.3] - 2026-03-09
+## [1.7.6] - 2026-03-12
 
 ### Added
 
-- **Update notification**: CLI checks npm registry for newer versions on startup (24h file-based cache, non-blocking). Notification displays after command output (TTY only) and in \`ca prime\` context.
+- **\`ca install-beads\` command**: Standalone subcommand to install the beads CLI via the official script. Includes a platform guard (skips on Windows with \`exitCode 1\`), an "already installed" short-circuit, a \`--yes\` flag to bypass the confirmation hint (safe: never runs \`curl | bash\` without explicit opt-in), \`spawnSync\` with a 60-second timeout, and a post-install shell-reload warning. Non-TTY mode without \`--yes\` prints the install command as a copy-pasteable hint rather than silently doing nothing.
 
 ### Fixed
 
-- **Spec-dev epic type**: \`bd create\` in spec-dev Phase 4 now explicitly uses \`--type=epic\`, preventing epics from defaulting to task type. Plan phase also validates the epic type and corrects it if needed.
-- **Update-check hardening**: Added explicit \`res.ok\` check in \`fetchLatestVersion\`, removed dead \`checkedAt\` cache field, removed redundant type cast.
+- **Beads hint display**: \`printBeadsFullStatus\` was silently swallowing the install hint message when the beads CLI was not found. The curl install command is now printed below the "not found" line.
+- **Beads hint text**: \`checkBeadsAvailable\` now returns the actual \`curl -sSL ... | bash\` install command in its message instead of a bare repo URL.
+- **Doctor fix message**: \`ca doctor\` now shows \`Run: ca install-beads\` for the missing-beads check instead of pointing to a URL.
+- **\`ca knowledge\` description**: Reframed from "Ask the project docs any question" to "Semantic search over project docs \u2014 use keyword phrases, not questions" in both the live prime template and the setup template, reflecting the underlying embedding RAG retrieval mechanism.
 
-## [1.7.2] - 2026-03-09
+## [1.7.5] - 2026-03-12
 
 ### Added
 
-- **Loop review phase**: \`ca loop\` can now spawn independent AI reviewers (Claude Sonnet, Claude Opus, Gemini, Codex) in parallel after every N completed epics. Reviewers produce severity-tagged reports, an implementer session fixes findings, and reviewers are resumed (not fresh) to verify fixes. Iterates until all approve or max cycles reached. New CLI options: \`--reviewers\`, \`--review-every\`, \`--max-review-cycles\`, \`--review-blocking\`, \`--review-model\`. Gracefully skips unavailable CLIs.
-
-### Fixed
-
-- **Security: command injection in \`ca test-summary --cmd\`**: User-supplied test command is now validated against an allowlist of safe prefixes (\`pnpm\`, \`npm\`, \`vitest\`, etc.) and shell metacharacters are rejected.
-- **Security: shell injection in \`ca doctor\`**: Replaced \`execSync(cmd, {shell})\` with \`execFileSync('bd', ['doctor'])\` to avoid shell interpretation.
-- **Portable timeout for macOS**: Generated loop scripts now use a \`portable_timeout()\` wrapper that tries GNU \`timeout\`, then \`gtimeout\` (Homebrew coreutils), then a shell-based kill/watchdog fallback. Previously failed silently on macOS.
-- **Session ID python3 fallback**: Review phase session ID management now falls back to python3 when \`jq\` is unavailable, with a centralized \`read_session_id()\` helper.
-- **Git diff window stability**: Replaced fragile \`HEAD~$N..HEAD\` commit-count arithmetic with SHA-based \`$REVIEW_BASE_SHA..HEAD\` diff ranges, immune to rebases and cherry-picks.
-- **ID collision risk**: Memory item IDs now use 64-bit entropy (16 hex chars) instead of 32-bit (8 hex chars).
-- **JSONL resilience**: Malformed lines in JSONL files are now skipped with try/catch per line instead of crashing the entire read.
-- **Stdin timeout leak**: \`clearTimeout\` now called in \`finally\` block for stdin reads in retrieval and hooks.
-- **Double JSONL read eliminated**: \`readMemoryItems()\` now returns \`deletedIds\` set, removing the need for a separate \`wasLessonDeleted()\` file read.
-- **FTS5 trigger optimization**: SQLite update trigger now scoped to FTS-indexed columns only, reducing unnecessary FTS rebuilds.
-- **Clustering noise accuracy**: Single-item clusters now correctly returned as \`noise\` instead of an always-empty noise array.
-- **Embed-worker path validation**: \`embed-worker\` command now validates that \`repoRoot\` exists and is a directory before proceeding.
-- **Script check timeout**: Rule-based script checks now have a 30-second default timeout, configurable via \`check.timeout\`.
+- **\`ca feedback\` command**: Surfaces the GitHub Discussions URL for bug reports and feature requests. \`ca feedback --open\` opens the page directly in the browser. Cross-platform (macOS \`open\`, Windows \`start\`, Linux \`xdg-open\`).
+- **Star and feedback prompt in \`ca about\`**: TTY sessions now see a star-us link and the GitHub Discussions URL after the changelog output.
 
 ### Changed
 
-- **Anchored approval detection**: Review loop now uses \`^REVIEW_APPROVED\` anchored grep to prevent false positives from partial-line matches.
-- **Numeric option validation**: \`--review-every\` and \`--max-review-cycles\` now reject NaN, negative, and non-integer values.
-- **\`isModelUsable()\` replaced**: \`compound\` command now uses lightweight \`isModelAvailable()\` (fs check) instead of loading the 278MB model just to probe.
-- **Dead code removed**: \`addCompoundAgentHook()\`, back-compat hook aliases (\`CLAUDE_READ_TRACKER_HOOK_CONFIG\`, \`CLAUDE_STOP_AUDIT_HOOK_CONFIG\`), and \`wasLessonDeleted()\` removed.
-- **Hardcoded model extracted**: Five occurrences of \`'claude-opus-4-6'\` in loop.ts extracted to \`DEFAULT_MODEL\` constant.
-- **EPIC_ID_PATTERN deduplicated**: \`watch.ts\` now imports \`LOOP_EPIC_ID_PATTERN\` from \`loop.ts\` instead of maintaining a duplicate.
-- **\`warn()\` output corrected**: \`shared.ts\` warn helper now writes to \`stderr\` instead of \`stdout\`.
-- **Templates import fixed**: \`templates.ts\` now imports \`VERSION\` from \`../version.js\` instead of barrel re-export.`;
+- **README overhaul**: Complete rewrite to present compound-agent as a full agentic development environment rather than a memory plugin.
+  - New thesis-driven one-liner that names category, mechanism, and benefit
+  - "What gets installed" inventory table (15 commands, 24 agent role skills, 7 hooks, 5 phase skills, 5 docs)
+  - Three principles section mapping each architecture layer to the problem it solves (Memory / Feedback Loops / Navigable Structure)
+  - "Agents are interchangeable" design principle explained in the overview
+  - Levels of use replacing flat Quick Start: memory-only, structured workflow, and factory mode with code examples
+  - \`/compound:architect\` promoted to its own section with 4-phase description and context-window motivation
+  - Infinity loop elevated from CLI table row to its own section with full flag examples and honest maturity note
+  - Automatic hooks table with per-hook descriptions
+  - Architecture diagram updated to reflect three-principle mapping and accurate counts
+  - Compound loop diagram updated with architect as optional upstream entry point
+  - "Open with an AI agent" entry point in the Documentation section`;
 
 // src/commands/about.ts
+var REPO_URL = "https://github.com/Nathandela/compound-agent";
+var DISCUSSIONS_URL = `${REPO_URL}/discussions`;
 function registerAboutCommand(program) {
   program.command("about").description("Show version, animation, and recent changelog").action(async () => {
     if (process.stdout.isTTY) {
@@ -10978,6 +10994,30 @@ function registerAboutCommand(program) {
     }
     console.log("");
     console.log(CHANGELOG_RECENT);
+    if (process.stdout.isTTY) {
+      console.log("");
+      console.log(`Find this useful? Star us: ${REPO_URL}`);
+      console.log(`Feedback & discussions:    ${DISCUSSIONS_URL}`);
+    }
+  });
+}
+var REPO_URL2 = "https://github.com/Nathandela/compound-agent";
+var DISCUSSIONS_URL2 = `${REPO_URL2}/discussions`;
+function openUrl(url) {
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  spawn(opener, [url], { detached: true, stdio: "ignore" }).unref();
+}
+function registerFeedbackCommand(program) {
+  program.command("feedback").description("Open GitHub Discussions to share feedback or report issues").option("--open", "Open the Discussions page in your browser").action((opts) => {
+    console.log(`Feedback & discussions: ${DISCUSSIONS_URL2}`);
+    console.log(`Repository:             ${REPO_URL2}`);
+    if (opts.open && process.stdout.isTTY) {
+      openUrl(DISCUSSIONS_URL2);
+      console.log("Opening in browser...");
+    } else if (!opts.open) {
+      console.log("");
+      console.log("Run `ca feedback --open` to open in your browser.");
+    }
   });
 }
 
@@ -11160,8 +11200,8 @@ function registerKnowledgeIndexCommand(program) {
     }
   });
   program.command("embed-worker <repoRoot>", { hidden: true }).description("Internal: background embedding worker").action(async (repoRoot) => {
-    const { existsSync: existsSync24, statSync: statSync7 } = await import('fs');
-    if (!existsSync24(repoRoot) || !statSync7(repoRoot).isDirectory()) {
+    const { existsSync: existsSync25, statSync: statSync7 } = await import('fs');
+    if (!existsSync25(repoRoot) || !statSync7(repoRoot).isDirectory()) {
       out.error(`Invalid repoRoot: "${repoRoot}" is not a directory`);
       process.exitCode = 1;
       return;
@@ -11264,6 +11304,41 @@ async function cleanLessonsAction() {
 function registerCleanLessonsCommand(program) {
   program.command("clean-lessons").description("Analyze lessons for semantic duplicates and contradictions").action(cleanLessonsAction);
 }
+var INSTALL_SCRIPT_URL = "https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh";
+var INSTALL_CMD = `curl -sSL ${INSTALL_SCRIPT_URL} | bash`;
+function registerInstallBeadsCommand(program) {
+  program.command("install-beads").description("Install the beads CLI via the official install script").option("--yes", "Skip confirmation prompt and install immediately").action((opts) => {
+    if (process.platform === "win32") {
+      console.error("Beads installation is not supported on Windows.");
+      process.exitCode = 1;
+      return;
+    }
+    if (checkBeadsAvailable().available) {
+      console.log("Beads CLI (bd) is already installed.");
+      return;
+    }
+    console.log(`Install script: ${INSTALL_SCRIPT_URL}`);
+    if (!opts.yes) {
+      console.log(`Run manually: ${INSTALL_CMD}`);
+      return;
+    }
+    const result = spawnSync("bash", ["-c", INSTALL_CMD], {
+      stdio: "inherit",
+      timeout: 6e4
+    });
+    if (result.error) {
+      console.error(`Installation error: ${result.error.message}`);
+      process.exitCode = 1;
+      return;
+    }
+    if (result.status !== 0) {
+      console.error(`Install error: process exited with code ${result.status}.`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log("Restart your shell or run: source ~/.bashrc");
+  });
+}
 
 // src/commands/capture.ts
 function createLessonFromFlags(trigger, insight, confirmed) {
@@ -11879,15 +11954,304 @@ function registerManagementCommands(program) {
   registerTestSummaryCommand(program);
   registerVerifyGatesCommand(program);
   registerAboutCommand(program);
+  registerFeedbackCommand(program);
   registerKnowledgeCommand(program);
   registerKnowledgeIndexCommand(program);
   registerCleanLessonsCommand(program);
+  registerInstallBeadsCommand(program);
   program.command("worktree").description("(removed) Use Claude Code native worktree support").action(() => {
     console.error("ca worktree has been removed. Use Claude Code's native EnterWorktree support instead.");
     process.exitCode = 1;
   });
 }
 
+// src/commands/improve-templates.ts
+function buildTopicDiscovery() {
+  return `
+get_topics() {
+  local improve_dir="\${IMPROVE_DIR:-improve}"
+  local topics=""
+  if [ -n "$TOPIC_FILTER" ]; then
+    # Use explicit topic list from CLI --topics
+    for topic in $TOPIC_FILTER; do
+      if [ -f "$improve_dir/\${topic}.md" ]; then
+        topics="$topics $topic"
+      else
+        log "WARN: $improve_dir/\${topic}.md not found, skipping"
+      fi
+    done
+  else
+    for f in "$improve_dir"/*.md; do
+      [ -f "$f" ] || continue
+      local topic
+      topic=$(basename "$f" .md)
+      topics="$topics $topic"
+    done
+  fi
+  topics="\${topics# }"
+  if [ -z "$topics" ]; then
+    log "No improve/*.md files found"
+    return 1
+  fi
+  echo "$topics"
+  return 0
+}
+`;
+}
+function buildImprovePrompt() {
+  return `
+build_improve_prompt() {
+  local topic="$1"
+  local improve_dir="\${IMPROVE_DIR:-improve}"
+  local program_file="$improve_dir/\${topic}.md"
+
+  if [ ! -f "$program_file" ]; then
+    log "ERROR: $program_file not found"
+    return 1
+  fi
+
+  # Stream static parts via quoted heredoc (no expansion) + file content via cat
+  # Avoids heredoc delimiter collision if .md file contains the delimiter string
+  cat <<'IMPROVE_PROMPT_HEADER'
+You are running in an autonomous improvement loop. Your task is to make ONE improvement to the codebase.
+
+## Your Program
+IMPROVE_PROMPT_HEADER
+
+  cat "$program_file"
+
+  cat <<'IMPROVE_PROMPT_FOOTER'
+
+## Rules
+- Make ONE focused improvement per iteration.
+- Run the validation described in your program.
+- If you successfully improved something and validation passes, commit your changes then output on its own line:
+  IMPROVED
+- If you tried but found nothing to improve (or improvements don't pass validation), output:
+  NO_IMPROVEMENT
+- If you encountered an error that prevents you from working, output:
+  FAILED
+- Do NOT ask questions -- there is no human.
+- Commit your changes before outputting the marker.
+- You can inspect what changed with git diff before committing.
+IMPROVE_PROMPT_FOOTER
+}
+`;
+}
+function buildImproveMarkerDetection() {
+  return `
+# detect_improve_marker() - Check for improvement markers in log and trace
+# Primary: macro log (anchored patterns). Fallback: trace JSONL (unanchored).
+# Usage: MARKER=$(detect_improve_marker "$LOGFILE" "$TRACEFILE")
+# Returns: "improved", "no_improvement", "failed", or "none"
+detect_improve_marker() {
+  local logfile="$1" tracefile="$2"
+
+  # Primary: check extracted text with anchored patterns
+  if [ -s "$logfile" ]; then
+    if grep -q "^IMPROVED$" "$logfile"; then
+      echo "improved"; return 0
+    elif grep -q "^NO_IMPROVEMENT$" "$logfile"; then
+      echo "no_improvement"; return 0
+    elif grep -q "^FAILED$" "$logfile"; then
+      echo "failed"; return 0
+    fi
+  fi
+
+  # Fallback: check raw trace JSONL (unanchored -- markers are inside JSON strings)
+  if [ -s "$tracefile" ]; then
+    if grep -q "IMPROVED" "$tracefile"; then
+      echo "improved"; return 0
+    elif grep -q "NO_IMPROVEMENT" "$tracefile"; then
+      echo "no_improvement"; return 0
+    elif grep -q "FAILED" "$tracefile"; then
+      echo "failed"; return 0
+    fi
+  fi
+
+  echo "none"
+}
+`;
+}
+function buildImproveObservability() {
+  return `
+# Observability: status file and execution log
+IMPROVE_STATUS_FILE="$LOG_DIR/.improve-status.json"
+IMPROVE_EXEC_LOG="$LOG_DIR/improvement-log.jsonl"
+
+write_improve_status() {
+  local status="$1"
+  local topic="\${2:-}"
+  local iteration="\${3:-0}"
+  if [ "$status" = "idle" ]; then
+    echo "{\\"status\\":\\"idle\\",\\"timestamp\\":\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\"}" > "$IMPROVE_STATUS_FILE"
+  else
+    echo "{\\"topic\\":\\"$topic\\",\\"iteration\\":$iteration,\\"started_at\\":\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\",\\"status\\":\\"$status\\"}" > "$IMPROVE_STATUS_FILE"
+  fi
+}
+
+log_improve_result() {
+  local topic="$1" result="$2" improvements="$3" duration="$4"
+  echo "{\\"topic\\":\\"$topic\\",\\"result\\":\\"$result\\",\\"improvements\\":$improvements,\\"duration_s\\":$duration,\\"timestamp\\":\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\"}" >> "$IMPROVE_EXEC_LOG"
+}
+`;
+}
+function buildImproveSessionRunner() {
+  return `
+    # Run claude session with two-scope logging
+    PROMPT=$(build_improve_prompt "$TOPIC")
+
+    claude --dangerously-skip-permissions \\
+           --model "$MODEL" \\
+           --output-format stream-json \\
+           --verbose \\
+           -p "$PROMPT" \\
+           2>"$LOGFILE.stderr" | tee "$TRACEFILE" | extract_text > "$LOGFILE" || true
+
+    # Append stderr to macro log
+    [ -f "$LOGFILE.stderr" ] && cat "$LOGFILE.stderr" >> "$LOGFILE" && rm -f "$LOGFILE.stderr"
+
+    # Health check: warn if macro log extraction failed
+    if [ -s "$TRACEFILE" ] && [ ! -s "$LOGFILE" ]; then
+      log "WARN: Macro log is empty but trace has content (extract_text may have failed)"
+    fi
+
+    MARKER=$(detect_improve_marker "$LOGFILE" "$TRACEFILE")
+`;
+}
+function buildImproveIterationBody() {
+  return buildImproveSessionRunner() + `
+
+    case "$MARKER" in
+      (improved)
+        # Verify the agent actually committed
+        if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+          log "WARN: Uncommitted changes detected after IMPROVED marker"
+        fi
+        log "Topic $TOPIC improved (iter $ITER)"
+        TOPIC_IMPROVED=$((TOPIC_IMPROVED + 1))
+        CONSECUTIVE_NO_IMPROVE=0
+        git tag -d "$TAG" 2>/dev/null || true
+        ;;
+      (no_improvement)
+        log "Topic $TOPIC: no improvement (iter $ITER), reverting"
+        git reset --hard "$TAG"
+        git clean -fd -e "$LOG_DIR/" 2>/dev/null || true
+        git tag -d "$TAG" 2>/dev/null || true
+        CONSECUTIVE_NO_IMPROVE=$((CONSECUTIVE_NO_IMPROVE + 1))
+        if [ $CONSECUTIVE_NO_IMPROVE -ge 2 ]; then
+          log "Diminishing returns for $TOPIC, moving on"
+          break
+        fi
+        ;;
+      (failed)
+        log "Topic $TOPIC failed (iter $ITER), reverting"
+        git reset --hard "$TAG"
+        git clean -fd -e "$LOG_DIR/" 2>/dev/null || true
+        git tag -d "$TAG" 2>/dev/null || true
+        TOPIC_FAILED=1
+        break
+        ;;
+      (*)
+        log "Topic $TOPIC: no marker detected (iter $ITER), reverting"
+        git reset --hard "$TAG"
+        git clean -fd -e "$LOG_DIR/" 2>/dev/null || true
+        git tag -d "$TAG" 2>/dev/null || true
+        TOPIC_FAILED=1
+        break
+        ;;
+    esac
+  done
+
+  TOPIC_DURATION=$(( $(date +%s) - TOPIC_START ))
+
+  if [ $TOPIC_IMPROVED -gt 0 ]; then
+    IMPROVED_COUNT=$((IMPROVED_COUNT + TOPIC_IMPROVED))
+    log_improve_result "$TOPIC" "improved" "$TOPIC_IMPROVED" "$TOPIC_DURATION"
+  elif [ $TOPIC_FAILED -eq 1 ]; then
+    FAILED_TOPICS=$((FAILED_TOPICS + 1))
+    log_improve_result "$TOPIC" "failed" "0" "$TOPIC_DURATION"
+  else
+    SKIPPED_TOPICS=$((SKIPPED_TOPICS + 1))
+    log_improve_result "$TOPIC" "no_improvement" "0" "$TOPIC_DURATION"
+  fi
+done`;
+}
+function buildImproveMainLoop(options) {
+  const embedded = options.embedded ?? false;
+  const guardOpen = embedded ? "IMPROVE_RESULT=1\nelse" : "exit 1\nfi";
+  const guardClose = embedded ? "fi" : "";
+  return `
+# Improve loop
+MAX_ITERS=${options.maxIters}
+TIME_BUDGET=${options.timeBudget}
+IMPROVED_COUNT=0
+FAILED_TOPICS=0
+SKIPPED_TOPICS=0
+IMPROVE_START=$(date +%s)
+
+# Worktree-clean preflight: refuse to run with dirty working tree
+if ! git diff --quiet 2>/dev/null || ! git diff --cached --quiet 2>/dev/null; then
+  log "ERROR: Working tree is dirty. Commit or stash changes before running the improvement loop."
+  log "  git status:"
+  git status --short
+  ${guardOpen}
+
+TOPICS=$(get_topics) || { log "No topics found, exiting"; ${embedded ? "IMPROVE_RESULT=0" : "exit 0"}; }
+log "Improve loop starting"
+log "Config: max_iters=$MAX_ITERS time_budget=$TIME_BUDGET model=$MODEL"
+log "Topics: $TOPICS"
+
+for TOPIC in $TOPICS; do
+  log "Starting topic: $TOPIC"
+  TOPIC_IMPROVED=0
+  TOPIC_FAILED=0
+  CONSECUTIVE_NO_IMPROVE=0
+  TOPIC_START=$(date +%s)
+
+  ITER=0
+  while [ $ITER -lt $MAX_ITERS ]; do
+    ITER=$((ITER + 1))
+
+    # Time budget check
+    if [ $TIME_BUDGET -gt 0 ]; then
+      ELAPSED=$(( $(date +%s) - IMPROVE_START ))
+      if [ $ELAPSED -ge $TIME_BUDGET ]; then
+        log "Time budget exhausted ($ELAPSED >= $TIME_BUDGET seconds)"
+        break 2
+      fi
+    fi
+
+    # Dry-run check BEFORE any side effects (tags, sessions)
+    if [ -n "\${IMPROVE_DRY_RUN:-}" ]; then
+      log "[DRY RUN] Would run claude session for $TOPIC (iter $ITER)"
+      TOPIC_IMPROVED=$((TOPIC_IMPROVED + 1))
+      continue
+    fi
+
+    TS=$(timestamp)
+    LOGFILE="$LOG_DIR/loop_improve_\${TOPIC}-\${TS}.log"
+    TRACEFILE="$LOG_DIR/trace_improve_\${TOPIC}-\${TS}.jsonl"
+    TAG="improve/\${TOPIC}/iter-\${ITER}/pre"
+
+    git tag -f "$TAG"
+    write_improve_status "running" "$TOPIC" "$ITER"
+    ln -sf "$(basename "$TRACEFILE")" "$LOG_DIR/.latest"
+
+    log "Iteration $ITER/$MAX_ITERS for $TOPIC"
+
+` + buildImproveIterationBody() + `
+
+# Summary
+TOTAL_DURATION=$(( $(date +%s) - IMPROVE_START ))
+echo "{\\"type\\":\\"summary\\",\\"improved\\":$IMPROVED_COUNT,\\"failed_topics\\":$FAILED_TOPICS,\\"skipped_topics\\":$SKIPPED_TOPICS,\\"total_duration_s\\":$TOTAL_DURATION}" >> "$IMPROVE_EXEC_LOG"
+write_improve_status "idle"
+log "Improve loop finished. Improvements: $IMPROVED_COUNT, Failed topics: $FAILED_TOPICS, Skipped: $SKIPPED_TOPICS"
+${embedded ? "IMPROVE_RESULT=$( [ $FAILED_TOPICS -eq 0 ] && echo 0 || echo 1 )" : "[ $FAILED_TOPICS -eq 0 ] && exit 0 || exit 1"}
+${guardClose}
+`;
+}
+
 // src/commands/loop-templates.ts
 function buildDependencyCheck() {
   return `
@@ -12203,7 +12567,7 @@ fi
 `
   };
 }
-function buildMainLoop(reviewOptions) {
+function buildMainLoop(reviewOptions, skipExit) {
   const { counterInit, periodic, final } = buildReviewTriggers(
     reviewOptions?.hasReview ?? false,
     reviewOptions?.reviewEvery ?? 0
@@ -12282,7 +12646,162 @@ TOTAL_DURATION=$(( $(date +%s) - LOOP_START ))
 echo "{\\"type\\":\\"summary\\",\\"completed\\":$COMPLETED,\\"failed\\":$FAILED,\\"skipped\\":$SKIPPED,\\"total_duration_s\\":$TOTAL_DURATION}" >> "$EXEC_LOG"
 write_status "idle"
 log "Loop finished. Completed: $COMPLETED, Failed: $FAILED, Skipped: $SKIPPED"
-[ $FAILED -eq 0 ] && exit 0 || exit 1`;
+${skipExit ? "" : "[ $FAILED -eq 0 ] && exit 0 || exit 1"}`;
+}
+
+// src/commands/improve.ts
+var TOPIC_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
+function buildImproveScriptHeader(timestamp, maxIters, timeBudget, model, topicFilter) {
+  return `#!/usr/bin/env bash
+# Improvement Loop - Generated by: ca improve
+# Date: ${timestamp}
+# Iterates over improve/*.md programs to autonomously improve the codebase.
+#
+# Usage:
+#   ./improvement-loop.sh
+#   IMPROVE_DRY_RUN=1 ./improvement-loop.sh  # Preview without executing
+
+set -euo pipefail
+
+# Config
+MAX_ITERS=${maxIters}
+TIME_BUDGET=${timeBudget}
+MODEL="${model}"
+TOPIC_FILTER="${topicFilter}"
+LOG_DIR="agent_logs"
+
+# Helpers
+timestamp() { date '+%Y-%m-%d_%H-%M-%S'; }
+log() { echo "[$(timestamp)] $*"; }
+die() { log "FATAL: $*"; exit 1; }
+
+command -v claude >/dev/null || die "claude CLI required"
+command -v git >/dev/null || die "git required"
+
+# Detect JSON parser: prefer jq, fall back to python3
+HAS_JQ=false
+command -v jq >/dev/null 2>&1 && HAS_JQ=true
+if [ "$HAS_JQ" = false ]; then
+  command -v python3 >/dev/null 2>&1 || die "jq or python3 required for JSON parsing"
+fi
+
+mkdir -p "$LOG_DIR"
+`;
+}
+function validateImproveOptions(options) {
+  if (!Number.isInteger(options.maxIters) || options.maxIters <= 0) {
+    throw new Error(`Invalid maxIters: must be a positive integer, got ${options.maxIters}`);
+  }
+  if (!Number.isInteger(options.timeBudget) || options.timeBudget < 0) {
+    throw new Error(`Invalid timeBudget: must be a non-negative integer, got ${options.timeBudget}`);
+  }
+  if (!MODEL_PATTERN.test(options.model)) {
+    throw new Error(`Invalid model "${options.model}": must match ${MODEL_PATTERN}`);
+  }
+  if (options.topics) {
+    for (const topic of options.topics) {
+      if (!TOPIC_NAME_PATTERN.test(topic)) {
+        throw new Error(`Invalid topic "${topic}": must match ${TOPIC_NAME_PATTERN}`);
+      }
+    }
+  }
+}
+function generateImproveScript(options) {
+  validateImproveOptions(options);
+  const topicFilter = options.topics?.join(" ") ?? "";
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  return buildImproveScriptHeader(timestamp, options.maxIters, options.timeBudget, options.model, topicFilter) + buildTopicDiscovery() + buildImprovePrompt() + buildStreamExtractor() + buildImproveMarkerDetection() + buildImproveObservability() + buildImproveMainLoop({ maxIters: options.maxIters, timeBudget: options.timeBudget });
+}
+async function handleImprove(cmd, options) {
+  const maxIters = Number(options.maxIters ?? 5);
+  const timeBudget = Number(options.timeBudget ?? 0);
+  const scriptOptions = {
+    topics: options.topics,
+    maxIters,
+    timeBudget,
+    model: options.model ?? DEFAULT_LOOP_MODEL
+  };
+  try {
+    validateImproveOptions(scriptOptions);
+  } catch (err) {
+    out.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.dryRun) {
+    out.info("Dry run - improvement loop plan:");
+    out.info(`  Topics: ${scriptOptions.topics?.join(", ") ?? "(all improve/*.md)"}`);
+    out.info(`  Max iterations per topic: ${scriptOptions.maxIters}`);
+    out.info(`  Time budget: ${scriptOptions.timeBudget === 0 ? "unlimited" : `${scriptOptions.timeBudget}s`}`);
+    out.info(`  Model: ${scriptOptions.model}`);
+    if (existsSync("improve")) {
+      out.info("  improve/ directory exists");
+    } else {
+      out.warn("  improve/ directory not found - create it with improve/*.md files");
+    }
+    return;
+  }
+  const outputPath = resolve(options.output ?? "./improvement-loop.sh");
+  if (existsSync(outputPath) && !options.force) {
+    out.error(`File already exists: ${outputPath}`);
+    out.info("Use --force to overwrite");
+    process.exitCode = 1;
+    return;
+  }
+  let script;
+  try {
+    script = generateImproveScript(scriptOptions);
+  } catch (err) {
+    out.error(err.message);
+    process.exitCode = 1;
+    return;
+  }
+  await mkdir(dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, script, "utf-8");
+  await chmod(outputPath, 493);
+  out.success(`Generated improvement loop script: ${outputPath}`);
+  out.info("Run it with: " + outputPath);
+  out.info("Preview with: IMPROVE_DRY_RUN=1 " + outputPath);
+}
+var EXAMPLE_PROGRAM = `# Linting
+
+## What to improve
+Find and fix lint violations in the codebase.
+
+## How to find work
+Run the project linter and look for violations:
+\`\`\`bash
+pnpm lint 2>&1 | head -50
+\`\`\`
+
+## How to validate
+After fixing, run the linter again and confirm fewer violations:
+\`\`\`bash
+pnpm lint
+pnpm test
+\`\`\`
+`;
+async function handleImproveInit(cmd) {
+  const improveDir = "improve";
+  const examplePath = resolve(improveDir, "example.md");
+  if (existsSync(examplePath)) {
+    out.info(`improve/ directory already exists with ${examplePath}`);
+    out.info("Add more .md files to define additional improvement topics.");
+    return;
+  }
+  await mkdir(improveDir, { recursive: true });
+  await writeFile(examplePath, EXAMPLE_PROGRAM, "utf-8");
+  out.success(`Created ${examplePath}`);
+  out.info("Edit this file or add more .md files to define improvement topics.");
+  out.info("Then run: ca improve");
+}
+function registerImproveCommands(program) {
+  const improveCmd = program.command("improve").description("Generate improvement loop script").option("--topics <names...>", "Specific topics to process").option("-o, --output <path>", "Output script path", "./improvement-loop.sh").option("--max-iters <n>", "Max iterations per topic", "5").option("--time-budget <seconds>", "Total time budget, 0=unlimited", "0").option("--model <model>", "Claude model to use", DEFAULT_LOOP_MODEL).option("--force", "Overwrite existing script").option("--dry-run", "Validate and print plan without generating").action(async function(options) {
+    await handleImprove(this, options);
+  });
+  improveCmd.command("init").description("Print guidance about creating improve/*.md files").action(async function() {
+    await handleImproveInit();
+  });
 }
 
 // src/commands/loop-review-templates.ts
@@ -12453,8 +12972,8 @@ spawn_reviewers() {
     case "$reviewer" in
       (claude-sonnet|claude-opus)
         local model_name
-        if [ "$reviewer" = "claude-sonnet" ]; then model_name="claude-sonnet-4-6"
-        else model_name="claude-opus-4-6"; fi
+        if [ "$reviewer" = "claude-sonnet" ]; then model_name="claude-sonnet-4-6[1m]"
+        else model_name="claude-opus-4-6[1m]"; fi
         local sid=""
         sid=$(read_session_id "$reviewer" "$REVIEW_DIR/sessions.json")
         if [ "$cycle" -eq 1 ]; then
@@ -12580,8 +13099,6 @@ run_review_phase() {
 
 // src/commands/loop.ts
 var LOOP_EPIC_ID_PATTERN = /^[a-zA-Z0-9_.-]+$/;
-var DEFAULT_MODEL = "claude-opus-4-6";
-var MODEL_PATTERN = /^[a-zA-Z0-9_.:/-]+$/;
 function buildScriptHeader(timestamp, maxRetries, model, epicIds) {
   return `#!/usr/bin/env bash
 # Infinity Loop - Generated by: ca loop
@@ -12675,6 +13192,14 @@ function validateOptions(options) {
       throw new Error(`Invalid maxReviewCycles: must be a positive integer, got ${options.maxReviewCycles}`);
     }
   }
+  if (options.improve) {
+    if (!Number.isInteger(options.improve.maxIters) || options.improve.maxIters <= 0) {
+      throw new Error(`Invalid improve maxIters: must be a positive integer, got ${options.improve.maxIters}`);
+    }
+    if (!Number.isInteger(options.improve.timeBudget) || options.improve.timeBudget < 0) {
+      throw new Error(`Invalid improve timeBudget: must be a non-negative integer, got ${options.improve.timeBudget}`);
+    }
+  }
 }
 function generateLoopScript(options) {
   validateOptions(options);
@@ -12687,7 +13212,7 @@ function generateLoopScript(options) {
       reviewers: options.reviewers,
       maxReviewCycles: options.maxReviewCycles ?? 3,
       reviewBlocking: options.reviewBlocking ?? false,
-      reviewModel: options.reviewModel ?? DEFAULT_MODEL,
+      reviewModel: options.reviewModel ?? DEFAULT_LOOP_MODEL,
       reviewEvery: options.reviewEvery ?? 0
     });
     script += buildReviewerDetection();
@@ -12697,7 +13222,24 @@ function generateLoopScript(options) {
     script += buildImplementerPhase();
     script += buildReviewLoop();
   }
-  script += buildMainLoop(hasReview ? { hasReview: true, reviewEvery: options.reviewEvery ?? 0 } : void 0);
+  const hasImprove = !!options.improve;
+  script += buildMainLoop(
+    hasReview ? { hasReview: true, reviewEvery: options.reviewEvery ?? 0 } : void 0,
+    hasImprove
+    // skipExit when improvement phase follows
+  );
+  if (options.improve) {
+    script += "\n# Improvement phase (runs after epic loop completes successfully)\n";
+    script += "if [ $FAILED -eq 0 ]; then\n";
+    script += '  log "Epic loop completed successfully, starting improvement phase"\n';
+    script += buildTopicDiscovery();
+    script += buildImprovePrompt();
+    script += buildImproveMarkerDetection();
+    script += buildImproveObservability();
+    script += buildImproveMainLoop({ ...options.improve, embedded: true });
+    script += "\nfi\n";
+    script += '[ $FAILED -eq 0 ] && [ "${IMPROVE_RESULT:-0}" -eq 0 ] && exit 0 || exit 1\n';
+  }
   return script;
 }
 async function handleLoop(cmd, options) {
@@ -12716,17 +13258,20 @@ async function handleLoop(cmd, options) {
   }
   const reviewEvery = Number(options.reviewEvery ?? 0);
   const maxReviewCycles = Number(options.maxReviewCycles ?? 3);
+  const improveMaxIters = Number(options.improveMaxIters ?? 5);
+  const improveTimeBudget = Number(options.improveTimeBudget ?? 0);
   let script;
   try {
     script = generateLoopScript({
       epics: options.epics,
       maxRetries,
-      model: options.model ?? DEFAULT_MODEL,
+      model: options.model ?? DEFAULT_LOOP_MODEL,
       reviewers: options.reviewers,
       reviewEvery,
       maxReviewCycles,
       reviewBlocking: options.reviewBlocking,
-      reviewModel: options.reviewModel ?? DEFAULT_MODEL
+      reviewModel: options.reviewModel ?? DEFAULT_LOOP_MODEL,
+      improve: options.improve ? { maxIters: improveMaxIters, timeBudget: improveTimeBudget } : void 0
     });
   } catch (err) {
     out.error(err.message);
@@ -12741,7 +13286,7 @@ async function handleLoop(cmd, options) {
   out.info("Preview with: LOOP_DRY_RUN=1 " + outputPath);
 }
 function registerLoopCommands(program) {
-  program.command("loop").description("Generate infinity loop script for epic tasks").option("--epics <ids...>", "Specific epic IDs to process").option("-o, --output <path>", "Output script path", "./infinity-loop.sh").option("--max-retries <n>", "Max retries per epic on failure", "1").option("--model <model>", "Claude model to use", DEFAULT_MODEL).option("--force", "Overwrite existing script").option("--review-every <n>", "Review every N completed epics (0=end-only)", "0").option("--reviewers <names...>", "Reviewers to use (claude-sonnet claude-opus gemini codex)").option("--max-review-cycles <n>", "Max review/fix iterations", "3").option("--review-blocking", "Fail loop if review not approved after max cycles").option("--review-model <model>", "Model for implementer fix sessions", DEFAULT_MODEL).action(async function(options) {
+  program.command("loop").description("Generate infinity loop script for epic tasks").option("--epics <ids...>", "Specific epic IDs to process").option("-o, --output <path>", "Output script path", "./infinity-loop.sh").option("--max-retries <n>", "Max retries per epic on failure", "1").option("--model <model>", "Claude model to use", DEFAULT_LOOP_MODEL).option("--force", "Overwrite existing script").option("--review-every <n>", "Review every N completed epics (0=end-only)", "0").option("--reviewers <names...>", "Reviewers to use (claude-sonnet claude-opus gemini codex)").option("--max-review-cycles <n>", "Max review/fix iterations", "3").option("--review-blocking", "Fail loop if review not approved after max cycles").option("--review-model <model>", "Model for implementer fix sessions", DEFAULT_LOOP_MODEL).option("--improve", "Run improvement phase after all epics complete").option("--improve-max-iters <n>", "Max improvement iterations per topic", "5").option("--improve-time-budget <seconds>", "Total improvement time budget, 0=unlimited", "0").action(async function(options) {
     await handleLoop(this, options);
   });
 }
@@ -12798,7 +13343,7 @@ function formatStreamEvent(event) {
     }
     case "result": {
       const text = typeof event.result === "string" ? event.result : "";
-      const markers = ["EPIC_COMPLETE", "EPIC_FAILED", "HUMAN_REQUIRED"];
+      const markers = ["EPIC_COMPLETE", "EPIC_FAILED", "HUMAN_REQUIRED", "NO_IMPROVEMENT", "IMPROVED", "FAILED"];
       const found = markers.find((m) => text.includes(m));
       if (found) {
         const markerLine = text.split("\n").find((l) => l.includes(found)) ?? found;
@@ -12811,19 +13356,19 @@ function formatStreamEvent(event) {
       return null;
   }
 }
-function findLatestTraceFile(logDir) {
+function findLatestTraceFile(logDir, prefix = "trace_") {
   if (!existsSync(logDir)) return null;
   const latestPath = join(logDir, ".latest");
   if (existsSync(latestPath)) {
     try {
       const target = readlinkSync(latestPath);
       const resolved = resolve(logDir, target);
-      if (existsSync(resolved)) return resolved;
+      if (existsSync(resolved) && target.startsWith(prefix)) return resolved;
     } catch {
     }
   }
   try {
-    const files = readdirSync(logDir).filter((f) => f.startsWith("trace_") && f.endsWith(".jsonl")).sort().reverse();
+    const files = readdirSync(logDir).filter((f) => f.startsWith(prefix) && f.endsWith(".jsonl")).sort().reverse();
     const first = files[0];
     if (first) return join(logDir, first);
   } catch {
@@ -12888,7 +13433,7 @@ async function handleWatch(cmd, options) {
     }
     if (existsSync(logDir)) {
       try {
-        const files = readdirSync(logDir).filter((f) => f.startsWith(`trace_${options.epic}`) && f.endsWith(".jsonl")).sort().reverse();
+        const files = readdirSync(logDir).filter((f) => f.startsWith(`trace_${options.epic}-`) && f.endsWith(".jsonl")).sort().reverse();
         const first = files[0];
         if (first) traceFile = join(logDir, first);
       } catch {
@@ -12899,6 +13444,13 @@ async function handleWatch(cmd, options) {
       process.exitCode = 1;
       return;
     }
+  } else if (options.improve) {
+    traceFile = findLatestTraceFile(logDir, "trace_improve_");
+    if (!traceFile) {
+      out.info("No improvement trace found. Run `ca improve` to generate an improvement loop script first.");
+      process.exitCode = 0;
+      return;
+    }
   } else {
     traceFile = findLatestTraceFile(logDir);
     if (!traceFile) {
@@ -12911,7 +13463,7 @@ async function handleWatch(cmd, options) {
   await tailFile(traceFile, follow);
 }
 function registerWatchCommand(program) {
-  program.command("watch").description("Tail and pretty-print live trace from infinity loop sessions").option("--epic <id>", "Watch a specific epic trace").option("--no-follow", "Print existing trace and exit (no live tail)").action(async function(options) {
+  program.command("watch").description("Tail and pretty-print live trace from infinity loop sessions").option("--epic <id>", "Watch a specific epic trace").option("--improve", "Watch improvement loop traces").option("--no-follow", "Print existing trace and exit (no live tail)").action(async function(options) {
     await handleWatch(this, options);
   });
 }
@@ -13051,6 +13603,7 @@ function createProgram() {
   registerManagementCommands(program);
   registerSetupCommands(program);
   registerCompoundCommands(program);
+  registerImproveCommands(program);
   registerLoopCommands(program);
   registerWatchCommand(program);
   registerPhaseCheckCommand(program);
@@ -13072,7 +13625,7 @@ function createProgram() {
 }
 async function runProgram(program, argv = process.argv) {
   let updatePromise = null;
-  if (process.stdout.isTTY) {
+  if (shouldCheckForUpdate()) {
     try {
       const cacheDir = join(getRepoRoot(), ".claude", ".cache");
       updatePromise = checkForUpdate(cacheDir);