@poetic-ai/poetic 1.42.0

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,2232 @@
+# Troubleshooting Guide
+
+> **Comprehensive troubleshooting guide for Poetic AI orchestration CLI**
+>
+> Common errors, solutions, and debugging techniques based on real-world issues
+
+---
+
+## Table of Contents
+
+- [Quick Reference](#quick-reference)
+- [Disk Filled by Provider Temp Files](#disk-filled-by-provider-temp-files)
+- [Recovering Competition Results](#recovering-competition-results)
+- [Flywheel Operator Recovery](#flywheel-operator-recovery)
+- [Common Errors & Solutions](#common-errors--solutions)
+- [Error Codes & Meanings](#error-codes--meanings)
+- [Provider-Specific Issues](#provider-specific-issues)
+- [Installation & Setup Problems](#installation--setup-problems)
+- [Debugging Tips](#debugging-tips)
+- [Advanced Troubleshooting](#advanced-troubleshooting)
+
+---
+
+## Quick Reference
+
+| Issue Type | Quick Fix | Full Guide |
+|------------|-----------|------------|
+| **Disk pressure** | `poetic cleanup provider-temp --use-default-roots` | [Disk Filled by Provider Temp Files](#disk-filled-by-provider-temp-files) |
+| **LaunchAgent stale** | `poetic cleanup temp-agent --status` | [LaunchAgent Stale After Repo Move](#launchagent-stale-after-repo-move) |
+| **Stale CLI Build** | `./scripts/build-poetic.sh` | [Stale CLI Build](#stale-cli-build) |
+| **Missing Dependencies** | `npm ci` | [Missing Runtime Dependencies](#missing-runtime-dependencies) |
+| **Authentication** | Check API keys | [Provider-Specific Issues](#provider-specific-issues) |
+| **Grok auth/readiness** | `grok login --device-auth` (or `grok login` / `grok`); optional `XAI_API_KEY` for CI/headless | [Grok Issues](#grok-issues) |
+| **Installation** | Verify CLI tools | [Installation & Setup Problems](#installation--setup-problems) |
+| **Execution** | Use `--verbose` flag | [Debugging Tips](#debugging-tips) |
+| **Codex Timeout** | Check bot comments | [Codex Issues](#codex-issues) |
+| **Parallel Failures** | Reduce concurrency | [Parallel Execution Problems](#parallel-execution-problems) |
+| **Worktree cleaned up** | Use `poetic compete apply` | [Recovering Competition Results](#recovering-competition-results) |
+| **Autoloop stuck or unclear** | `poetic loop explain <taskId>` | [Autoloop Diagnosis](#autoloop-diagnosis) |
+
+---
+
+## Disk Filled by Provider Temp Files
+
+**Symptoms**: Disk full warnings on a development machine, or `df -h` shows `/` or `/private` near capacity. Common on always-on machines that run long Claude Code sessions.
+
+**Cause**: AI providers write temp files during execution and don't always clean up after themselves. Two directories are the primary culprits:
+
+- `/private/tmp/claude-<UID>/` — Claude Code writes sandbox isolation files here during sessions
+- `/private/tmp/claude-mcp-npm-cache` — npm package cache used by MCP server processes (e.g. brave-search, exa-api, tavily); redirected here intentionally to keep it out of `~/.npm`
+
+> macOS may clear `/private/tmp` on its own schedule, but this is not reliable on always-on machines and should not be relied upon when disk pressure is active.
+
+### Quick fix (one-time dry-run)
+
+```bash
+# Preview what would be deleted (no changes made)
+poetic cleanup provider-temp --use-default-roots
+
+# Run the actual cleanup (files older than 24h by default)
+poetic cleanup provider-temp --use-default-roots --execute
+```
+
+### Automated cleanup (recommended for long-running machines)
+
+Install a macOS LaunchAgent that runs cleanup daily in the background by default:
+
+```bash
+poetic cleanup temp-agent --install-launchagent --use-default-roots
+```
+
+Logs are written to `~/.poetic/logs/temp-cleanup.log`. To check status:
+
+```bash
+poetic cleanup temp-agent --status
+```
+
+### Configuration
+
+Override the defaults in `.poetic/config/poetic.config.jsonc`:
+
+```js
+cleanup: {
+  providerTemp: {
+    roots: ['/private/tmp/claude-501', '/private/tmp/claude-mcp-npm-cache'],
+    maxAgeHours: 24,  // default: 24
+  }
+}
+```
+
+When `cleanup.providerTemp.roots` is set in config, `poetic cleanup temp-agent --install-launchagent` uses those roots without requiring `--use-default-roots`.
+
+### LaunchAgent stale after repo move
+
+If you move or rebuild the Poetic repo, the LaunchAgent wrapper embeds the old binary path and silently skips cleanup. Check for staleness:
+
+```bash
+poetic cleanup temp-agent --status
+# Shows "MISSING" next to Binary or Node if the embedded paths are gone
+```
+
+Fix:
+
+```bash
+poetic cleanup temp-agent --install-launchagent --use-default-roots
+# Reinstalls the wrapper with current binary and Node paths
+```
+
+---
+
+## Recovering Competition Results
+
+If the worktree was cleaned up before you could apply competition results (e.g. the output showed "Worktree cleaned up. Recover via: ..."):
+
+Before applying, check out a delivery branch. Non-dry-run
+`poetic compete apply` is intentionally blocked on `run/*`, `validation/*`, and
+generated `poetic/*` artifact branches. Use `fix/*` for product code, `docs/*`
+for documentation-only patches, or `test/*` for test-only patches.
+
+### Method 1: Use `poetic compete apply` (Recommended)
+
+```bash
+# Apply winner's changes from most recent competition
+poetic compete apply
+
+# Apply specific competition
+poetic compete apply <task-id>
+
+# Preview without applying
+poetic compete apply <task-id> --dry-run
+```
+
+The command recovers the diff from telemetry (state/variants) when the worktree directory no longer exists.
+
+### Method 2: Manual recovery from telemetry
+
+If `poetic compete apply` is unavailable or you need to inspect the raw diff:
+
+1. Find the variant state file: `ls .poetic/telemetry/state/variants/ | grep <task-id>`
+2. Extract the diff: `cat .poetic/telemetry/state/variants/<filename>.json | jq -r '.worktreeDiff' > changes.patch`
+3. Apply the patch: `git apply changes.patch`
+
+---
+
+## Autoloop Diagnosis
+
+Use these commands when `poetic run --autoloop` stops unexpectedly, appears
+stuck, or reports an unclear completion status:
+
+```bash
+poetic run autoloop history --last 10
+poetic run autoloop stats
+poetic loop explain <taskId>
+```
+
+`poetic run autoloop history` lists recent CLI and Flywheel autoloop runs.
+`poetic run autoloop stats` summarizes aggregate outcomes. `poetic loop explain`
+shows a run's termination reason, completion summary, blocking issues, gate
+state, semantic validation state, artifact paths, and worktree path when
+available.
+
+If durable run artifacts exist but `poetic run autoloop history` is incomplete,
+rebuild the append-only ledger:
+
+```bash
+poetic run autoloop backfill
+```
+
+Timebox units differ by surface: `--autoloop-timebox` is whole minutes, while
+`POETIC_AUTOLOOP_TIMEBOX_MS` is milliseconds. `POETIC_AUTOLOOP_TIMEBOX` remains
+supported as a legacy millisecond alias. If an env value was intended as
+minutes, convert it before retrying. When both environment variables are set,
+the explicit `_MS` variable takes precedence.
+
+Autoloop uses an isolated worktree by default. Use `--preserve-worktrees` before
+retrying when you need to inspect failed or partial edits. Use `--in-place` only
+when direct writes to the current working tree are intended; it refuses a dirty
+tree unless `--allow-dirty` is also set.
+
+Only one CLI autoloop can hold the per-repo lock at a time. If a new run reports
+an active lock after a crash, inspect recent history and check that no owning
+process is still running. The lock is `.poetic/autoloop/.run.lock`; remove it
+only when the process is gone and the lock is older than the 90-minute stale
+window.
+
+---
+
+## Flywheel Operator Recovery
+
+Use this sequence when operating an independent Flywheel workflow or recovering
+from an incomplete run:
+
+```bash
+# Before provider execution
+poetic run flywheel catalog
+poetic run flywheel validate <workflow>
+poetic run flywheel plan <workflow>
+poetic run flywheel run <workflow>              # preview only
+poetic run flywheel run <workflow> --execute
+
+# After the run prints a workflowId
+poetic run flywheel status <workflow-id>
+poetic run flywheel inspect <workflow-id>
+
+# Review before integrating
+git diff <baseSha>..poetic/flywheel/<workflow-id>
+poetic run flywheel merge-result <workflow-id> --dry-run
+poetic run flywheel merge-result <workflow-id>
+
+# Cleanup is preview-only by default
+poetic run flywheel cleanup <workflow-id>
+poetic run flywheel cleanup <workflow-id> --execute
+```
+
+If a stage needs manual repair, fix the run branch and then re-run persisted
+quality gates with `poetic run flywheel reverify <workflow-id> <stage-id> --dry-run`.
+After reviewing the commands, use `--yes` for non-interactive reverification.
+
+---
+
+## Common Errors & Solutions
+
+### CLI Task Description Quoting Issues
+
+**Error**: `Error: Too many arguments provided` when running `poetic compete` or `poetic run`
+
+**Symptoms**: Command fails immediately with "too many arguments" error message.
+
+**Cause**: Task descriptions containing spaces must be quoted. Without quotes, the shell splits the description into multiple arguments.
+
+**Resolution**:
+```bash
+#  Wrong (unquoted task description):
+poetic compete Add error handling to auth.ts --variant claude:conservative:local
+
+#  Correct (quoted task description):
+poetic compete "Add error handling to auth.ts" --variant claude:conservative:local
+```
+
+**Improved Error Messages (v0.1.0+):**
+The CLI now provides helpful guidance when this error occurs:
+```
+ Error: Too many arguments provided
+
+ Tip: Task description must be quoted if it contains spaces:
+   Correct: poetic compete "Task description here" --variant ...
+   Wrong:    poetic compete Task description here --variant ...
+```
+
+**Prevention:**
+- Always quote task descriptions that contain spaces
+- Use single quotes if description contains double quotes: `'Task with "quoted" text'`
+- Use backslash escaping for complex cases: `"Task with \"nested\" quotes"`
+- For long or multiline tasks, prefer `--task-file`:
+  - `poetic run --task-file task.txt`
+  - `poetic compete --task-file task.txt --variant ...`
+
+### Stale CLI Build
+
+**Error**: `Failed to load CLI: Dynamic require of "fs" is not supported` or `Cannot find module './index.js'`
+
+**Symptoms**:
+- CLI commands fail immediately on startup
+- Error message mentions "Dynamic require" or missing modules
+- Occurs after `git pull`, `git checkout`, or editing source files
+
+**Cause**: The compiled CLI in `dist/` is missing or outdated. This happens because:
+- `dist/` is gitignored (not tracked in version control)
+- Source files (`src/`) changed after your last build
+- The `prepare` hook only runs during `npm install`, not after git operations
+
+**Resolution**:
+
+1. **Quick fix** - Rebuild and rewire the local CLI:
+   ```bash
+   ./scripts/build-poetic.sh
+   ```
+
+2. **Compilation-only alternative** - Rebuild `dist/` without relinking:
+   ```bash
+   npm run build
+   ```
+
+3. **Verify the build**:
+   ```bash
+   # Check that dist/ was created and is recent
+   ls -la dist/entry.js
+   ```
+
+**When to rebuild**:
+-  After `git pull` or `git fetch && git merge`
+-  After `git checkout` to a different branch
+-  After editing any files in `src/` directory
+-  After `git cherry-pick`, `git rebase`, or similar operations
+-  NOT needed after `npm install` (automatic via `prepare` hook)
+
+**Improved error message (v0.1.0+)**:
+
+The CLI now detects stale builds and provides clear instructions:
+
+```
+ CLI build is missing or outdated
+
+ How to fix:
+  1) Rebuild and rewire the CLI:
+     ./scripts/build-poetic.sh
+
+  2) Or compile dist/ only:
+     npm run build
+
+ Common causes:
+  • git pull/checkout changed source files
+  • Local edits to src/ directory
+  • Deleted dist/ directory
+
+For more help: docs/TROUBLESHOOTING.md#stale-cli-build
+```
+
+**Prevention**:
+- Remember to run `./scripts/build-poetic.sh` after pulling source changes
+- Add to your workflow: `git pull && ./scripts/build-poetic.sh`
+- Consider setting up a git post-merge hook for automatic rebuilds
+
+**Technical details**:
+- The CLI uses ESM modules with dynamic imports for performance
+- When `dist/` is stale, the import chain fails with cryptic Node.js module errors
+- The build process (via tsup) bundles TypeScript source into optimized JavaScript
+
+### Missing Runtime Dependencies
+
+**Error**: `Missing runtime dependencies for Poetic CLI in /path/to/install: @anthropic-ai/sdk, ...` or `Cannot find package '@anthropic-ai/sdk'`
+
+**Symptoms**:
+- `poetic compete` or `poetic run` fails immediately with a missing dependencies message
+- Claude provider variant crashes at startup (4s) with an opaque SDK import error
+- AI judges fail with `Cannot find package '@anthropic-ai/sdk' imported from dist/transports-*.js`
+
+**Cause**: Node.js runtime dependencies declared in `package.json` are not installed. This typically happens after:
+- Cloning the repo without running `npm ci`
+- Switching branches where `package.json` changed
+- Deleted or corrupt `node_modules/`
+
+**Resolution**:
+```bash
+npm ci
+npm run build
+```
+
+**Bypass** (for test/mock environments):
+
+| Variable | Effect |
+|----------|--------|
+| `POETIC_SKIP_RUNTIME_DEP_CHECKS=1` | Skip only the runtime dependency preflight |
+| `POETIC_SKIP_TOOLING_CHECKS=1` | Skip all tooling preflight checks (includes dependency check) |
+| `POETIC_E2E_TEST=1` | Skip preflight (end-to-end test harness) |
+| `POETIC_MOCK_PROVIDERS=1` (with test runner or `POETIC_ALLOW_MOCK_PROVIDERS=1`) | Skip preflight when mock providers are actually permitted; outside tests, both flags are required or startup scrubs the mock flag |
+
+These env vars are intended for CI, test harnesses, and environments where dependencies are lazily or externally provided. Do not use them to mask a broken local install.
+
+### `poetic do` Apply Conflicts
+
+**Error**: `Failed to apply worktree diff to repo` or `Cannot apply patch - conflicts detected`
+
+**Symptoms**:
+- `poetic do` execution completes successfully in the isolated worktree
+- Quality gates pass (if enabled)
+- Apply step fails with conflict errors
+- Worktree is preserved for inspection
+- Patch file saved to `.poetic/tmp/do-apply-failures/`
+
+**Cause**: The changes made in the isolated worktree conflict with the current state of your repository. This happens when:
+- Repository HEAD moved during `poetic do` execution (someone pushed changes)
+- Working tree has uncommitted changes that conflict with worktree changes
+- File was modified/deleted in repo since worktree was created
+- Merge conflict between worktree patch and current repo state
+
+**Resolution**:
+
+The error output provides four recovery options:
+
+**Option 1: Inspect Changes (Recommended first step)**
+```bash
+# Navigate to the preserved worktree
+cd <preserved-worktree-path-from-output>
+
+# View all changes made
+git diff <baseline-sha>
+
+# View specific file changes
+git diff <baseline-sha> -- path/to/file.ts
+```
+
+**Option 2: Manual Apply with 3-Way Merge**
+```bash
+# Attempt manual apply with conflict resolution
+git apply --3way .poetic/tmp/do-apply-failures/apply-failed-<timestamp>.patch
+
+# If conflicts occur, you'll see markers in files:
+# <<<<<<< ours (current repo state)
+# =======
+# >>>>>>> theirs (worktree changes)
+
+# Fix conflicts manually, then:
+git add <conflicted-files>
+git status  # Verify resolution
+```
+
+**Option 3: View Patch Content**
+```bash
+# Inspect what the patch would do
+cat .poetic/tmp/do-apply-failures/apply-failed-<timestamp>.patch
+
+# Or use less for large patches
+less .poetic/tmp/do-apply-failures/apply-failed-<timestamp>.patch
+```
+
+**Option 4: Cherry-Pick from Worktree**
+```bash
+# Navigate to worktree
+cd <preserved-worktree-path-from-output>
+
+# Find the commit(s) made by the provider
+git log --oneline -n 5
+
+# Cherry-pick specific commit(s) into main repo
+cd <back-to-main-repo>
+git cherry-pick <commit-sha-from-worktree>
+```
+
+**After Recovery:**
+```bash
+# Clean up the preserved worktree
+poetic cleanup stale --only worktrees --worktree-age 0 --execute
+```
+
+**Prevention:**
+
+1. **Keep repo clean** - Commit or stash changes before running `poetic do`:
+   ```bash
+   git status  # Check for uncommitted changes
+   git stash   # Or commit them
+   poetic do "task"
+   ```
+
+2. **Use `--allow-dirty` carefully** - Only when you understand the risk:
+   ```bash
+   poetic do "task" --allow-dirty
+   ```
+
+3. **Check for upstream changes** - Pull latest before long-running tasks:
+   ```bash
+   git pull
+   poetic do "task"
+   ```
+
+4. **Use `--preserve-worktree` for debugging** - Inspect without auto-cleanup:
+   ```bash
+   poetic do "task" --preserve-worktree --verbose
+   ```
+
+**Related:**
+- [poetic do](CLI_REFERENCE.md#poetic-do) command reference
+- Worktree isolation behavior and its limits; isolation is not a comprehensive safety guarantee
+
+### Claude CLI variants always fail with "empty changes"
+
+**Symptoms**: Claude CLI variants complete execution but are marked as failed with error "Variant produced no changes (empty result)" despite actually modifying files.
+
+**Error**:
+```
+ claude default-model conservative: Completed in 24.4s (local)
+ Competition failed: No variants succeeded
+```
+
+**Cause**: This is a critical architectural issue with two different workspace edit models:
+
+1. **JSONL Protocol** (Cursor, Codex, GLM): Provider emits edits to `.poetic/edits.jsonl` during execution
+2. **Git-Detection** (Claude CLI): Provider writes files directly, changes detected via `git status` after execution
+
+The issue occurs when code uses `workspaceEditsApplied` (count of edits we wrote) instead of `workspaceEditsRequested` (count of edits provider reported) for success validation. Git-detected edits are filtered before applying (since files already exist on disk), resulting in `workspaceEditsApplied = 0` even when Claude made real changes.
+
+**Resolution**:
+1. Ensure `local-executor.ts:1260-1263` uses `workspaceEditsRequested` not `workspaceEditsApplied`:
+```typescript
+// CORRECT - counts all edits including git-detected
+const emptyChanges = workspaceEditsRequested === 0 && completeness === 0;
+
+// WRONG - misses git-detected edits
+const emptyChanges = workspaceEditsApplied === 0 && completeness === 0;
+```
+
+2. If you see this after a code update, rebuild: `./scripts/build-poetic.sh`
+
+**Technical details**:
+- See comprehensive comments in `src/orchestrator/executors/pipeline/variant-execution-pipeline.ts:42-67`
+- Git-detected edits are marked with `_source: 'git-detection'`
+- These edits represent real work but don't need re-application (files already on disk)
+- Success validation must account for both edit models
+
+**History**:
+- **Breaking commit**: `5642c9ec` (2025-11-26) - introduced git-detection filtering without updating success check
+- **Fix commit**: Current - updated success check to use `workspaceEditsRequested`
+
+### Cursor polling appears hung or times out
+
+**Symptoms**: Waiting for Cursor completion seems to stall; eventually times out.
+
+**What’s happening**: The poller is resilient to transient GitHub/`gh` errors and continues iterating until the timeout. If commits aren’t detected, it exits cleanly. It may log warnings when `--verbose` is enabled.
+
+**Quick checks**:
+- Run with `--verbose` to see per-iteration progress and transient error warnings.
+- Verify commits: `gh pr view <PR#> --json commits` and look for Cursor bot author patterns.
+- Ensure PR number and branch are correct; check that `git remote get-url origin` points to GitHub.
+
+**If it truly times out**:
+- Re-run with more time if the task is complex.
+- Re-issue the `@cursor` instruction if needed.
+
+### Authentication Failures
+
+> **Info: Authentication at Runtime**
+>
+> Provider execution defers authentication to the underlying CLI. Auth errors surface at
+> execution time with actionable guidance. Routing and dry-run may perform advisory
+> pre-verification, but are not a universal gate. Use `poetic provider list` for readiness verification.
+
+#### Claude Authentication Issues
+
+**Error**: `Authentication failed` or CLI reports not authenticated
+
+**Solutions**:
+```bash
+# 1. Re-authenticate via Claude CLI
+claude auth logout
+claude auth login
+
+# 2. Verify CLI installation
+which claude
+claude --version
+```
+
+**Common Causes**:
+- Claude CLI session expired
+- Claude CLI not installed or not in PATH
+- Wrong config directory
+
+#### Gemini Authentication Issues
+
+**Error**: `GEMINI_API_KEY not found` or `Authentication failed`
+
+**Solutions**:
+```bash
+# 1. Set API key
+export GEMINI_API_KEY='your-api-key-here'
+
+# 2. Verify key format (should start with AIza...)
+echo $GEMINI_API_KEY | head -c 10
+
+# 3. Test with simple request
+poetic run "test" --engine gemini --model gemini-2.5-flash
+```
+
+**Common Causes**:
+- Missing `GEMINI_API_KEY` environment variable
+- Invalid API key format
+- Quota exceeded (check Google AI Studio)
+
+#### Grok Authentication Issues
+
+**Error**: `XAI_API_KEY not found`, Grok readiness is `unknown`, or browser auth is required
+
+**Solutions**:
+```bash
+# 1. Install Grok through Poetic's guarded setup path
+POETIC_ALLOW_CURL_BASH=1 poetic provider setup --providers grok
+
+# 2. Primary for local use: cached OAuth / device login via the Grok CLI
+grok login --device-auth
+# or: grok login
+# or first interactive launch: grok
+
+# 3. Optional for CI/headless automation (official key)
+export XAI_API_KEY='your-key-here'
+# Deprecated Poetic compatibility alias (still accepted; not preferred):
+# export GROK_CODE_XAI_API_KEY='your-key-here'
+
+# 4. Inspect passive readiness (key presence remains unverified)
+poetic provider list
+poetic doctor --provider grok
+```
+
+**Common Causes**:
+- Grok CLI is not installed or not on `PATH`
+- Cached CLI OAuth / device login has not been completed (`~/.grok` auth missing)
+- CI/headless runs have neither a usable CLI auth cache nor `XAI_API_KEY` (or the deprecated `GROK_CODE_XAI_API_KEY` alias)
+- Sandboxed agent sessions cannot read Grok's CLI auth state
+- `POETIC_GROK_ALLOW_BROWSER_AUTH=1` was not set when deliberately allowing browser auth probes (opt-in only; not safe by default in headless/CI)
+
+#### Cursor Authentication Issues
+
+**Error**: `ConnectError: [invalid_argument]` or `Cursor CLI not found`
+
+**Solutions**:
+```bash
+# 1. Install Cursor Agent
+curl https://cursor.com/install -fsS | bash
+
+# 2. Verify installation
+cursor-agent --version
+```
+
+**Common Causes**:
+- Cursor CLI not installed
+- Invalid API key
+- Plan mode conflicts (try disabling)
+
+#### Codex Authentication Issues
+
+**Error**: `Invalid token` or `Command not found: codex`
+
+**Solutions**:
+```bash
+# 1. Install Codex CLI
+npm install -g @openai/codex
+
+# 2. Verify installation
+codex --version
+
+# 3. Authenticate
+codex login
+
+# 4. Verify via Poetic
+poetic doctor --provider codex
+```
+
+**Common Causes**:
+- Codex CLI not installed
+- Invalid or expired token
+- Wrong environment variable name
+
+### Installation Issues
+
+#### Missing CLIs
+
+**Error**: `'claude' is not available on this system` or similar
+
+**Solutions**:
+```bash
+# 1. Install all required CLIs
+npm install -g @anthropic-ai/claude-code
+npm install -g @openai/codex
+curl https://cursor.com/install -fsS | bash
+
+# 2. Verify installations
+claude --version
+codex --version
+cursor-agent --version
+
+# 3. Add to PATH if needed
+export PATH="$PATH:$(npm config get prefix)/bin"
+```
+
+#### PATH Problems
+
+**Error**: `Command not found` despite installation
+
+**Solutions**:
+```bash
+# 1. Find where npm installs global packages
+npm config get prefix
+
+# 2. Add to PATH
+export PATH="$PATH:$(npm config get prefix)/bin"
+
+# 3. Make permanent (add to ~/.bashrc or ~/.zshrc)
+echo 'export PATH="$PATH:$(npm config get prefix)/bin"' >> ~/.bashrc
+source ~/.bashrc
+
+# 4. Verify PATH
+which claude
+which codex
+which cursor-agent
+```
+
+#### Node.js Version Issues
+
+**Error**: `Unsupported Node.js version` or `Module not found`
+
+**Solutions**:
+```bash
+# 1. Check Node.js version
+node --version
+# Requires: Node.js 24.x (see .nvmrc)
+
+# 2. Update Node.js (using nvm)
+nvm install 24
+nvm use 24
+
+# 3. Rebuild native dependencies (better-sqlite3)
+npm rebuild better-sqlite3
+
+# 4. Clear npm cache
+npm cache clean --force
+
+# 5. Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Execution Failures
+
+#### Timeout Errors
+
+**Error**: `Timeout waiting for task to complete`
+
+**Solutions**:
+```bash
+# 1. Increase timeout
+poetic run "task" --timeout 60
+
+# 2. Use faster model
+poetic run "task" --model gemini-2.5-flash
+
+# 3. Check provider status
+poetic providers
+
+# 4. Use verbose mode for details
+poetic run "task" --verbose
+```
+
+**Common Causes**:
+- Task too complex for timeout limit
+- Provider rate limiting
+- Network connectivity issues
+- Memory pressure (check system resources)
+
+#### Memory Issues
+
+**Error**: `Memory limit exceeded` or `Out of memory`
+
+**Solutions**:
+```bash
+# 1. Check memory usage
+poetic run "task" --verbose
+# Look for: "Memory: XX% heap"
+
+# 2. Reduce parallel execution
+poetic run "task" --fan-out 2 --max-concurrent 2
+
+# 3. Configure guardian behavior
+#    - Log-only (observe without killing)
+export POETIC_MEMORY_KILL=0
+#    - Aggressive kill mode (stress testing)
+export POETIC_MEMORY_KILL=1
+#    - Container-aware RSS cap (e.g., 2GB)
+export POETIC_RSS_LIMIT_MB=2048
+
+# 4. Disable memory guardian (development only)
+export POETIC_MEMORY_GUARD=0
+
+# 5. Increase Node.js memory limit
+node --max-old-space-size=4096 poetic.js run "task"
+```
+
+**Common Causes**:
+- Large codebase processing
+- Too many parallel executions
+- Memory leaks in provider code
+- Insufficient system RAM
+
+#### Crashes
+
+**Error**: `Process exited with code 1` or `Segmentation fault`
+
+**Solutions**:
+```bash
+# 1. Check system resources
+free -h
+df -h
+
+# 2. Run with verbose logging
+poetic run "task" --verbose
+
+# 3. Check logs
+ls -la .poetic/telemetry/logs/
+
+# 4. Test with simple task
+poetic run "Create hello.js" --engine claude
+```
+
+**Common Causes**:
+- System resource exhaustion
+- Provider-specific bugs
+- Corrupted configuration
+- Node.js version incompatibility
+
+#### Token Analysis Failures
+
+**Error**: `Token analysis failed` or unexpected split decisions during parallel decomposition
+
+**Solutions**:
+```bash
+# 1. Check token analysis output
+POETIC_DEBUG=1 poetic compete "task" --variant claude:conservative
+
+# 2. Disable token-aware splitting
+poetic compete "task" --context-mode off --variant claude:conservative
+
+# 3. Verify model is recognized by token estimator
+# Unknown models fall back to 128K context window and 0.5 confidence
+```
+
+**Common Causes**:
+- Unknown model ID (not in token estimator registry) → conservative 128K estimate
+- Very short prompts below the 60% threshold → no split even when expected
+- tiktoken unavailable → character-based estimation (less accurate)
+
+#### Partial Result Corruption
+
+**Error**: Aggregated results contain incomplete or garbled output from parallel subtasks
+
+**Solutions**:
+```bash
+# 1. Reduce parallelism to isolate the failing subtask
+poetic compete "task" --fan-out 2 --variant claude:conservative
+
+# 2. Check for memory pressure (backpressure threshold is 70% RSS by default)
+POETIC_MEMORY_BACKPRESSURE_PCT=50 poetic compete "task" --variant claude:conservative
+
+# 3. Increase subtask timeout (subtask may be timing out mid-output)
+POETIC_SUBTASK_TIMEOUT_MS=1800000 poetic compete "task" --variant claude:conservative
+
+# 4. Run with verbose to see per-subtask output
+poetic compete "task" --verbose --variant claude:conservative
+```
+
+**Common Causes**:
+- Subtask timeout triggered mid-generation (output truncated)
+- Memory backpressure killing workers under load
+- Provider returning partial responses on network errors
+
+### Git/GitHub Integration Errors
+
+#### Git Conflicts
+
+**Error**: `The following untracked working tree files would be overwritten by merge`
+
+**Solutions**:
+```bash
+# 1. Inspect the working directory before changing it
+git status
+
+# 2. Preserve tracked and untracked changes
+git stash push --include-untracked -m "pre-merge recovery"
+
+# 3. Pull latest changes
+git pull origin main
+
+# 4. Apply stash
+git stash pop
+
+# 5. Retry task
+poetic run "task"
+```
+
+**Common Causes**:
+- Parallel executions creating overlapping files
+- Uncommitted changes in working directory
+- Git lock file conflicts
+- Branch synchronization issues
+
+#### GitHub API Errors
+
+**Error**: `GitHub API rate limit exceeded` or `403 Forbidden`
+
+**Solutions**:
+```bash
+# 1. Check GitHub token
+echo $GITHUB_TOKEN
+
+# 2. Wait for rate limit reset (usually 1 hour)
+gh api rate_limit
+
+# 3. Use personal access token
+export GITHUB_TOKEN='your-token-here'
+```
+
+**Common Causes**:
+- GitHub API rate limiting
+- Invalid or expired token
+- Insufficient token permissions
+- Network connectivity issues
+
+### Parallel Execution Problems
+
+#### Concurrency Issues
+
+**Error**: `Too many concurrent executions` or `Resource exhausted`
+
+**Solutions**:
+```bash
+# 1. Reduce concurrency
+poetic run "task" --fan-out 2 --max-concurrent 2
+
+# 2. Use sequential execution
+poetic run "task" --fan-out 1
+
+# 3. Check system resources
+htop
+free -h
+
+# 4. Cap per-provider concurrency
+poetic run "task" --fan-out 4 --provider-limit claude=2
+```
+
+**Common Causes**:
+- System resource limits
+- Provider rate limiting
+- Memory pressure
+- Network bandwidth constraints
+
+#### Worktree Conflicts
+
+**Error**: `Git worktree already exists` or `Branch already exists`
+
+**Solutions**:
+```bash
+# 1. Clean up worktrees
+git worktree prune
+
+# 2. Remove specific worktree
+git worktree remove <path>
+
+# 3. Check for existing branches
+git branch -a
+
+# 4. Let Poetic choose a unique managed branch name for a new run
+poetic run "task"
+```
+
+**Common Causes**:
+- Previous execution didn't clean up properly
+- Manual git operations interfering
+- Concurrent executions using same branch names
+- Git lock file issues
+
+---
+
+## Error Codes & Meanings
+
+### Exit Codes
+
+| Code | Meaning | Common Causes | Solutions |
+|------|---------|---------------|-----------|
+| `0` | Success | All tasks completed successfully | - |
+| `1` | General failure | Task failed, quality gate failed | Check logs, use `--verbose` |
+| `2` | Invalid arguments | Wrong CLI syntax | Check command format |
+
+### Provider-Specific Error Messages
+
+#### Claude Errors
+
+| Error Message | Cause | Solution |
+|---------------|-------|----------|
+| `Authentication failed` | Invalid API key | Re-authenticate with `claude auth login` |
+| `Rate limit exceeded` | Too many requests | Wait 60 seconds or upgrade plan |
+| `Model not available` | Invalid model name | Use a model reported by `poetic provider show claude` or omit the model to use the configured default |
+| `Context length exceeded` | Task too large | Split into smaller tasks |
+
+#### Gemini Errors
+
+| Error Message | Cause | Solution |
+|---------------|-------|----------|
+| `GEMINI_API_KEY not found` | Missing API key | Set `export GEMINI_API_KEY='key'` |
+| `Quota exceeded` | API quota limit | Check Google AI Studio quotas |
+| `Invalid model` | Wrong model name | Use `gemini-2.5-flash` or `gemini-2.5-pro` |
+| `Permission denied` | API key permissions | Regenerate key with correct permissions |
+
+#### Grok Errors
+
+| Error Message | Cause | Solution |
+|---------------|-------|----------|
+| `Command not found: grok` | Grok CLI not installed or not on `PATH` | Run `POETIC_ALLOW_CURL_BASH=1 poetic provider setup --providers grok` or install with xAI's installer |
+| `Authentication unknown` | Passive readiness cannot verify a configured key or cached CLI auth | Primary: `grok login --device-auth` (or `grok login` / `grok`). Optional for CI/headless: set `XAI_API_KEY`. Key presence remains unverified until requested execution or `poetic doctor --probe --provider grok` succeeds. |
+| `XAI_API_KEY not found` / headless requires key | Headless path has no key and no usable CLI auth cache | Prefer CLI OAuth for local use; keys are optional only when a cache exists. For CI/headless without cache set `XAI_API_KEY` (deprecated alias `GROK_CODE_XAI_API_KEY` still accepted). Do not rely on browser auth unless you opt in |
+| Requested Grok execution reports an auth failure | The Grok CLI could not authenticate the requested run | Re-run `grok login --device-auth` or `grok login`; for CI set optional `XAI_API_KEY`. Poetic does not run a separate auth preflight. |
+| `Browser auth required` | The Grok CLI wants to start an interactive auth flow | Complete cached login in a terminal (`grok login --device-auth` / `grok`). Set `POETIC_GROK_ALLOW_BROWSER_AUTH=1` only when browser auth is acceptable (opt-in; not automatically safe in headless/CI) |
+| `unsafe for Grok headless execution` | `POETIC_GROK_PERMISSION_MODE` is `acceptEdits` or `auto` | Unset the variable (omit `--permission-mode`) or use locked native read-only posture (`dontAsk` + allow rules + tool/MCP/subagent locks; CLI >= 0.2.93) / `bypassPermissions` only when policy permits |
+| `reasoningEffort` rejected | The selected Grok model does not declare native effort support, or `auto` discovery could not establish it | Use `grok-4.6`, or leave effort unset. With `auto`, confirm `grok models` exposes an effort-capable default. |
+| `max_turns exceeded` / early Cancelled | Explicit `--max-turns` too low, or transport death under a bad permission mode | Leave `POETIC_GROK_MAX_TURNS` unset for normal runs; do not use `acceptEdits`/`auto` headless. Auth/edit probes may set a low turn cap deliberately |
+
+#### Cursor Errors
+
+| Error Message | Cause | Solution |
+|---------------|-------|----------|
+| `ConnectError: [invalid_argument]` | Plan mode conflict | Disable plan mode or use different model |
+| `Cursor CLI not found` | CLI not installed | Install with `curl https://cursor.com/install -fsS | bash` |
+| `Workspace not found` | Wrong directory | Run from project root |
+
+#### Codex Errors
+
+| Error Message | Cause | Solution |
+|---------------|-------|----------|
+| `Command not found: codex` | CLI not installed | Install with `npm install -g @openai/codex` |
+| `Authentication required` | Not logged in | Run `codex login`, then `poetic doctor --provider codex` |
+| `Codex execution timed out` | Local CLI exceeded the execution deadline | Inspect the retained worktree/branch, then retry with a suitable executor timeout |
+| `Codex CLI terminated without an exit code` | Local process or transport ended unexpectedly | Inspect stderr and retained git changes before retrying |
+
+### File Compliance Failure Messages
+
+| Error Message | Cause | Solution |
+|---------------|-------|----------|
+| `FILE: specification missing` | No FILE: in task | Add `FILE: path/to/file` to task description |
+| `File not found: <path>` | Invalid file path | Check file exists and path is correct |
+| `Compliance check failed` | Wrong file edited | Use exact FILE: specification |
+| `Multiple files not supported` | Too many files | Use single file or split into multiple tasks |
+
+### Timeout Error Patterns
+
+| Pattern | Cause | Solution |
+|---------|-------|----------|
+| `Timeout after 30 minutes` | Provider execution timeout | Inspect retained local changes, then retry or simplify the task |
+| `Timeout after 10 minutes` | Provider execution timeout | Use faster model or simpler task |
+| `Timeout after 5 minutes` | Network connectivity | Check internet connection |
+| `Timeout after 1 minute` | Provider rate limiting | Wait and retry |
+
+---
+
+## Provider-Specific Issues
+
+### Grok Issues
+
+Grok is a supported validated provider, but Poetic does
+not manage Grok credentials. **Primary for local use:** cached OAuth / device
+login via the Grok CLI (`grok login --device-auth`, `grok login`, or an initial
+`grok`). Keys are **optional** and only needed when there is no usable CLI auth
+cache (typical CI/headless): official `XAI_API_KEY`.
+`GROK_CODE_XAI_API_KEY` is a deprecated Poetic compatibility alias (still
+accepted; not preferred for new setup). Provider-scoped keys are accepted via
+Poetic's provider policy when present; they are not mandatory for local OAuth.
+
+#### Authentication at execution
+
+Poetic does not infer Grok authentication from keys or local auth files before a
+run. It starts the requested `grok --prompt-file` invocation and reports the
+CLI's actual authentication or transport error. This supports CLI-owned auth
+state without coupling execution to a particular cache-file layout.
+
+Passive `poetic doctor --provider grok` never spawns `grok` and may report auth
+as unknown; that cold state is not a blocker. Use
+`poetic doctor --probe --provider grok` only when you intentionally want an
+active readiness probe. `POETIC_GROK_ALLOW_BROWSER_AUTH=1` remains an explicit
+opt-in when a requested execution or probe may open a browser.
+
+Headless defaults (no operator action required): `--max-turns` is **not** set unless you opt in with `POETIC_GROK_MAX_TURNS`; output defaults to `streaming-json` when provider streaming is on; `--permission-mode` is omitted for normal edit runs. Do not set `POETIC_GROK_PERMISSION_MODE=acceptEdits` or `auto` for headless automation.
+
+#### First-Task Check with Grok
+
+Prefer `poetic run` for straightforward single-provider execution. Use
+`poetic compete` when you want judge scores/rationale or multi-variant
+comparison. Claude and Codex are primary validated providers; Grok is a
+supported validated alternative.
+
+```bash
+poetic provider setup --providers grok
+grok login --device-auth
+# or: grok login  /  grok
+poetic provider list
+
+git checkout -b run/my-task
+# Preferred default: straightforward single-provider execution
+poetic run "Create a small marker file"
+# Delivery caveat: changes may stay in a worktree or patch under .poetic/
+
+# Graded evaluation (AI judge default — omit --judge ai)
+poetic compete "Create a small marker file" --variant grok:conservative
+git checkout -b fix/my-task
+poetic compete apply <competition-id>
+git status
+```
+
+If `poetic provider list` reports Grok auth as unknown, that is expected when
+Poetic can see the binary but cannot verify a usable CLI auth cache without an
+active probe. Complete cached CLI login for local use, or set optional
+`XAI_API_KEY` for non-interactive/CI runs. Set
+`POETIC_GROK_ALLOW_BROWSER_AUTH=1` only when you deliberately accept active Grok
+CLI auth probes that may open a browser (opt-in; not automatically safe in
+headless/CI).
+
+If `poetic run` succeeds but your repository root is unchanged, inspect the
+printed worktree and/or patch paths (default isolation). If you used
+`poetic compete` and stopped after the `run/*` execution branch, note the
+competition ID, create a `fix/*`, `docs/*`, or `test/*` branch, and run
+`poetic compete apply <competition-id>`.
+
+For validation-only checks from `main`, use:
+
+```bash
+poetic compete --validation-run "Validate first-task provider readiness" \
+  --variant grok:conservative
+```
+
+That creates a disposable `validation/<date>-<slug>` branch. Do not use that
+branch as the product apply target; move real fixes to a focused delivery
+branch first.
+
+### Claude Issues
+
+> **Info: Authentication at Runtime**
+>
+> Provider execution defers authentication to the Claude CLI. Auth errors surface at
+> execution time with actionable guidance. Use `poetic provider list` for readiness verification.
+> The manual verification commands below are useful for deeper troubleshooting.
+
+#### Authentication Problems
+
+**Symptoms**:
+- `Authentication failed` errors
+- CLI reports not authenticated
+- Tasks fail immediately
+
+**Diagnosis**:
+```bash
+# Verify CLI installation
+which claude
+claude --version
+```
+
+**Solutions**:
+```bash
+# 1. Re-authenticate via Claude CLI
+claude auth logout
+claude auth login
+
+# 2. Test with simple task
+poetic run "Create hello.js" --engine claude
+```
+
+#### Rate Limits
+
+**Symptoms**:
+- `Rate limit exceeded` errors
+- Tasks fail after working initially
+- 429 HTTP status codes
+
+**Solutions**:
+```bash
+# 1. Wait for rate limit reset (usually 60 seconds)
+sleep 60
+
+# 2. Upgrade Anthropic plan for higher limits
+# Visit: https://console.anthropic.com/
+
+# 4. Use different provider temporarily
+poetic run "task" --engine gemini
+```
+
+
+
+### Gemini Issues
+
+> **Info: Authentication at Runtime**
+>
+> Provider execution defers authentication to the Gemini CLI. Auth errors surface at
+> execution time with actionable guidance. Use `poetic provider list` for readiness verification.
+> The manual verification commands below are useful for deeper troubleshooting.
+
+#### Auth Flow Problems
+
+**Symptoms**:
+- `GEMINI_API_KEY not found` errors
+- Authentication failures
+- Model not available errors
+
+**Diagnosis**:
+```bash
+# Check API key format
+echo $GEMINI_API_KEY | head -c 10
+# Should start with "AIza"
+
+# Test API key
+curl -H "Authorization: Bearer $GEMINI_API_KEY" \
+  "https://generativelanguage.googleapis.com/v1/models"
+```
+
+**Solutions**:
+```bash
+# 1. Get API key from Google AI Studio
+# https://aistudio.google.com/
+
+# 2. Set environment variable
+export GEMINI_API_KEY='AIza...'
+
+# 3. Test with simple request
+poetic run "test" --engine gemini --model gemini-2.5-flash
+
+# 4. Check quotas in Google AI Studio
+```
+
+#### Model Availability
+
+**Symptoms**:
+- `Model not available` errors
+- `Invalid model` messages
+- Tasks fail with model-specific errors
+
+**Solutions**:
+```bash
+# 1. Use supported models only
+poetic run "task" --model gemini-2.5-flash
+poetic run "task" --model gemini-2.5-pro
+
+# 2. Check model availability
+poetic providers --json
+
+# 3. Use auto-detection
+poetic run "task" --engine gemini
+```
+
+#### Legacy command syntax errors
+
+**Symptoms**:
+- `bash: gemini: command not found: code`
+- Shell prints `no matches found: --allowed-tools=[]`
+- Command succeeds manually but fails when invoked by Poetic
+
+**Diagnosis**:
+```bash
+# Compare against Poetic's invocation
+poetic --verbose run "Say hello" --engine gemini
+
+# Reproduce directly
+gemini --output-format json --model gemini-2.5-flash "Say hello"
+```
+
+**Solutions**:
+```bash
+# 1. Drop removed flags and the legacy subcommand (v0.8+)
+gemini --output-format json --model gemini-2.5-flash "prompt"
+
+# 2. Quote brackets if you must pass arrays (advanced usage only)
+gemini --output-format json --model gemini-2.5-flash --allowed-tools '[]' "prompt"
+
+# 3. Prefer Poetic defaults unless a flag is officially documented
+```
+
+#### Gemini CLI stderr handling
+
+**Symptoms**:
+- Poetic reports `Loaded cached credentials.` as an error
+- CLI exits with code 1 when run from Poetic but succeeds directly
+- Retry loop runs 15 times without additional diagnostics
+
+**Diagnosis**:
+```bash
+# Run with verbose logging to capture the exact command
+POETIC_DEBUG=1 poetic run "test" --engine gemini --verbose
+
+# Check exit code from manual invocation
+gemini --output-format json --model gemini-2.5-flash "test"
+echo $?  # Should be 0 on success
+```
+
+**Solutions**:
+```bash
+# 1. Trust the exit code, not stderr noise
+# (Poetic filters the message internally; treat exitCode===0 as success)
+
+# 2. Failures that look like retries: inspect verbose process I/O
+# (there is no live --max-retries CLI flag on poetic run)
+POETIC_DEBUG=1 poetic run "task" --engine gemini --verbose
+
+# 3. Confirm the provider CLI succeeds outside Poetic
+gemini --output-format json --model gemini-2.5-flash "test"
+echo $?
+
+# 4. See docs/GEMINI_BEST_PRACTICES.md § CLI Invocation Requirements for context
+```
+
+### Cursor Issues
+
+#### Agent Selection Problems
+
+**Symptoms**:
+- Wrong agent selected for task
+- Poor task execution quality
+- Inconsistent results
+
+**Diagnosis**:
+```bash
+# Agent selection is provider-native; there is no live --explain-agents flag.
+# Check run output for agent labels when present, then routing status:
+poetic routing status
+poetic routing status --provider cursor
+
+# After competitions, inspect recorded outcomes:
+poetic compete results <task-id>
+```
+
+**Solutions**:
+```bash
+# 1. Pin provider/model when automatic selection is a poor fit
+poetic run "task" --engine cursor --model auto
+
+# 2. Check agent/provider performance telemetry
+poetic telemetry leaderboard
+```
+
+#### Workspace Issues
+
+**Symptoms**:
+- `Workspace not found` errors
+- File not found errors
+- Context not loaded properly
+
+**Solutions**:
+```bash
+# 1. Run from project root
+cd /path/to/your/project
+poetic run "task"
+
+# 2. Check workspace structure
+ls -la
+ls -la .poetic/
+
+# 3. Initialize if needed
+poetic init
+```
+
+### Codex Issues
+
+#### Local Result Recovery
+
+Codex runs locally in the selected workspace or isolated worktree. There is no
+Codex cloud task to poll or apply.
+
+```bash
+# Confirm CLI availability and authentication
+poetic doctor --provider codex
+
+# Inspect durable local delivery after a timeout or interrupted process
+git status
+git diff
+git log --oneline --max-count=10
+```
+
+For competition runs, inspect the retained variant branch/worktree reported by
+Poetic. Codex executors respect `--executor-timeout-minutes`; `--timeout`
+controls the overall competition deadline. Do not use `codex apply` recovery
+instructions from historical run records.
+
+---
+
+## Installation & Setup Problems
+
+### Node.js Version Issues
+
+#### Unsupported Version
+
+**Error**: `Unsupported Node.js version` or `Module not found`
+
+**Diagnosis**:
+```bash
+# Check current version
+node --version
+# Requires: Node.js 24.x (see .nvmrc)
+
+# Check npm version
+npm --version
+```
+
+**Solutions**:
+```bash
+# 1. Install Node.js LTS (using nvm)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+source ~/.bashrc
+nvm install 24
+nvm use 24
+
+# Rebuild native dependencies (better-sqlite3)
+npm rebuild better-sqlite3
+
+# 2. Verify installation
+node --version
+npm --version
+
+# 3. Clear npm cache
+npm cache clean --force
+
+# 4. Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
+```
+
+#### Version Conflicts
+
+**Error**: `Module version mismatch` or `Incompatible versions`
+
+**Solutions**:
+```bash
+# 1. Use Node.js 24 (the version Poetic is built and tested against)
+nvm install 24
+nvm use 24
+
+# 2. Clear all caches
+npm cache clean --force
+rm -rf node_modules package-lock.json
+
+# 3. Reinstall with exact versions
+npm install
+
+# 4. Verify compatibility
+npm ls
+```
+
+#### Replicate the Node 24 Fix on Another Computer
+
+Pulling the repository propagates the runtime guards, installer, launcher generator,
+workflow checks, and documentation. It does not change that computer's shell `PATH`,
+installed Node executable, native modules, or generated `poetic` launcher.
+
+On every development computer:
+
+```bash
+git pull
+nvm install 24
+nvm use 24
+node --version
+node -p 'process.versions.modules'
+npm ci
+npm rebuild better-sqlite3
+./scripts/build-poetic.sh
+poetic doctor --json
+poetic provider list --json
+```
+
+`./scripts/build-poetic.sh` installs a launcher pinned to the verified Node 24
+executable into `~/.local/bin` (override with `POETIC_BIN_DIR`) and puts that
+executable first in child `PATH`. An existing launcher the script did not
+generate is left in place, so a hand-maintained wrapper is never overwritten.
+If Node 24 is moved or reinstalled, rerun the build. Package installations should
+be refreshed with `bash install.sh --force` for the same reason.
+
+For a temporary override, point the launcher at another Node 24 executable:
+
+```bash
+POETIC_NODE_BIN=/path/to/node poetic doctor --json
+```
+
+The launcher validates that override on every invocation and rejects non-Node-24
+executables. Set it in the service or editor environment as well when those
+processes do not inherit the interactive shell's `PATH`.
+
+Claude readiness is the native Claude CLI (`poetic provider list` /
+`poetic doctor`), not a Poetic Claude Code plugin. Pre-1.42 installs that
+still have a leftover plugin registration can remove it with
+`poetic provider disconnect claude --scope user|project|local`. That cleanup does
+not sign out, revoke credentials, or disable Claude. Project and local scopes
+must be cleaned from each affected repository.
+
+For Homebrew without `nvm`, put `/opt/homebrew/opt/node@24/bin` before other Node
+locations in the shell startup file, reopen the shell, then run the rebuild and
+verification commands above. Shell profile edits and generated launchers are
+machine-local and must be repeated on each computer.
+
+### npm Install Failures
+
+#### Network Issues
+
+**Error**: `npm ERR! network timeout` or `npm ERR! fetch failed`
+
+**Solutions**:
+```bash
+# 1. Check internet connection
+ping google.com
+
+# 2. Clear npm cache
+npm cache clean --force
+
+# 3. Use different registry
+npm config set registry https://registry.npmjs.org/
+
+# 4. Increase timeout
+npm config set timeout 300000
+
+# 5. Retry installation
+npm install
+```
+
+#### Permission Issues
+
+**Error**: `npm ERR! EACCES: permission denied` or `npm ERR! EPERM`
+
+**Solutions**:
+```bash
+# 1. Fix npm permissions (recommended)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# 2. Or use sudo (not recommended)
+sudo npm install -g @anthropic-ai/claude-code
+
+# 3. Or use nvm with Node 24 (best practice)
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+source ~/.bashrc
+nvm install 24
+nvm use 24
+```
+
+#### Dependency Conflicts
+
+**Error**: `npm ERR! peer dep missing` or `npm ERR! conflict`
+
+**Solutions**:
+```bash
+# 1. Check for conflicts
+npm ls
+
+# 2. Install missing peer dependencies
+npm install --save-dev <missing-package>
+
+# 3. Use --force to override conflicts
+npm install --force
+
+# 4. Or use --legacy-peer-deps
+npm install --legacy-peer-deps
+```
+
+### CLI Installation Verification
+
+#### Claude CLI
+
+**Verification**:
+```bash
+# Check installation
+which claude
+claude --version
+
+# Test execution
+claude run "Create hello.js"
+```
+
+**Common Issues**:
+- Not in PATH
+- Wrong version installed
+- Authentication not configured
+
+#### Codex CLI
+
+**Verification**:
+```bash
+# Check installation
+which codex
+codex --version
+
+# Test authentication
+codex login
+
+# Verify via Poetic
+poetic doctor --provider codex
+```
+
+**Common Issues**:
+- Not in PATH
+- Wrong package name
+- Authentication not configured
+
+#### Cursor CLI
+
+**Verification**:
+```bash
+# Check installation
+which cursor-agent
+cursor-agent --version
+```
+
+**Common Issues**:
+- Not in PATH
+- Wrong package name
+- Authentication not configured
+
+### Configuration File Errors
+
+#### Invalid JSONC
+
+**Error**: `JSONC parse error`, `SyntaxError: Unexpected token`, or `Invalid JSON`
+
+**Diagnosis**:
+```bash
+# JSONC is JSON with comments and trailing commas.
+# Validate config with Poetic's JSONC-aware parser.
+poetic config validate
+poetic config diagnose
+```
+
+**Solutions**:
+```bash
+# Repair fixable validation issues first
+poetic config validate --fix
+```
+
+If the file remains unparseable, follow [Configuration Corruption](#configuration-corruption).
+That procedure preserves the original project configuration before regenerating it.
+
+#### Missing Configuration
+
+**Error**: `Configuration not found` or `Config file missing`
+
+**Solutions**:
+```bash
+# 1. Initialize configuration
+poetic init
+
+# 2. Check if .poetic directory exists
+ls -la .poetic/
+
+# 3. Create manually if needed
+mkdir -p .poetic/config
+touch .poetic/config/poetic.config.jsonc
+```
+
+#### Permission Issues
+
+**Error**: `EACCES: permission denied` or `Cannot write to config`
+
+**Solutions**:
+```bash
+# 1. Fix directory permissions
+chmod 755 .poetic/
+chmod 644 .poetic/config/poetic.config.jsonc
+
+# 2. Check ownership
+ls -la .poetic/
+
+# 3. Fix ownership if needed
+sudo chown -R $USER:$USER .poetic/
+```
+
+---
+
+## Debugging Tips
+
+### Using --verbose Flag
+
+**Enable detailed logging**:
+```bash
+# Basic verbose mode
+poetic run "task" --verbose
+
+# Verbose with specific provider
+poetic run "task" --engine claude --verbose
+
+# Verbose with parallel execution
+poetic run "task" --fan-out 2 --verbose
+```
+
+**What verbose mode shows**:
+- Provider selection reasoning
+- API request/response details
+- File operations and git commands
+- Error stack traces
+- Performance metrics
+
+### Checking Telemetry Logs
+
+**View execution logs**:
+```bash
+# List log files (durable JSONL, organized by month)
+ls -la .poetic/telemetry/logs/
+
+# Follow today's events
+tail -f .poetic/telemetry/logs/<YYYY-MM>/<YYYY-MM-DD>.jsonl
+
+# Search for errors
+grep -i error .poetic/telemetry/logs/*/*.jsonl
+
+# View a specific day's events
+cat .poetic/telemetry/logs/<YYYY-MM>/<YYYY-MM-DD>.jsonl | jq .
+```
+
+**Log file locations**:
+- `.poetic/telemetry/logs/<YYYY-MM>/<YYYY-MM-DD>.jsonl` - Durable execution event logs
+- `.poetic/telemetry/db/` - SQLite databases (`variants.db`, `validations.db`)
+- `.poetic/telemetry/artifacts/` - Per-run generated files and artifacts
+
+### Reviewing PR Comments
+
+**For ordinary PR review or historical cloud-record recovery**:
+```bash
+# List recent PRs
+gh pr list --limit 10
+
+# View specific PR
+gh pr view <PR_NUMBER>
+
+# Check for bot comments
+gh pr view <PR_NUMBER> --json comments \
+  --jq '.comments[] | select(.author.login | contains("bot"))'
+
+# View PR diff
+gh pr diff <PR_NUMBER>
+```
+
+**Common bot comment patterns** (including historical cloud records):
+- `chatgpt-codex-connector` - Codex bot (historical cloud comments)
+- `cursor-agent` - Cursor bot (historical cloud comments)
+- Look for `Summary:` sections
+- Extract historical task IDs from comments when recovering old records
+
+### Using Evaluation Scripts
+
+**Check if evaluation scripts exist**:
+```bash
+# Look for evaluation scripts
+find . -name "*evaluate*" -type f
+find . -name "*evaluation*" -type f
+
+# Check scripts directory
+ls -la scripts/
+
+# Run evaluation if available
+./scripts/evaluate-agent.sh <TASK_ID> <PROVIDER>
+```
+
+**Manual evaluation process**:
+```bash
+# 1. Find agent's implementation commit
+git log --author="Cursor Agent" --grep="feat:\|Implement\|Refactor" --oneline
+
+# 2. Show actual changes
+git show <commit_hash> --stat
+
+# 3. Check if merged to main
+git branch --contains <commit_hash> | grep main
+
+# 4. For Codex and other local providers, inspect the variant branch
+git log <variant_branch> --oneline --max-count=10
+git diff main...<variant_branch>
+```
+
+### System Resource Monitoring
+
+**Check system resources**:
+```bash
+# Memory usage
+free -h
+htop
+
+# Disk space
+df -h
+
+# CPU usage
+top
+htop
+
+# Network connectivity
+ping google.com
+curl -I https://api.anthropic.com
+```
+
+**Common resource issues**:
+- Low memory (causes crashes)
+- Full disk (prevents file operations)
+- High CPU usage (causes timeouts)
+- Network issues (causes API failures)
+
+### Provider-Specific Debugging
+
+#### Claude Debugging
+
+```bash
+# Test with simple request
+claude run "Create hello.js"
+
+# Check logs
+claude logs
+
+# Verify API key (only for direct HTTP debugging; Poetic uses Claude CLI auth by default)
+curl -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
+  "https://api.anthropic.com/v1/messages" \
+  -d '{"model":"claude-3-sonnet-20240229","max_tokens":10,"messages":[{"role":"user","content":"test"}]}'
+```
+
+#### Gemini Debugging
+
+```bash
+# Test API key
+curl -H "Authorization: Bearer $GEMINI_API_KEY" \
+  "https://generativelanguage.googleapis.com/v1/models"
+
+# Check quotas
+curl -H "Authorization: Bearer $GEMINI_API_KEY" \
+  "https://generativelanguage.googleapis.com/v1/models/gemini-2.5-flash"
+
+# Test with simple request
+poetic run "test" --engine gemini --model gemini-2.5-flash
+```
+
+#### Cursor Debugging
+
+```bash
+# Verify Poetic can find Cursor Agent
+poetic doctor --provider cursor
+
+# If you installed Cursor Agent somewhere non-standard, override the binary:
+export CURSOR_CLI_COMMAND=/path/to/cursor-agent
+```
+
+#### Grok Debugging
+
+```bash
+# Verify Poetic can find Grok and evaluate passive readiness
+poetic doctor --provider grok
+
+# Local primary path: confirm CLI login / auth cache exists
+test -f "${HOME}/.grok/auth.json" && echo "Grok CLI auth cache present"
+
+# Optional CI/headless path: confirm the official key is present without printing it
+test -n "$XAI_API_KEY" && echo "XAI_API_KEY is set"
+# Deprecated compatibility alias (still accepted):
+# test -n "$GROK_CODE_XAI_API_KEY" && echo "GROK_CODE_XAI_API_KEY is set"
+```
+
+#### Codex Debugging
+
+```bash
+# Verify Poetic can find Codex CLI + your login state
+poetic doctor --provider codex
+
+# Inspect local delivery
+git status
+git diff
+git log --oneline --max-count=10
+```
+
+---
+
+## Advanced Troubleshooting
+
+### Memory Guardian Issues
+
+**Symptoms**:
+- `Memory: XX% heap` warnings
+- Process kills due to memory pressure
+- Performance degradation
+
+**Diagnosis**:
+```bash
+# Check memory usage
+poetic run "task" --verbose
+# Look for: "Memory: XX% heap"
+
+# Check memory guardian logs
+grep -i "memory" .poetic/telemetry/logs/*/*.jsonl
+```
+
+**Solutions**:
+```bash
+# 1. Reduce parallel execution
+poetic run "task" --fan-out 2 --max-concurrent 2
+
+# 2. Configure guardian behavior
+export POETIC_MEMORY_KILL=0        # Log-only
+export POETIC_MEMORY_KILL=1        # Aggressive kills
+export POETIC_RSS_LIMIT_MB=2048    # RSS cap (MB)
+export POETIC_RSS_LIMIT_PCT=75     # RSS cap (% of total RAM; ignored if POETIC_RSS_LIMIT_MB is set)
+
+# 3. Disable memory guardian (development only)
+export POETIC_MEMORY_GUARD=0
+
+# 4. Increase Node.js memory limit
+node --max-old-space-size=4096 poetic.js run "task"
+
+# 5. Use faster model
+poetic run "task" --model gemini-2.5-flash
+```
+
+#### Memory Guardian Stress Harness
+
+Use the stress harness to reproduce memory pressure locally or during scheduled health checks:
+
+```bash
+# Developer workstation
+npm run test:stress
+
+# CI / cron job (uses gentler thresholds)
+npm run ci:stress
+```
+
+The script streams heap usage as it allocates memory and exits automatically when the guardian intervenes or the target threshold is reached. Capture the console output when reporting memory regressions.
+
+### Recursion Detection Issues
+
+**Symptoms**:
+- `Recursion depth exceeded` errors
+- Infinite loops in parallel execution
+- Process hangs
+
+**Diagnosis**:
+```bash
+# Check recursion depth
+echo $POETIC_MAX_RECURSION_DEPTH
+
+# Look for recursion warnings
+grep -i "recursion" .poetic/telemetry/logs/*/*.jsonl
+```
+
+**Solutions**:
+```bash
+# 1. Increase recursion limit (careful!)
+export POETIC_MAX_RECURSION_DEPTH=3
+
+# 2. Use sequential execution
+poetic run "task" --fan-out 1
+
+# 3. Check for recursive calls
+grep -r "poetic run" .poetic/
+```
+
+### Git Lock Issues
+
+**Symptoms**:
+- `fatal: Unable to create '.../index.lock'` errors
+- Git operations fail
+- Parallel execution conflicts
+
+**Diagnosis**:
+```bash
+# Resolve the lock for this checkout, including linked worktrees
+git_dir="$(git rev-parse --path-format=absolute --git-dir)"
+lock_path="$git_dir/index.lock"
+ls -l "$lock_path"
+
+# Check for active Git operations
+ps -axo pid=,command= | grep '[g]it'
+```
+
+Do not move the lock while any Git process is active. If no Git process is active and the
+lock is older than the failed operation, quarantine only that exact lock, then verify the
+worktree:
+
+```bash
+mv "$lock_path" "${lock_path}.stale.$(date +%Y%m%dT%H%M%S)"
+git status
+```
+
+Poetic automatically removes only a stale `index.lock`, and it refuses recovery when any
+Git process is live. Moving the lock aside preserves it for inspection and avoids changing
+tracked or untracked work.
+
+### Provider Rate Limiting
+
+**Symptoms**:
+- `Rate limit exceeded` errors
+- 429 HTTP status codes
+- Tasks fail after working initially
+
+**Solutions**:
+```bash
+# 1. Wait for rate limit reset
+sleep 60
+
+# 2. Use different provider
+poetic run "task" --engine gemini
+
+# 3. Reduce concurrency
+poetic run "task" --fan-out 1
+
+# 4. Check provider quotas
+# Claude: https://console.anthropic.com/
+# Gemini: https://aistudio.google.com/
+# Cursor: https://cursor.sh/settings
+```
+
+### Network Connectivity Issues
+
+**Symptoms**:
+- `Network timeout` errors
+- `Connection refused` errors
+- API requests fail
+
+**Diagnosis**:
+```bash
+# Test basic connectivity
+ping google.com
+
+# Test provider APIs
+curl -I https://api.anthropic.com
+curl -I https://generativelanguage.googleapis.com
+curl -I https://api.cursor.sh
+
+# Check DNS resolution
+nslookup api.anthropic.com
+```
+
+**Solutions**:
+```bash
+# 1. Check internet connection
+ping google.com
+
+# 2. Check DNS settings
+cat /etc/resolv.conf
+
+# 3. Use different DNS
+echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
+
+# 4. Check firewall settings
+sudo ufw status
+
+# 5. Use proxy if needed
+export HTTP_PROXY=http://proxy:port
+export HTTPS_PROXY=http://proxy:port
+```
+
+### Configuration Corruption
+
+**Symptoms**:
+- `Invalid configuration` errors
+- Unexpected behavior
+- Settings not applied
+
+**Diagnosis**:
+```bash
+poetic config validate
+poetic config diagnose
+```
+
+First try the parser-aware repair:
+
+```bash
+poetic config validate --fix
+poetic config validate
+```
+
+If the project configuration is still unparseable, stop active Poetic runs and copy that
+exact file to a location outside the repository before resetting it:
+
+```bash
+cp .poetic/config/poetic.config.jsonc /path/outside/repo/poetic.config.jsonc.saved
+poetic config reset --level project --backup
+poetic init --force
+poetic config validate
+```
+
+`poetic config reset --backup` prints the name of a `poetic-config-backup-<timestamp>.json`
+file created in the current directory. Move that exact printed file outside the repository
+if you need to retain it. Restore individual custom settings only after validation passes.
+
+### Telemetry Database Not Initialized
+
+**Symptoms**:
+- `poetic compete results` fails with "No evaluation found" or "Database not initialized"
+- AI Judge evaluation commands fail
+- SQLite error messages when querying results
+
+**Cause**:
+The database may be missing, corrupt, or missing its schema. This can occur after an
+interrupted write, incomplete restore, or removal of ignored runtime state.
+
+**Diagnosis**:
+```bash
+poetic doctor --json
+poetic telemetry-checkpoint --verify --json
+```
+
+`poetic telemetry-checkpoint --repair` reports corruption but does not rebuild the database
+automatically.
+
+If the database is missing, initialize it and verify the result:
+
+```bash
+poetic init --db
+poetic telemetry-checkpoint --verify --json
+```
+
+If the database is corrupt and a Poetic backup exists, inspect the restore before applying
+it:
+
+```bash
+poetic backup list
+poetic backup restore --latest --dry-run
+```
+
+After reviewing the dry-run, stop active Poetic, provider, and agent processes, apply the
+restore, and verify:
+
+```bash
+poetic backup restore --latest --force
+poetic telemetry-checkpoint --verify --json
+```
+
+If no usable backup exists, stop all Poetic, provider, and agent activity before moving
+database files. Attempt a database backup first:
+
+```bash
+poetic backup
+```
+
+The backup command uses the external `sqlite3` executable. If it is unavailable or the
+corruption prevents a backup, copy the database and any SQLite sidecars together to a
+location outside the repository:
+
+```bash
+mkdir -p /path/outside/repo/poetic-db-saved
+cp .poetic/telemetry/db/variants.db* /path/outside/repo/poetic-db-saved/
+```
+
+Only after activity has stopped and the snapshot or copy has completed, quarantine the
+database and any sidecars rather than deleting them:
+
+```bash
+mkdir -p .poetic/telemetry/db/quarantine
+mv .poetic/telemetry/db/variants.db .poetic/telemetry/db/quarantine/
+test ! -e .poetic/telemetry/db/variants.db-wal || mv .poetic/telemetry/db/variants.db-wal .poetic/telemetry/db/quarantine/
+test ! -e .poetic/telemetry/db/variants.db-shm || mv .poetic/telemetry/db/variants.db-shm .poetic/telemetry/db/quarantine/
+poetic init --db
+poetic telemetry-checkpoint --verify --json
+```
+
+Keep the quarantined files until you have confirmed that the rebuilt database is usable
+and decided whether historical telemetry needs recovery.
+
+**Common causes**:
+- Force-cleaning ignored files with Git, which can remove the `.poetic/` directory
+- Insufficient disk space during database creation
+- File permission issues on `.poetic/` directory
+- Corrupted SQLite database file (rare)
+
+---
+
+## Implementation Artifacts (.poetic/implementations/)
+
+### "Implementation files missing" Warning
+
+**Status**:  **This is normal and healthy**
+
+Implementation artifacts are **ephemeral files** created only in variant worktrees during execution (including historical cloud-era runs). The main working directory should NOT contain `.poetic/implementations/*.md` files.
+
+**Why you're seeing this**:
+-  Empty `.poetic/implementations/` directory - **Normal**
+-  Missing `.poetic/implementations/` directory - **Normal**
+-  Old stale files - **Run `poetic cleanup prune`**
+
+**What to do**:
+```bash
+# Check artifact status
+poetic doctor --verbose
+
+# Clean up governed runtime artifacts
+poetic cleanup prune
+poetic cleanup prune --execute
+```
+
+**See also**: Placeholder implementation files are ephemeral worktree artifacts and should not persist in the main working tree.
+
+### CLI Load Failures ("Dynamic require" Errors)
+
+**Error**: `Dynamic require of "fs" is not supported`
+
+**Cause**: ESM/CommonJS incompatibility in bundled CLI
+
+**Status**:  **Fixed** (as of 2025-11-15)
+
+**If you still see this error**:
+```bash
+# Rebuild the CLI
+npm run build
+
+# Verify ESM compliance
+npm run check:esm
+
+# If error persists, report issue with:
+node --version  # Node.js version
+npm list better-sqlite3  # Module versions
+```
+
+**Make sure you're running the repo-local CLI build**
+
+```bash
+# 1) Inspect every poetic binary on PATH + global installs
+which -a poetic
+npm ls -g @poetic-ai/poetic
+
+# 2) Remove stale global installs (safe to run even if none exist)
+npm uninstall -g @poetic-ai/poetic || true
+which -a poetic
+
+# 3) Always launch competitions via the repo wrapper (rebuilds + logs version/SHA)
+./scripts/run-competition-local.sh "Task description" --variant claude:conservative:local
+```
+
+---
+
+## Getting Help
+
+### Self-Service Resources
+
+1. **Check this guide first** - Most common issues are covered
+2. **Use `--verbose` flag** - Get detailed error information
+3. **Check telemetry logs** - Review execution history
+4. **Test with simple tasks** - Isolate the problem
+
+### Community Support
+
+- **GitHub Issues**: [Report bugs and request features](https://github.com/your-org/poetic/issues)
+- **Documentation**: [Complete documentation](https://github.com/your-org/poetic/docs)
+- **Examples**: [Usage examples and patterns](https://github.com/your-org/poetic/examples)
+
+### Provider Support
+
+- **Claude**: [Anthropic Support](https://support.anthropic.com/)
+- **Gemini**: [Google AI Studio Support](https://aistudio.google.com/)
+- **Cursor**: [Cursor Support](https://cursor.sh/support)
+- **Codex**: [Codex Platform Support](https://codex.example.com/support)
+
+### Reporting Issues
+
+When reporting issues, include:
+
+1. **Error message** (exact text)
+2. **Command used** (with all flags)
+3. **Verbose output** (use `--verbose`)
+4. **System information** (OS, Node.js version)
+5. **Provider status** (authentication, quotas)
+6. **Log files** (relevant entries from `.poetic/telemetry/logs/`)
+
+---
+
+**Last Updated**: 2025-10-15 (Session 51 - T626314)
+**Version**: 0.1.0