ci(deps): bump actions/stale from 9 to 10

Bumps [actions/stale](https://github.com/actions/stale) from 9 to 10.
- [Release notes](https://github.com/actions/stale/releases)
- [Changelog](https://github.com/actions/stale/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/stale/compare/v9...v10)

---
updated-dependencies:
- dependency-name: actions/stale
  dependency-version: '10'
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <support@github.com>

.github/workflows/discord-release.yml

@@ -3,6 +3,7 @@ name: Discord Release Notification
 on:
   release:
     types: [published]
+  workflow_dispatch:
 
 jobs:
   discord-notification:

.github/workflows/release.yml

@@ -620,7 +620,7 @@ jobs:
           draft: false
           prerelease: ${{ contains(github.ref, 'beta') || contains(github.ref, 'alpha') }}
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.PAT_TOKEN || secrets.GITHUB_TOKEN }}
 
   # Update README with new version after successful release
   update-readme:

.github/workflows/stale.yml

@@ -11,7 +11,7 @@ jobs:
     permissions:
       issues: write
     steps:
-      - uses: actions/stale@v9
+      - uses: actions/stale@v10
         with:
           stale-issue-message: |
             This issue has been inactive for 60 days. It will be closed in 14 days if there's no activity.

CHANGELOG.md

@@ -1,3 +1,234 @@
+## 2.7.6 - Stability & Feature Enhancements
+
+### ✨ New Features
+
+- **Multi-profile account management** — Unified profile swapping with automatic token refresh and rate limit recovery for both OAuth and API-compatible providers
+
+- **Enhanced terminal experience** — Customizable terminal fonts with OS-specific defaults, Claude Code CLI settings injection, and improved worktree integration
+
+- **Advanced roadmap management** — Expand/collapse functionality for phase features and real-time sync with task lifecycle
+
+- **Queue System v2** — Smart task prioritization with auto-promotion and intelligent rate limit recovery
+
+- **GitHub integration enhancements** — AI-powered PR template generation, user-friendly API error handling, and improved review visibility
+
+- **UI/UX improvements** — Spell check support for text inputs, collapsible sidebar toggle, task screenshot capture, expandable task descriptions, and bulk worktree operations
+
+- **Evidence-based PR validation** — Advanced review system with trigger-driven exploration and enhanced recovery mechanisms
+
+### 🛠️ Improvements
+
+- **Performance optimizations** — Async parallel worktree listing prevents UI freezes and improves responsiveness
+
+- **Robustness enhancements** — Atomic file writes, better error detection in AI responses, and improved OOM/orphaned agent management for overnight builds
+
+- **Terminal stability** — Fixed GPU context exhaustion from large pastes, SIGABRT crashes on macOS shutdown, and session restoration on app restart
+
+- **Build & packaging** — XState bundling for packaged apps, aligned Linux package builds, and improved auto-updater for beta releases and DMG installations
+
+- **Diagnostic improvements** — Sentry instrumentation for Python subprocesses and better error tracking across the system
+
+### 🐛 Bug Fixes
+
+- **Terminal & PTY** — Fixed paste size limits, race conditions, rendering issues, text alignment, worktree crashes, and terminal content resizing on expansion
+
+- **PR review system** — Resolved error visibility in bundled apps, improved structured output validation with three-tier recovery, preserved findings during crashes, and fixed UTC timestamp detection for comment tracking
+
+- **Planning & task execution** — Fixed handling of empty/greenfield projects, atomic writes to prevent 0-byte file corruption, planning phase crashes, and implementation plan file watching
+
+- **Authentication & profiles** — Resolved OAuth token revocation loops, API profile mode support without OAuth requirement, subscription type preservation during token refresh, and Linux credential file detection
+
+- **Windows/cross-platform** — Complete System32 executable path fixes for where.exe and taskkill.exe, Windows credential normalization, and proper shell detection for Windows terminals
+
+- **Agent management** — Fixed infinite retry loops for tool concurrency errors, auth error detection, and title generator production path resolution
+
+- **UI/UX fixes** — Resolved Insights scroll-to-blank-space issues, infinite re-render loops in terminal font settings, kanban board scaling collisions, ideation stuck states, and panel constraint errors during terminal exit
+
+- **Worktree & Git** — Improved branch pattern validation, removed auto-commit on deletion, support for detached HEAD state during PR creation, and better merge conflict resolution with progress tracking
+
+- **Integrations** — Fixed Ollama infinite subprocess spawning, Graphiti import paths, OpenRouter API URL suffix, and GitLab authentication bugs
+
+- **Settings & configuration** — Corrected .auto-claude path discovery timeout, z.AI China preset URL, log order sorting, and onboarding completion state persistence
+
+### 📚 Documentation
+
+- Added Awesome Claude Code badge to README
+
+- Added instructions for resetting PR review state in CLAUDE.md
+
+---
+
+## What's Changed
+
+- fix: handle unknown SDK message types (rate_limit_event) to prevent session crashes by @AndyMik90 in 4a75ea9f9
+- fix: PR review error visibility and gh CLI resolution in bundled apps by @AndyMik90 in 732fc1cd3
+- fix: handle empty/greenfield projects in spec creation (#1426) (#1841) by @Andy in 819f98d9f
+- fix: clear terminalEventSeen on task restart to prevent stuck-after-planning (#1828) (#1840) by @Andy in 28a620079
+- fix: watch worktree path for implementation_plan.json changes (#1805) (#1842) by @Andy in fb3a3fbda
+- fix: resolve Claude CLI not found on Windows - PATH, prompt size, cwd (#1661) (#1843) by @Andy in 76d1d3b03
+- fix: handle planning phase crash and resume recovery (#1562) (#1844) by @Andy in 3cb05781f
+- fix: show dismissed PR review findings in UI instead of silently dropping them (#1852) by @Andy in d98ff7d19
+- fix: preserve file/line info in PR review extraction recovery (#1857) by @Andy in 635b53eea
+- docs: add Awesome Claude Code badge to README (#1838) by @Andy in 2e4b5ac65
+- test: achieve 100% test coverage for backend CLI commands (#1772) by @StillKnotKnown in 385f04414
+- fix: cap terminal paste size to 1MB to prevent GPU context exhaustion by @AndyMik90 in 7b0f3a2c0
+- fix: prevent OOM, orphaned agents, and unbounded growth during overnight builds (#1813) by @Andy in 4091d1d4b
+- docs: add instructions for resetting PR review state in CLAUDE.md by @AndyMik90 in ecb615802
+- auto-claude: 217-investigate-symlink-issues-in-work-tree-creation-f (#1808) by @Andy in ae13ce14c
+- auto-claude: 218-enable-claude-code-features-in-worktree-terminals (#1809) by @Andy in e3b219288
+- auto-claude: 219-investigate-and-fix-authentication-subscription-sy (#1810) by @Andy in 6204d5fc2
+- feat(roadmap): add expand/collapse functionality for phase features (#1796) by @Burak in f735f0b49
+- auto-claude: 216-display-ongoing-pr-review-logs-in-progress (#1807) by @Andy in a4870fa0c
+- fix(pr-review): reduce structured output failures and preserve findings in recovery (#1806) by @Andy in f1b8cd3a7
+- fix(sentry): enable Sentry for Python subprocesses and add diagnostic instrumentation (#1804) by @Andy in 4d4234378
+- fix(pr-review): add three-tier recovery for structured output validation failure (#1797) by @Andy in d1fbccde3
+- test: improve backend agent test coverage to 94% (#1779) by @StillKnotKnown in ed93df698
+- fix(github): use UTC timestamps for reviewed_at to fix comment detection (#1795) by @Andy in 8872d33e3
+- feat: add user-friendly GitHub API error handling (#1790) by @StillKnotKnown in 8ece0009e
+- fix(roadmap): sync roadmap features with task lifecycle (#1791) by @Andy in 115576e85
+- fix(github): resolve PR review hanging in bundled app (#1793) by @Andy in 3791b37bb
+- feat(profiles): implement unified profile swapping across OAuth and API accounts (#1794) by @StillKnotKnown in 282387356
+- test: improve backend memory system test coverage to 100% (#1780) by @StillKnotKnown in 4f1b7b2a9
+- fix(ideation): guard against non-string properties in IdeaCard badges by @AndyMik90 in 5e78d748e
+- fix(updater): convert HTML release notes to markdown before rendering by @AndyMik90 in aa5fc7f95
+- fix(pr-review): simplify structured output schema to reduce validation failures (#1787) by @Andy in cd8914700
+- fix(qa): enforce visual verification for UI changes and inject startup commands (#1784) by @Andy in f149a7fbd
+- fix(plan-files): use atomic writes to prevent 0-byte corruption (#1785) by @Andy in c2245b812
+- fix(terminal): make worktree dropdown scrollable and show all items by @AndyMik90 in 950da45e4
+- auto-claude: subtask-1-1 - Add adaptive thinking badge to thinking level label (#1782) by @Andy in 25acf2826
+- auto-claude: subtask-1-1 - Add overflow-hidden and break-words to subtask cards by @AndyMik90 in 39aa08872
+- refactor(app-updater): disable automatic downloads and allow intentional downgrades by @AndyMik90 in 8de8039db
+- fix(auth): detect auth errors in AI response text and prevent retry loops (#1776) by @Andy in f4788e4af
+- test: achieve 100% coverage for backend core workspace module (#1774) by @StillKnotKnown in 3f95765cf
+- fix(title-generator): add production path resolution for backend source (#1778) by @Andy in 923880f5b
+- fix(fast-mode): use setting_sources instead of env var for CLI fast mode (#1771) by @Andy in 390ba6a58
+- fix(windows): complete System32 executable path fixes for where.exe and taskkill.exe (#1715) by @VDT-91 in aa7f56e5d
+- fix(worktree): remove auto-commit on deletion and add uncommitted changes warning by @AndyMik90 in cec8e65ee
+- Smart PR Status Polling System (#1766) by @Andy in 48d5f7a32
+- feat: simplify thinking system and remove opus-1m model variant (#1760) by @Andy in bb7e18937
+- auto-claude: 203-fix-pr-review-ui-update-issue (#1732) by @Andy in 7589f8e4f
+- auto-claude: subtask-2-1 - Create isAPIProfileAuthenticated() function to val (#1745) by @Andy in 57e38a692
+- auto-claude: 202-fix-kanban-board-scaling-collisions (#1731) by @Andy in d09ebb850
+- auto-claude: 204-fix-pr-review-ui-not-updating-without-manual-navig (#1734) by @Andy in 087091cef
+- auto-claude: 203-fix-ui-not-updating-during-pr-review-operations (#1733) by @Andy in f085c08bd
+- auto-claude: 205-fix-insights-chat-only-shows-last-task-suggestion- (#1735) by @Andy in f121f9cdd
+- auto-claude: 197-roadmap-generation-stuck-at-50-file-locking-race-c (#1746) by @Andy in f41f15e59
+- auto-claude: 193-fix-update-context7-mcp-tool-name-from-get-library (#1744) by @Andy in bdff9141a
+- auto-claude: 192-changelog-generation-multiple-critical-bugs-tasks- (#1725) by @Andy in 8c9a504df
+- auto-claude: 194-bug-rate-limit-during-task-execution-causes-subtas (#1726) by @Andy in 8a7443d24
+- auto-claude: 201-bug-pr-review-logs-and-analysis (#1730) by @Andy in e0d53adb4
+- auto-claude: 196-fix-worktrees-dialog-auto-close-race-condition-and (#1727) by @Andy in 323b0d3be
+- auto-claude: 199-bug-logs-disappear-after-restart (#1728) by @Andy in d639f6ef8
+- auto-claude: 198-critical-oauth-token-revocation-causes-infinite-40 (#1747) by @Andy in 4438c0b10
+- Fix Panel Constraints Error During Terminal Exit (#1757) by @Andy in 32bf353da
+- auto-claude: 190-bug-context-page-crash-multiple-root-causes-when-v (#1724) by @Andy in 2db36982f
+- feat: add search/filter to WorktreeSelector dropdown (#1754) by @Andy in 09f059ca3
+- fix(terminal): push worktree branch to remote with tracking on creation (#1753) by @Andy in b5de0d9ff
+- auto-claude: 189-subtask-execution-stuck-in-infinite-retry-loop-whe (#1723) by @Andy in 445da186c
+- auto-claude: 188-terminal-claude-sessions-require-manual-click-to-r (#1743) by @Andy in f8499e965
+- auto-claude: 200-bug-changelog-and-release-generation (#1729) by @Andy in 826583b82
+- fix(terminal): use each terminal's cwd for invoke Claude all button (#1756) by @Andy in ac4fe4f42
+- feat(terminal): read Claude Code CLI settings and inject env vars into PTY sessions (#1750) by @Andy in 152e54093
+- fix: correct .auto-claude path mismatch causing discovery phase timeout (#1748) by @VDT-91 in 2c2a8a754
+- fix: remove incorrect /v1 suffix from OpenRouter API URL (#1749) by @StillKnotKnown in 7e799ee57
+- fix: prevent terminal worktree crash with race condition fixes (#1586) (#1658) by @VDT-91 in 216b58bcf
+- fix: correct log order sorting and add configurable log order setting (#1720) by @Burak in 2e2b82365
+- fix(ollama): stop infinite subprocess spawning from useEffect re-render loop (#1716) by @Quentin Veys in acb131b72
+- fix(graphiti): migrate graphiti_memory imports to canonical paths (#1714) by @Quentin Veys in df528f065
+- fix: improve auto-updater for beta releases and DMG installs (#1681) by @Andy in ff91a1af0
+- feat: unified operation registry for intelligent auth/rate limit recovery (#1698) by @Andy in 6d0222fa9
+- fix: Prevent stale worktree data from overriding correct task status (#1710) by @Burak in fe08c644c
+- feat: add subscriptionType and rateLimitTier to ClaudeProfile (#1688) by @Andy in a5e3cc9a2
+- auto-claude: subtask-1-1 - Add useTaskStore import and update task state after successful PR creation (#1683) by @Andy in 4587162e4
+- auto-claude: 182-implement-pagination-and-filtering-for-github-pr-l (#1654) by @Andy in b4e6b2fe4
+- auto-claude: 181-add-expand-button-for-long-task-descriptions (#1653) by @Andy in d9cd300fe
+- fix(terminal): resolve text alignment issues on expand/minimize (#1650) by @VDT-91 in f5a7e26d9
+- fix(windows): use full path to where.exe for reliable executable lookup (#1659) by @VDT-91 in 5f63daa3c
+- fix: resolve ideation stuck at 3/6 types bug (#1660) by @VDT-91 in e6e8da17c
+- Clarify Local and Origin Branch Distinction (#1652) by @Andy in 9317148b6
+- auto-claude: 186-set-default-dark-mode-on-startup (#1656) by @Andy in 473020621
+- auto-claude: subtask-1-1 - Add min-h-0 to enable scrolling in Roadmap tabs (#1655) by @Andy in ae703be9f
+- fix: XState status lifecycle & cross-project contamination fixes (#1647) by @kaigler in 5293fb399
+- refactor(frontend): complete XState task state machine migration (#1338) (#1575) by @kaigler in e2f9abadb
+- Merge conflict resolution progress bar and log viewer (#1620) by @Andy in d16be3077
+- fix: align Linux package builds (AppImage/deb/Flatpak) with target-specific extraResources (#1623) by @StillKnotKnown in bad1a9b2c
+- Fix/gitlab bugs (#1519 and #1521) (#1544) by @bu5hm4nn in cd423c65c
+- feat(kanban): add bulk task delete and worktree cleanup improvements (#1588) by @kaigler in 02ed91c91
+- fix: add worktree isolation warning to prevent agent escape (#1528) by @kaigler in fe5cc582b
+- feat(ui): add spell check support for text inputs (#1304) by @kaigler in 8f02a5129
+- fix(windows): complete Windows credential fixes with path normalization (#1585) by @kaigler in 1e1997167
+- AI-Powered GitHub PR Template Generation (#1618) by @Andy in 900dd4360
+- Fix pty.node SIGABRT crash on macOS shutdown (#1619) by @Andy in f355e09d7
+- fix(merge): use git merge for diverged branches with progress tracking (#1605) by @Andy in bde2ca4b2
+- Surface Billing/Credit Exhaustion Errors to UI (Issue #1580) (#1617) by @Andy in 7bf12e856
+- auto-claude: subtask-1-1 - Change $teamId type from ID! to String! in the team query (#1627) by @Andy in 54d0cd2f4
+- fix(auth): support API profile mode without OAuth requirement (#1616) by @StillKnotKnown in f8cc63af4
+- fix: agent retry loop for tool concurrency errors (#1546) [v3] (#1606) by @Michael Ludlow in 0aea4fb5e
+- fix(queue): enforce max parallel tasks and auto-refresh UI (#1594) by @Andy in 4070a4c29
+- Persist Kanban column collapse state per project via main process (#1579) by @Andy in a1114664e
+- feat(pr-review): evidence-based validation and trigger-driven exploration (#1593) by @Andy in bfc232825
+- fix(ui): smart auto-scroll for Insights streaming responses (#1591) by @kaigler in eee97e7ea
+- fix(changelog): validate Claude CLI exists before generation (#1305) by @kaigler in c1f24c07f
+- auto-claude: subtask-1-1 - Add min-w-0 class to subtask title row flex container (#1578) by @Andy in 286591c02
+- auto-claude: subtask-1-1 - Remove Popover wrapper and related functionality from ClaudeCodeStatusBadge (#1566) by @Andy in 8d18cc81a
+- fix(claude-profile): preserve subscriptionType and rateLimitTier during token refresh (#1556) by @Andy in 52e426a48
+- auto-claude: subtask-1-1 - Update cancelReview callback to handle both success and failure cases (#1551) by @Andy in d8f00fe5a
+- fix(backend): prioritize git remote detection over env var for repo (#1555) by @Andy in 9b07ed464
+- fix(backend): handle detached HEAD state when pushing branch for PR creation (#1560) by @Andy in 2b72694d0
+- fix: add explicit UTF-8 encoding across all Electron main process I/O (#1554) by @Andy in 4243530e9
+- fix(backend): pass OAuth token to Python subprocess for authentication by @AndyMik90 in 6f1002dd7
+- perf(frontend): async parallel worktree listing to prevent UI freezes (#1553) by @Andy in 399a7e736
+- auto-claude: subtask-1-1 - Remove amber lock indicator line from kanban resize handle (#1557) by @Andy in 83a64b88e
+- fix(frontend): resolve TerminalFontSettings infinite re-render loop (#1536) by @StillKnotKnown in 1c6266025
+- fix(frontend): respect hasCompletedOnboarding from ~/.claude.json (#1537) by @StillKnotKnown in 1860c2c43
+- fix: prevent planner from generating invalid verification types (#1388) (#1529) by @kaigler in 94d941333
+- fix(frontend): resolve Insights scroll-to-blank-space issue on macOS (ACS-382) (#1535) by @StillKnotKnown in 496b2b96a
+- feat: add customizable terminal fonts with OS-specific defaults (#1412) by @StillKnotKnown in f289107b8
+- Add dev mode screenshot capture warning (#1516) by @Andy in 16eeb301a
+- fix: add worktree isolation warnings to prevent agent escape (ACS-394) (#1495) by @StillKnotKnown in 1e453653b
+- fix: resolve flaky subprocess-spawn test on Windows CI (ACS-392) (#1494) by @StillKnotKnown in f6b264d56
+- feat(task-logger): strip ANSI escape codes from logs and extend coverage (#1411) by @StillKnotKnown in 988ec0c25
+- fix(frontend): use spawn() instead of exec() for Windows terminal launching (#1498) by @StillKnotKnown in 26c9083d3
+- fix(api-profiles): correct z.AI China preset URL and rename provider presets (#1500) by @StillKnotKnown in 05cf0a516
+- fix: validate branch pattern before worktree cleanup to prevent deleting wrong branch (#1493) by @StillKnotKnown in 8576754a1
+- Real-Time Updates for Insights Chat (#1511) by @Andy in d940b6ade
+- Fix Terminal UI Rendering Issues (#1514) by @Andy in 8d8306b8e
+- Fix terminal content resizing on expansion (#1512) by @Andy in 9f6c0026b
+- Restore Terminal Session History on App Restart (#1515) by @Andy in 63e2847fc
+- Move Reference Images Above Task Title & Fix Image Display Issues (#1513) by @Andy in b269ac305
+- auto-claude: 143-fix-github-integration-ui-refresh-issues (#1467) by @Andy in aa2cb4fa6
+- feat: Multi-profile account swapping with token refresh and queue routing (#1496) by @Andy in 1e72c8d77
+- Simplified Testing Strategy for Regression Prevention (#1379) by @Andy in ae4e48e8b
+- auto-claude: 152-persist-tasks-during-roadmap-regeneration (#1463) by @Andy in 9bd3d7e3b
+- Debug Kanban Memory & Add Sentry Monitoring (#1380) by @Andy in bc5f550ee
+- auto-claude: 147-remove-outdated-compatibility-shims (#1465) by @Andy in 53111dbb9
+- auto-claude: 162-fix-worktree-error-on-repeated-task-starts (#1453) by @Andy in b955badf7
+- auto-claude: 155-fix-pr-list-diff-display-metrics (#1458) by @Andy in 31f116db5
+- auto-claude: 151-fix-pr-review-agent-token-refresh-on-account-swap (#1456) by @Andy in d081af042
+- auto-claude: 148-add-progress-persistence-and-status-indicators (#1464) by @Andy in 4937d5745
+- auto-claude: 154-fix-task-modal-conflict-check-status-refresh (#1462) by @Andy in 0299009df
+- auto-claude: 153-widen-kanban-columns-and-add-collapse-feature (#1457) by @Andy in d65973075
+- auto-claude: subtask-1-1 - Add filter after map operation to remove empty str (#1466) by @Andy in 783f0fe0e
+- fix: add formatReleaseNotes helper for markdown changelog rendering (#1468) by @Andy in 43a97e1b3
+- feat(sidebar): add collapsible sidebar toggle (#1501) by @Michael Ludlow in d17c17887
+- fix(auth): check .credentials.json for Linux profile authentication (#1492) by @StillKnotKnown in 8d2f66291
+- auto-claude: subtask-1-1 - Replace ReleaseNotesRenderer with ReactMarkdown (#1454) by @Andy in 1185a558c
+- auto-claude: 156-fix-electron-app-version-detection-bug (#1459) by @Andy in 9a3b48c25
+- auto-claude: subtask-1-1 - Add --no-track flag to git worktree add command (#1455) by @Andy in 0c2990815
+- auto-claude: subtask-1-1 - Change task.specId to taskId in 3 startSpecCreation calls (#1461) by @Andy in 91edc0e14
+- fix(onboarding): align MemoryStep layout with Settings MemoryBackendSection (#1445) by @Michael Ludlow in e9de26d59
+- auto-claude: subtask-1-1 - Add metadata?.requireReviewBeforeCoding check (#1460) by @Andy in 426d56571
+- fix: use API profile environment variables for task title generation (#1471) by @JoshuaRileyDev in c5a0f042d
+- fix(auth): Long-lived OAuth authentication with multi-profile usage display (#1443) by @Andy in 12e788417
+- feat: Add screenshot capture to task creation modal (#1429) by @JoshuaRileyDev in 1a2a1b1fc
+- fix: prevent queue settings modal from disappearing when tasks change (#1430) by @JoshuaRileyDev in 33acc1430
+- feat: Queue System v2 with Auto-Promotion and Smart Task Management (#1203) by @JoshuaRileyDev in 3b87e24d7
+- feat: Add API profile providers usage endpoints support (#1279) by @StillKnotKnown in cfe7dedd0
+
+## Thanks to all contributors
+
+@AndyMik90, @Andy, @Burak, @StillKnotKnown, @VDT-91, @kaigler, @Michael Ludlow, @JoshuaRileyDev, @Quentin Veys, @bu5hm4nn
+
 ## 2.7.5 - Security & Platform Improvements
 
 ### ✨ New Features

CLAUDE.md

@@ -30,27 +30,55 @@ Auto Claude is a desktop application (+ CLI) where users describe a goal and AI
 
 ## Critical Rules
 
-**Claude Agent SDK only** — All AI interactions use `claude-agent-sdk`. NEVER use `anthropic.Anthropic()` directly. Always use `create_client()` from `core.client`.
+**Claude Agent SDK only** — All AI interactions use `claude-agent-sdk` because it handles security hooks, tool permissions, and MCP server integration. Use `create_client()` from `core.client`, not `anthropic.Anthropic()` directly.
 
-**i18n required** — All frontend user-facing text MUST use `react-i18next` translation keys. Never hardcode strings in JSX/TSX. Add keys to both `en/*.json` and `fr/*.json`.
+**i18n required** — All frontend user-facing text uses `react-i18next` translation keys. Hardcoded strings in JSX/TSX break localization for non-English users. Add keys to both `en/*.json` and `fr/*.json`.
 
-**Platform abstraction** — Never use `process.platform` directly. Import from `apps/frontend/src/main/platform/` or `apps/backend/core/platform/`. CI tests all three platforms.
+**Platform abstraction** — Use the platform modules in `apps/frontend/src/main/platform/` or `apps/backend/core/platform/` instead of `process.platform` directly. CI tests all three platforms, and raw platform checks cause failures.
 
-**No time estimates** — Never provide duration predictions. Use priority-based ordering instead.
+**No time estimates** — Provide priority-based ordering instead of duration predictions.
 
-**PR target** — Always target the `develop` branch for PRs to AndyMik90/Auto-Claude, NOT `main`.
+**PR target** — Always target the `develop` branch for PRs, not `main`. Main is reserved for releases.
 
-## Work Approach
+**No console.log in production code** — `console.log` output is invisible in bundled Electron apps. Use Sentry for error tracking in production; reserve `console.log` for development only.
 
-**Investigate before speculating** — Always read the actual code before proposing root causes. Spawn agents to grep and read relevant source files before forming any hypothesis. Never guess at causes without evidence from the codebase.
+## Work Approach: Orchestrator-First
 
-**Spawn agents for complex tasks** — When tackling complex tasks, spawn sub-agents/agent teams immediately rather than trying to handle everything in a single context window. Never attempt to analyze large codebases or multiple features monolithically.
+You are an orchestrator. Your primary role is to understand what needs to be done, break it into workstreams, and delegate execution to agent teams. This keeps your context window focused on coordination and decision-making rather than filling up with implementation details.
 
-**Minimal fixes only** — Prefer the simplest approach (e.g., prompt-only changes, single guard clause) before suggesting multi-component solutions. If the user asks for X, implement X — don't bundle additional fixes they didn't request.
+<orchestrator_pattern>
+When given a task, follow this pattern:
+
+1. **Investigate first** — Read the actual code before forming any hypothesis. Use targeted searches (Glob, Grep, Read) for simple lookups. For broader exploration, spawn an Explore agent.
+
+2. **Plan the approach** — Identify what needs to change, which files are involved, and whether work can be parallelized. For multi-step tasks, create a task list to track workstreams.
+
+3. **Delegate execution** — Spawn agent teams to do the implementation work. Each agent gets a clear, self-contained assignment with all the context it needs: relevant file paths, the specific change to make, and acceptance criteria. Run independent workstreams in parallel.
+
+4. **Verify and integrate** — Review agent outputs, run tests, and ensure changes work together. Fix integration issues or spawn follow-up agents as needed.
+</orchestrator_pattern>
+
+**When to delegate vs. do directly:**
+- Delegate: multi-file changes, research across the codebase, independent parallel workstreams, tasks that would consume significant context
+- Do directly: single-file edits, simple bug fixes, quick lookups, tasks where you already have the context
+
+**Giving agents good assignments** — Each agent works with a fresh context. Include: the specific goal, relevant file paths, code patterns to follow, and what "done" looks like. Agents perform better with explicit, complete instructions than with vague references to "the current task."
+
+**Minimal changes only** — Prefer the simplest approach (e.g., prompt-only changes, single guard clause) before suggesting multi-component solutions. If the user asks for X, implement X — don't bundle additional fixes they didn't request.
+
+**Default to action** — When the user's intent implies making changes, implement them rather than only suggesting. If something is unclear, read the relevant code to fill in the gaps rather than asking. Only ask when genuine ambiguity remains about what the user wants.
+
+## Context Management
+
+Your context window will be automatically compacted as it approaches its limit, allowing you to continue working indefinitely. Do not stop tasks early due to context concerns — instead, persist progress and keep going.
+
+**For long-running tasks:** Use git commits, task lists, and structured notes to track state. When context compacts, review git log and any progress files to re-orient. Focus on incremental progress — complete one component before moving to the next, and commit working states along the way.
+
+**Parallel tool calls** — When reading multiple files, running independent searches, or executing unrelated commands, make all calls in parallel rather than sequentially. This significantly speeds up investigation and implementation.
 
 ## Known Gotchas
 
-**Electron path resolution** — For bug fixes in the Electron app, always check path resolution differences between dev and production builds (`app.isPackaged`, `process.resourcesPath`). Paths that work in dev often break when Electron is bundled for production — verify both contexts.
+**Electron path resolution** — For bug fixes in the Electron app, check path resolution differences between dev and production builds (`app.isPackaged`, `process.resourcesPath`). Paths that work in dev often break when Electron is bundled for production — verify both contexts.
 
 ### Resetting PR Review State
 
@@ -276,7 +304,7 @@ Supports Windows, macOS, Linux. CI tests all three.
 | `findExecutable(name)` | Cross-platform executable lookup |
 | `requiresShell(command)` | `.cmd/.bat` shell detection (Win) |
 
-Never hardcode paths. Use `findExecutable()` and `joinPaths()`. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#cross-platform-development) for extended guide.
+Use `findExecutable()` and `joinPaths()` instead of hardcoded paths. See [ARCHITECTURE.md](shared_docs/ARCHITECTURE.md#cross-platform-development) for extended guide.
 
 ## E2E Testing (Electron MCP)
 

README.md

@@ -17,18 +17,18 @@
 ### Stable Release
 
 <!-- STABLE_VERSION_BADGE -->
-[![Stable](https://img.shields.io/badge/stable-2.7.5-blue?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.5)
+[![Stable](https://img.shields.io/badge/stable-2.7.6-blue?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.6)
 <!-- STABLE_VERSION_BADGE_END -->
 
 <!-- STABLE_DOWNLOADS -->
 | Platform | Download |
 |----------|----------|
-| **Windows** | [Auto-Claude-2.7.5-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-win32-x64.exe) |
-| **macOS (Apple Silicon)** | [Auto-Claude-2.7.5-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-darwin-arm64.dmg) |
-| **macOS (Intel)** | [Auto-Claude-2.7.5-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-darwin-x64.dmg) |
-| **Linux** | [Auto-Claude-2.7.5-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-linux-x86_64.AppImage) |
-| **Linux (Debian)** | [Auto-Claude-2.7.5-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-linux-amd64.deb) |
-| **Linux (Flatpak)** | [Auto-Claude-2.7.5-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.5/Auto-Claude-2.7.5-linux-x86_64.flatpak) |
+| **Windows** | [Auto-Claude-2.7.6-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6/Auto-Claude-2.7.6-win32-x64.exe) |
+| **macOS (Apple Silicon)** | [Auto-Claude-2.7.6-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6/Auto-Claude-2.7.6-darwin-arm64.dmg) |
+| **macOS (Intel)** | [Auto-Claude-2.7.6-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6/Auto-Claude-2.7.6-darwin-x64.dmg) |
+| **Linux** | [Auto-Claude-2.7.6-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6/Auto-Claude-2.7.6-linux-x86_64.AppImage) |
+| **Linux (Debian)** | [Auto-Claude-2.7.6-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6/Auto-Claude-2.7.6-linux-amd64.deb) |
+| **Linux (Flatpak)** | [Auto-Claude-2.7.6-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6/Auto-Claude-2.7.6-linux-x86_64.flatpak) |
 <!-- STABLE_DOWNLOADS_END -->
 
 ### Beta Release
@@ -36,18 +36,18 @@
 > ⚠️ Beta releases may contain bugs and breaking changes. [View all releases](https://github.com/AndyMik90/Auto-Claude/releases)
 
 <!-- BETA_VERSION_BADGE -->
-[![Beta](https://img.shields.io/badge/beta-2.7.6--beta.5-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.6-beta.5)
+[![Beta](https://img.shields.io/badge/beta-2.7.6--beta.6-orange?style=flat-square)](https://github.com/AndyMik90/Auto-Claude/releases/tag/v2.7.6-beta.6)
 <!-- BETA_VERSION_BADGE_END -->
 
 <!-- BETA_DOWNLOADS -->
 | Platform | Download |
 |----------|----------|
-| **Windows** | [Auto-Claude-2.7.6-beta.5-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-win32-x64.exe) |
-| **macOS (Apple Silicon)** | [Auto-Claude-2.7.6-beta.5-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-darwin-arm64.dmg) |
-| **macOS (Intel)** | [Auto-Claude-2.7.6-beta.5-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-darwin-x64.dmg) |
-| **Linux** | [Auto-Claude-2.7.6-beta.5-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-linux-x86_64.AppImage) |
-| **Linux (Debian)** | [Auto-Claude-2.7.6-beta.5-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-linux-amd64.deb) |
-| **Linux (Flatpak)** | [Auto-Claude-2.7.6-beta.5-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.5/Auto-Claude-2.7.6-beta.5-linux-x86_64.flatpak) |
+| **Windows** | [Auto-Claude-2.7.6-beta.6-win32-x64.exe](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.6/Auto-Claude-2.7.6-beta.6-win32-x64.exe) |
+| **macOS (Apple Silicon)** | [Auto-Claude-2.7.6-beta.6-darwin-arm64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.6/Auto-Claude-2.7.6-beta.6-darwin-arm64.dmg) |
+| **macOS (Intel)** | [Auto-Claude-2.7.6-beta.6-darwin-x64.dmg](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.6/Auto-Claude-2.7.6-beta.6-darwin-x64.dmg) |
+| **Linux** | [Auto-Claude-2.7.6-beta.6-linux-x86_64.AppImage](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.6/Auto-Claude-2.7.6-beta.6-linux-x86_64.AppImage) |
+| **Linux (Debian)** | [Auto-Claude-2.7.6-beta.6-linux-amd64.deb](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.6/Auto-Claude-2.7.6-beta.6-linux-amd64.deb) |
+| **Linux (Flatpak)** | [Auto-Claude-2.7.6-beta.6-linux-x86_64.flatpak](https://github.com/AndyMik90/Auto-Claude/releases/download/v2.7.6-beta.6/Auto-Claude-2.7.6-beta.6-linux-x86_64.flatpak) |
 <!-- BETA_DOWNLOADS_END -->
 
 > All releases include SHA256 checksums and VirusTotal scan results for security verification.

apps/backend/__init__.py

@@ -19,5 +19,5 @@ Quick Start:
 See README.md for full documentation.
 """
 
-__version__ = "2.7.6-beta.5"
+__version__ = "2.7.6"
 __author__ = "Auto Claude Team"

apps/backend/agents/coder.py

@@ -13,7 +13,9 @@ import re
 from datetime import datetime, timedelta
 from pathlib import Path
 
+from context.constants import SKIP_DIRS
 from core.client import create_client
+from core.file_utils import write_json_atomic
 from linear_updater import (
     LinearTaskState,
     is_linear_enabled,
@@ -84,6 +86,7 @@ from .memory_manager import debug_memory_system_status, get_graphiti_context
 from .session import post_session_processing, run_agent_session
 from .utils import (
     find_phase_for_subtask,
+    find_subtask_in_plan,
     get_commit_count,
     get_latest_commit,
     load_implementation_plan,
@@ -97,8 +100,383 @@ logger = logging.getLogger(__name__)
 # FILE VALIDATION UTILITIES
 # =============================================================================
 
+# Directories to exclude from file path search — extends context.constants.SKIP_DIRS
+_EXCLUDE_DIRS = frozenset(SKIP_DIRS | {".auto-claude", ".tox", "out"})
 
-def validate_subtask_files(subtask: dict, project_dir: Path) -> dict:
+
+def _build_file_index(
+    project_dir: Path, suffixes: set[str]
+) -> dict[str, list[tuple[str, Path]]]:
+    """
+    Build an index of project files grouped by basename, scanning the tree once.
+
+    Also indexes index.{ext} files under their parent directory name as a
+    secondary key (e.g., api/index.ts is indexed under both "index.ts" and
+    "api" as directory-stem).
+
+    Args:
+        project_dir: Root directory of the project
+        suffixes: File extensions to index (e.g., {".ts", ".tsx"})
+
+    Returns:
+        Dict mapping basename -> list of (relative_path_str, Path(relative_path))
+    """
+    index: dict[str, list[tuple[str, Path]]] = {}
+    resolved_str = str(project_dir.resolve())
+
+    for root, dirs, files in os.walk(project_dir.resolve()):
+        dirs[:] = [d for d in dirs if d not in _EXCLUDE_DIRS]
+
+        for filename in files:
+            ext_idx = filename.rfind(".")
+            if ext_idx == -1:
+                continue
+            file_suffix = filename[ext_idx:]
+            if file_suffix not in suffixes:
+                continue
+
+            full_path = os.path.join(root, filename)
+            rel_str = os.path.relpath(full_path, resolved_str).replace(os.sep, "/")
+            rel_path = Path(rel_str)
+
+            # Index by basename
+            index.setdefault(filename, []).append((rel_str, rel_path))
+
+            # Also index index.{ext} files by parent dir name (for stem matching)
+            stem_part = filename[:ext_idx]
+            if stem_part == "index":
+                dir_name = os.path.basename(root)
+                key = f"__dir_stem__:{dir_name}{file_suffix}"
+                index.setdefault(key, []).append((rel_str, rel_path))
+
+    return index
+
+
+def _score_and_select(candidates: list[tuple[str, float]]) -> str | None:
+    """
+    Select the best candidate from a scored list of (path, score) pairs.
+
+    Requires a minimum score of 8.0 and a gap of at least 3.0 from the
+    runner-up to avoid ambiguous matches.
+
+    Args:
+        candidates: List of (relative_path, score) tuples
+
+    Returns:
+        Best path if unambiguous, None otherwise
+    """
+    if not candidates:
+        return None
+
+    candidates.sort(key=lambda x: x[1], reverse=True)
+    best_path, best_score = candidates[0]
+
+    if best_score < 8.0:
+        return None
+
+    if len(candidates) > 1:
+        runner_up_score = candidates[1][1]
+        if best_score - runner_up_score < 3.0:
+            return None
+
+    return best_path
+
+
+def _find_correct_path_indexed(
+    missing_path: str,
+    parent_parts: tuple[str, ...],
+    file_index: dict[str, list[tuple[str, Path]]],
+) -> str | None:
+    """
+    Find the correct path using a pre-built file index (no tree walk needed).
+
+    Args:
+        missing_path: The incorrect file path from the plan
+        parent_parts: Parent directory parts of the missing path
+        file_index: Index built by _build_file_index
+
+    Returns:
+        Corrected relative path, or None if no good match found
+    """
+    missing = Path(missing_path)
+    basename = missing.name
+    stem = missing.stem
+    suffix = missing.suffix
+
+    if not suffix:
+        return None
+
+    candidates: list[tuple[str, float]] = []
+
+    # Strategy 1: Exact basename match
+    for rel_str, rel_path in file_index.get(basename, []):
+        score = 10.0
+        candidate_parts = rel_path.parent.parts
+        for i, part in enumerate(parent_parts):
+            if i < len(candidate_parts) and candidate_parts[i] == part:
+                score += 3.0
+        depth_diff = abs(len(candidate_parts) - len(parent_parts))
+        score -= 0.5 * depth_diff
+        candidates.append((rel_str, score))
+
+    # Strategy 2: index.{ext} in directory matching stem
+    stem_key = f"__dir_stem__:{stem}{suffix}"
+    for rel_str, rel_path in file_index.get(stem_key, []):
+        score = 8.0
+        candidate_parts = rel_path.parent.parts
+        for i, part in enumerate(parent_parts):
+            if i < len(candidate_parts) and candidate_parts[i] == part:
+                score += 3.0
+        depth_diff = abs(len(candidate_parts) - len(parent_parts))
+        score -= 0.5 * depth_diff
+        candidates.append((rel_str, score))
+
+    return _score_and_select(candidates)
+
+
+def _find_correct_path(missing_path: str, project_dir: Path) -> str | None:
+    """
+    Attempt to find the correct path for a missing file using fuzzy matching.
+
+    Strategies:
+    1. Same basename in nearby directory
+    2. index.{ext} pattern (e.g., preload/api.ts -> preload/api/index.ts)
+
+    Uses os.walk with directory pruning to avoid traversing into node_modules,
+    .git, dist, etc. — unlike Path.rglob which traverses everything then filters.
+
+    Args:
+        missing_path: The incorrect file path from the plan
+        project_dir: Root directory of the project
+
+    Returns:
+        Corrected relative path, or None if no good match found
+    """
+    missing = Path(missing_path)
+    basename = missing.name
+    stem = missing.stem
+    suffix = missing.suffix
+    parent_parts = missing.parent.parts
+
+    if not suffix:
+        return None
+
+    candidates: list[tuple[str, float]] = []
+    resolved_project = project_dir.resolve()
+    resolved_str = str(resolved_project)
+
+    # os.walk with pruning: modify dirs in-place to skip excluded directories
+    for root, dirs, files in os.walk(resolved_project):
+        dirs[:] = [d for d in dirs if d not in _EXCLUDE_DIRS]
+
+        for filename in files:
+            if not filename.endswith(suffix):
+                continue
+
+            full_path = os.path.join(root, filename)
+            rel_str = os.path.relpath(full_path, resolved_str).replace(os.sep, "/")
+            rel = Path(rel_str)
+
+            score = 0.0
+
+            # Strategy 1: Exact basename match
+            if filename == basename:
+                score += 10.0
+            # Strategy 2: index.{ext} in directory matching stem
+            elif filename == f"index{suffix}" and os.path.basename(root) == stem:
+                score += 8.0
+            else:
+                continue
+
+            # Bonus: shared parent directory segments
+            candidate_parts = rel.parent.parts
+            for i, part in enumerate(parent_parts):
+                if i < len(candidate_parts) and candidate_parts[i] == part:
+                    score += 3.0
+
+            # Penalty: depth difference
+            depth_diff = abs(len(candidate_parts) - len(parent_parts))
+            score -= 0.5 * depth_diff
+
+            candidates.append((rel_str, score))
+
+    return _score_and_select(candidates)
+
+
+def _auto_correct_subtask_files(
+    subtask: dict,
+    missing_files: list[str],
+    project_dir: Path,
+    spec_dir: Path,
+) -> list[str]:
+    """
+    Attempt to auto-correct missing file paths in a subtask.
+
+    Corrects paths in-memory AND persists changes to implementation_plan.json.
+
+    Args:
+        subtask: Subtask dictionary containing files_to_modify
+        missing_files: List of file paths that don't exist
+        project_dir: Root directory of the project
+        spec_dir: Spec directory containing implementation_plan.json
+
+    Returns:
+        List of file paths that could NOT be corrected
+    """
+    corrections: dict[str, str] = {}
+    still_missing: list[str] = []
+
+    # Build file index once for all missing files (avoids repeated os.walk)
+    suffixes_needed: set[str] = set()
+    for missing_path in missing_files:
+        suffix = Path(missing_path).suffix
+        if suffix:
+            suffixes_needed.add(suffix)
+    file_index = (
+        _build_file_index(project_dir, suffixes_needed) if suffixes_needed else {}
+    )
+
+    for missing_path in missing_files:
+        missing = Path(missing_path)
+        corrected = _find_correct_path_indexed(
+            missing_path, missing.parent.parts, file_index
+        )
+        if corrected:
+            corrections[missing_path] = corrected
+            logger.info(f"Auto-corrected file path: {missing_path} -> {corrected}")
+            print_status(f"Auto-corrected: {missing_path} -> {corrected}", "success")
+        else:
+            still_missing.append(missing_path)
+
+    if not corrections:
+        return still_missing
+
+    # Update subtask in-memory
+    files_to_modify = subtask.get("files_to_modify", [])
+    subtask["files_to_modify"] = [corrections.get(f, f) for f in files_to_modify]
+
+    # Persist corrections to implementation_plan.json
+    plan_file = spec_dir / "implementation_plan.json"
+    if plan_file.exists():
+        try:
+            with open(plan_file, encoding="utf-8") as f:
+                plan = json.load(f)
+
+            subtask_id = subtask.get("id")
+            if subtask_id is not None:
+                plan_subtask = find_subtask_in_plan(plan, subtask_id)
+                if plan_subtask:
+                    plan_files = plan_subtask.get("files_to_modify", [])
+                    plan_subtask["files_to_modify"] = [
+                        corrections.get(f, f) for f in plan_files
+                    ]
+
+            write_json_atomic(plan_file, plan)
+            logger.info(
+                f"Persisted {len(corrections)} path correction(s) to implementation_plan.json"
+            )
+        except (OSError, TypeError, ValueError) as e:
+            logger.warning(f"Failed to persist path corrections: {e}")
+
+    return still_missing
+
+
+def _validate_plan_file_paths(spec_dir: Path, project_dir: Path) -> str | None:
+    """
+    Validate all file paths in the implementation plan after planning.
+
+    Builds a file index once, then checks all paths across all subtasks against it.
+    Attempts auto-correction for missing paths. Returns a retry context string for
+    the planner if uncorrectable paths remain, or None if all paths are valid.
+
+    Args:
+        spec_dir: Spec directory containing implementation_plan.json
+        project_dir: Root directory of the project
+
+    Returns:
+        Retry context string if issues remain, None if all OK
+    """
+    plan_file = spec_dir / "implementation_plan.json"
+    if not plan_file.exists():
+        return None
+
+    try:
+        with open(plan_file, encoding="utf-8") as f:
+            plan = json.load(f)
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return None
+
+    resolved_project = project_dir.resolve()
+
+    # First pass: collect all missing files and their suffixes
+    missing_entries: list[
+        tuple[list[str], int, str]
+    ] = []  # (subtask_files_list, index, path)
+    suffixes_needed: set[str] = set()
+
+    for phase in plan.get("phases", []):
+        for subtask in phase.get("subtasks", []):
+            files = subtask.get("files_to_modify", [])
+            for i, file_path in enumerate(files):
+                full_path = (resolved_project / file_path).resolve()
+                if not full_path.is_relative_to(resolved_project):
+                    continue
+                if full_path.exists():
+                    continue
+
+                missing = Path(file_path)
+                if missing.suffix:
+                    suffixes_needed.add(missing.suffix)
+                    missing_entries.append((files, i, file_path))
+
+    if not missing_entries:
+        return None
+
+    # Build index once for all needed suffixes
+    file_index = _build_file_index(project_dir, suffixes_needed)
+
+    all_missing: list[str] = []
+    corrections_made = 0
+
+    for files_list, idx, file_path in missing_entries:
+        missing = Path(file_path)
+        corrected = _find_correct_path_indexed(
+            file_path, missing.parent.parts, file_index
+        )
+        if corrected:
+            files_list[idx] = corrected
+            corrections_made += 1
+            logger.info(f"Post-plan auto-corrected: {file_path} -> {corrected}")
+            print_status(f"Auto-corrected: {file_path} -> {corrected}", "success")
+        else:
+            all_missing.append(file_path)
+
+    # Persist any corrections that were made
+    if corrections_made > 0:
+        try:
+            write_json_atomic(plan_file, plan)
+            logger.info(f"Persisted {corrections_made} post-plan path correction(s)")
+        except (OSError, TypeError, ValueError) as e:
+            logger.warning(f"Failed to persist post-plan corrections: {e}")
+
+    if not all_missing:
+        return None
+
+    return (
+        "## FILE PATH VALIDATION ERRORS\n\n"
+        "The following files referenced in your implementation plan do NOT exist "
+        "and could not be auto-corrected:\n"
+        + "\n".join(f"- `{p}`" for p in all_missing)
+        + "\n\nPlease fix these file paths in the `implementation_plan.json`.\n"
+        "Use the project's actual file structure to find the correct paths.\n"
+        "Common issues: wrong directory nesting, missing index files "
+        "(e.g., `dir/file.ts` should be `dir/file/index.ts`)."
+    )
+
+
+def validate_subtask_files(
+    subtask: dict, project_dir: Path, spec_dir: Path | None = None
+) -> dict:
     """
     Validate all files_to_modify exist before subtask execution.
 
@@ -136,6 +514,15 @@ def validate_subtask_files(subtask: dict, project_dir: Path) -> dict:
         }
 
     if missing_files:
+        # Attempt auto-correction if spec_dir is provided
+        if spec_dir:
+            still_missing = _auto_correct_subtask_files(
+                subtask, missing_files, project_dir, spec_dir
+            )
+            if not still_missing:
+                return {"success": True, "missing_files": [], "invalid_paths": []}
+            missing_files = still_missing
+
         return {
             "success": False,
             "error": f"Planned files do not exist: {', '.join(missing_files)}",
@@ -685,7 +1072,10 @@ async def run_autonomous_agent(
 
             # Validate that all files_to_modify exist before attempting execution
             # This prevents infinite retry loops when implementation plan references non-existent files
-            validation_result = validate_subtask_files(next_subtask, project_dir)
+            # Pass spec_dir to enable auto-correction of wrong paths
+            validation_result = validate_subtask_files(
+                next_subtask, project_dir, spec_dir
+            )
             if not validation_result["success"]:
                 # File validation failed - record error and skip session
                 error_msg = validation_result["error"]
@@ -719,6 +1109,11 @@ async def run_autonomous_agent(
                         subtask_id,
                         f"File validation failed after {attempt_count} attempts: {error_msg}",
                     )
+                    emit_phase(
+                        ExecutionPhase.FAILED,
+                        f"Subtask {subtask_id} stuck: file validation failed",
+                        subtask=subtask_id,
+                    )
                     print_status(
                         f"Subtask {subtask_id} marked as STUCK after {attempt_count} failed validation attempts",
                         "error",
@@ -812,8 +1207,28 @@ async def run_autonomous_agent(
         if is_planning_phase and status != "error":
             valid, errors = _validate_and_fix_implementation_plan()
             if valid:
-                plan_validated = True
-                planning_retry_context = None
+                # Fix 5: Validate file paths in the newly created plan
+                path_issues = _validate_plan_file_paths(spec_dir, project_dir)
+                if (
+                    path_issues
+                    and planning_validation_failures < max_planning_validation_retries
+                ):
+                    planning_validation_failures += 1
+                    planning_retry_context = path_issues
+                    print_status(
+                        "Plan has invalid file paths - retrying planner",
+                        "warning",
+                    )
+                    first_run = True
+                    status = "continue"
+                else:
+                    if path_issues:
+                        logger.warning(
+                            f"Plan has uncorrectable file paths after "
+                            f"{planning_validation_failures} retries - proceeding anyway"
+                        )
+                    plan_validated = True
+                    planning_retry_context = None
             else:
                 planning_validation_failures += 1
                 if planning_validation_failures >= max_planning_validation_retries:
@@ -871,6 +1286,11 @@ async def run_autonomous_agent(
                 recovery_manager.mark_subtask_stuck(
                     subtask_id, f"Failed after {attempt_count} attempts"
                 )
+                emit_phase(
+                    ExecutionPhase.FAILED,
+                    f"Subtask {subtask_id} stuck after {attempt_count} attempts",
+                    subtask=subtask_id,
+                )
                 print()
                 print_status(
                     f"Subtask {subtask_id} marked as STUCK after {attempt_count} attempts",
@@ -1230,4 +1650,24 @@ async def run_autonomous_agent(
     if completed == total:
         status_manager.update(state=BuildState.COMPLETE)
     else:
-        status_manager.update(state=BuildState.PAUSED)
+        # Check if all remaining subtasks are stuck — if so, this is an error, not a pause
+        all_remaining_stuck = False
+        if stuck_subtasks:
+            stuck_ids = {s["subtask_id"] for s in stuck_subtasks}
+            plan = load_implementation_plan(spec_dir)
+            if plan:
+                all_remaining_stuck = True
+                for phase in plan.get("phases", []):
+                    for s in phase.get("subtasks", []):
+                        if s.get("status") != "completed":
+                            if s.get("id") not in stuck_ids:
+                                all_remaining_stuck = False
+                                break
+                    if not all_remaining_stuck:
+                        break
+
+        if all_remaining_stuck and stuck_subtasks:
+            emit_phase(ExecutionPhase.FAILED, "All remaining subtasks are stuck")
+            status_manager.update(state=BuildState.ERROR)
+        else:
+            status_manager.update(state=BuildState.PAUSED)

apps/backend/agents/session.py

@@ -14,6 +14,7 @@ from core.error_utils import (
     is_authentication_error,
     is_rate_limit_error,
     is_tool_concurrency_error,
+    safe_receive_messages,
 )
 from core.file_utils import write_json_atomic
 from debug import debug, debug_detailed, debug_error, debug_section, debug_success
@@ -490,7 +491,7 @@ async def run_agent_session(
         # Collect response text and show tool use
         response_text = ""
         debug("session", "Starting to receive response stream...")
-        async for msg in client.receive_response():
+        async for msg in safe_receive_messages(client, caller="session"):
             msg_type = type(msg).__name__
             message_count += 1
             debug_detailed(

apps/backend/cli/qa_commands.py

@@ -101,8 +101,12 @@ def handle_qa_command(
             print("\n✅ Build already approved by QA.")
         else:
             completed, total = count_subtasks(spec_dir)
-            print(f"\n❌ Build not complete ({completed}/{total} subtasks).")
-            print("Complete all subtasks before running QA validation.")
+            print(
+                f"\n❌ Build not ready for QA ({completed}/{total} subtasks completed)."
+            )
+            print(
+                "All subtasks must reach a terminal state (completed, failed, or stuck) before running QA."
+            )
         return
 
     if has_human_feedback:

apps/backend/core/client.py

@@ -29,6 +29,89 @@ from core.platform import (
 
 logger = logging.getLogger(__name__)
 
+# =============================================================================
+# SDK Message Parser Patch
+# =============================================================================
+# The Claude Agent SDK's message_parser raises MessageParseError for unknown
+# message types (e.g., "rate_limit_event"). Since parse_message runs inside an
+# async generator, the exception kills the entire agent session stream.
+# Patch to log a warning and return a SystemMessage instead of crashing.
+# This is needed until the SDK natively handles all CLI message types.
+
+
+def _patch_sdk_message_parser() -> None:
+    """Patch the SDK's parse_message to handle unknown message types gracefully.
+
+    The Claude CLI may emit message types that the installed SDK version doesn't
+    recognize (e.g., rate_limit_event, usage_event). Without this patch, any
+    unrecognized type raises MessageParseError inside the SDK's async generator,
+    which terminates the entire response stream and kills the agent session.
+
+    The patch converts unknown types into SystemMessage objects with a
+    'unknown_<type>' subtype, which all message consumers silently skip.
+    """
+    try:
+        import claude_agent_sdk._internal.message_parser as _parser
+        from claude_agent_sdk._errors import MessageParseError
+        from claude_agent_sdk.types import SystemMessage
+
+        _original_parse = _parser.parse_message
+
+        def _patched_parse(data):
+            try:
+                return _original_parse(data)
+            except MessageParseError as e:
+                msg = str(e)
+                if "Unknown message type" in msg:
+                    msg_type = (
+                        data.get("type", "unknown")
+                        if isinstance(data, dict)
+                        else "unknown"
+                    )
+                    # Rate limit events deserve a visible warning; others just debug-level
+                    if "rate_limit" in msg_type:
+                        retry_after = (
+                            data.get("retry_after")
+                            or data.get("data", {}).get("retry_after")
+                            if isinstance(data, dict)
+                            else None
+                        )
+                        retry_info = (
+                            f" (retry_after={retry_after}s)" if retry_after else ""
+                        )
+                        logger.warning(
+                            f"Rate limit event received from CLI{retry_info} — "
+                            f"the SDK will handle backoff automatically"
+                        )
+                    else:
+                        logger.debug(
+                            f"SDK received unhandled message type '{msg_type}', skipping"
+                        )
+                    return SystemMessage(
+                        subtype=f"unknown_{msg_type}",
+                        data=data if isinstance(data, dict) else {},
+                    )
+                raise
+
+        _parser.parse_message = _patched_parse
+    except Exception as e:
+        logger.warning(f"Failed to patch SDK message parser: {e}")
+
+
+_patch_sdk_message_parser()
+
+# =============================================================================
+# Windows System Prompt Limits
+# =============================================================================
+# Windows CreateProcessW has a 32,768 character limit for the entire command line.
+# When CLAUDE.md is very large and passed as --system-prompt, the command can exceed
+# this limit, causing ERROR_FILE_NOT_FOUND. We cap CLAUDE.md content to stay safe.
+# 20,000 chars leaves ~12KB headroom for CLI overhead (model, tools, MCP config, etc.)
+WINDOWS_MAX_SYSTEM_PROMPT_CHARS = 20000
+WINDOWS_TRUNCATION_MESSAGE = (
+    "\n\n[... CLAUDE.md truncated due to Windows command-line length limit ...]"
+)
+
 # =============================================================================
 # Project Index Cache
 # =============================================================================
@@ -821,8 +904,31 @@ def create_client(
     if should_use_claude_md():
         claude_md_content = load_claude_md(project_dir)
         if claude_md_content:
+            # On Windows, the SDK passes system_prompt as a --system-prompt CLI argument.
+            # Windows CreateProcessW has a 32,768 character limit for the entire command line.
+            # When CLAUDE.md is very large, the command can exceed this limit, causing Windows
+            # to return ERROR_FILE_NOT_FOUND which the SDK misreports as "Claude Code not found".
+            # Cap CLAUDE.md content to keep total command line under the limit. (#1661)
+            was_truncated = False
+            if is_windows():
+                max_claude_md_chars = (
+                    WINDOWS_MAX_SYSTEM_PROMPT_CHARS
+                    - len(base_prompt)
+                    - len(WINDOWS_TRUNCATION_MESSAGE)
+                    - len("\n\n# Project Instructions (from CLAUDE.md)\n\n")
+                )
+                if len(claude_md_content) > max_claude_md_chars > 0:
+                    claude_md_content = (
+                        claude_md_content[:max_claude_md_chars]
+                        + WINDOWS_TRUNCATION_MESSAGE
+                    )
+                    print(
+                        "   - CLAUDE.md: truncated (exceeded Windows command-line limit)"
+                    )
+                    was_truncated = True
             base_prompt = f"{base_prompt}\n\n# Project Instructions (from CLAUDE.md)\n\n{claude_md_content}"
-            print("   - CLAUDE.md: included in system prompt")
+            if not was_truncated:
+                print("   - CLAUDE.md: included in system prompt")
         else:
             print("   - CLAUDE.md: not found in project root")
     else:

apps/backend/core/error_utils.py

@@ -6,7 +6,17 @@ Common error detection and classification functions used across
 agent sessions, QA, and other modules.
 """
 
+from __future__ import annotations
+
+import logging
 import re
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from claude_agent_sdk.types import Message
+
+logger = logging.getLogger(__name__)
 
 
 def is_tool_concurrency_error(error: Exception) -> bool:
@@ -118,3 +128,61 @@ def is_authentication_error(error: Exception) -> bool:
             "please login again",
         ]
     )
+
+
+async def safe_receive_messages(
+    client,
+    *,
+    caller: str = "agent",
+) -> AsyncIterator[Message]:
+    """Iterate over SDK messages with resilience against unexpected errors.
+
+    The SDK's ``receive_response()`` async generator can terminate early if:
+    1. An unhandled message type slips past the monkey-patch (e.g., SDK upgrade
+       removes the patch surface).
+    2. A transient parse error corrupts a single message in the stream.
+    3. An unexpected ``StopAsyncIteration`` or runtime error occurs mid-stream.
+
+    This wrapper catches per-message errors, logs them, and continues yielding
+    subsequent messages so the agent session can complete its work.
+
+    It also detects rate-limit events (surfaced as ``SystemMessage`` with
+    subtype ``unknown_rate_limit_event``) and logs a user-visible warning.
+
+    Args:
+        client: A ``ClaudeSDKClient`` instance (must be inside ``async with``).
+        caller: Label for log messages (e.g., "session", "agent_runner").
+
+    Yields:
+        Parsed ``Message`` objects from the SDK response stream.
+    """
+    try:
+        async for msg in client.receive_response():
+            # Detect rate-limit events surfaced by the monkey-patch
+            msg_type = type(msg).__name__
+            if msg_type == "SystemMessage":
+                subtype = getattr(msg, "subtype", "")
+                if subtype.startswith("unknown_"):
+                    original_type = subtype[len("unknown_") :]
+                    if "rate_limit" in original_type:
+                        data = getattr(msg, "data", {})
+                        retry_after = data.get("retry_after") or data.get(
+                            "data", {}
+                        ).get("retry_after")
+                        retry_info = (
+                            f" (retry in {retry_after}s)" if retry_after else ""
+                        )
+                        logger.warning(f"[{caller}] Rate limit event{retry_info}")
+                    else:
+                        logger.debug(
+                            f"[{caller}] Skipping unknown SDK message type: {original_type}"
+                        )
+                    continue
+            yield msg
+    except GeneratorExit:
+        return
+    except Exception as e:
+        # If the generator itself raises (e.g., transport error), log and stop
+        # gracefully so callers can process whatever was collected so far.
+        logger.error(f"[{caller}] SDK response stream terminated unexpectedly: {e}")
+        return

apps/backend/core/progress.py

@@ -115,6 +115,65 @@ def is_build_complete(spec_dir: Path) -> bool:
     return total > 0 and completed == total
 
 
+def _load_stuck_subtask_ids(spec_dir: Path) -> set[str]:
+    """Load IDs of subtasks marked as stuck from attempt_history.json."""
+    stuck_subtask_ids: set[str] = set()
+    attempt_history_file = spec_dir / "memory" / "attempt_history.json"
+    if attempt_history_file.exists():
+        try:
+            with open(attempt_history_file, encoding="utf-8") as f:
+                attempt_history = json.load(f)
+            for entry in attempt_history.get("stuck_subtasks", []):
+                if "subtask_id" in entry:
+                    stuck_subtask_ids.add(entry["subtask_id"])
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+            # Corrupted attempt history is non-fatal; skip stuck-subtask filtering
+            pass
+    return stuck_subtask_ids
+
+
+def is_build_ready_for_qa(spec_dir: Path) -> bool:
+    """
+    Check if the build is ready for QA validation.
+
+    Unlike is_build_complete() which requires all subtasks to be "completed",
+    this function considers the build ready when all subtasks have reached
+    a terminal state: completed, failed, or stuck (exhausted retries in attempt_history.json).
+
+    Args:
+        spec_dir: Directory containing implementation_plan.json
+
+    Returns:
+        True if all subtasks are in a terminal state, False otherwise
+    """
+    plan_file = spec_dir / "implementation_plan.json"
+    if not plan_file.exists():
+        return False
+
+    stuck_subtask_ids = _load_stuck_subtask_ids(spec_dir)
+
+    try:
+        with open(plan_file, encoding="utf-8") as f:
+            plan = json.load(f)
+
+        total = 0
+        terminal = 0
+
+        for phase in plan.get("phases", []):
+            for subtask in phase.get("subtasks", []):
+                total += 1
+                status = subtask.get("status", "pending")
+                subtask_id = subtask.get("id")
+
+                if status in ("completed", "failed") or subtask_id in stuck_subtask_ids:
+                    terminal += 1
+
+        return total > 0 and terminal == total
+
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return False
+
+
 def get_progress_percentage(spec_dir: Path) -> float:
     """
     Get the progress as a percentage.
@@ -420,22 +479,7 @@ def get_next_subtask(spec_dir: Path) -> dict | None:
     if not plan_file.exists():
         return None
 
-    # Load stuck subtasks from recovery manager's attempt history
-    stuck_subtask_ids = set()
-    attempt_history_file = spec_dir / "memory" / "attempt_history.json"
-    if attempt_history_file.exists():
-        try:
-            with open(attempt_history_file, encoding="utf-8") as f:
-                attempt_history = json.load(f)
-            # Collect IDs of subtasks marked as stuck
-            stuck_subtask_ids = {
-                entry["subtask_id"]
-                for entry in attempt_history.get("stuck_subtasks", [])
-                if "subtask_id" in entry
-            }
-        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
-            # If we can't read the file, continue without stuck checking
-            pass
+    stuck_subtask_ids = _load_stuck_subtask_ids(spec_dir)
 
     try:
         with open(plan_file, encoding="utf-8") as f:
@@ -454,8 +498,11 @@ def get_next_subtask(spec_dir: Path) -> dict | None:
                 str(phase_id_raw) if phase_id_raw is not None else f"unknown:{i}"
             )
             subtasks = phase.get("subtasks", phase.get("chunks", []))
+            # Stuck subtasks count as "resolved" for phase dependency purposes.
+            # This prevents one stuck subtask from blocking all downstream phases.
             phase_complete[phase_id_key] = all(
-                s.get("status") == "completed" for s in subtasks
+                s.get("status") == "completed" or s.get("id") in stuck_subtask_ids
+                for s in subtasks
             )
 
         # Find next available subtask

apps/backend/core/workspace/dependency_strategy.py

@@ -9,9 +9,10 @@ Each dependency ecosystem has different constraints:
 - **node_modules**: Safe to symlink. Node's resolution algorithm follows symlinks
   correctly, and the directory is self-contained.
 
-- **venv / .venv**: Must be recreated. Python's ``pyvenv.cfg`` discovery walks the
-  real directory hierarchy without resolving symlinks (CPython bug #106045), so a
-  symlinked venv resolves paths relative to the *target*, not the worktree.
+- **venv / .venv**: Symlinked for fast worktree creation. CPython bug #106045
+  (pyvenv.cfg symlink resolution) does not affect typical usage (running scripts,
+  imports, pip). A health check after symlinking verifies usability; if it fails,
+  the caller falls back to recreating the venv.
 
 - **vendor (PHP)**: Safe to symlink. Composer's autoloader uses ``__DIR__``-relative
   paths that resolve correctly through symlinks.
@@ -42,9 +43,9 @@ from .models import DependencyShareConfig, DependencyStrategy
 DEFAULT_STRATEGY_MAP: dict[str, DependencyStrategy] = {
     # JavaScript / Node.js — symlink is safe and fast
     "node_modules": DependencyStrategy.SYMLINK,
-    # Python — venvs MUST be recreated (pyvenv.cfg symlink bug)
-    "venv": DependencyStrategy.RECREATE,
-    ".venv": DependencyStrategy.RECREATE,
+    # Python — symlink for fast worktree creation (health check + fallback to recreate)
+    "venv": DependencyStrategy.SYMLINK,
+    ".venv": DependencyStrategy.SYMLINK,
     # PHP — Composer vendor dir is safe to symlink
     "vendor_php": DependencyStrategy.SYMLINK,
     # Ruby — Bundler vendor/bundle is safe to symlink

apps/backend/core/workspace/models.py

@@ -278,12 +278,11 @@ class SpecNumberLock:
 class DependencyStrategy(Enum):
     """Strategy for sharing dependency directories across worktrees.
 
-    SYMLINK is fast but unsafe for certain ecosystems. Notably, Python venv
-    breaks when symlinked because CPython's pyvenv.cfg discovery walks the
-    real directory hierarchy without resolving symlinks first
-    (CPython bug #106045). This means a symlinked venv resolves its home
-    path relative to the symlink target's parent, not the worktree, causing
-    import failures and broken interpreters.
+    SYMLINK is fast and now safe for Python venvs with runtime health checks.
+    A post-symlink health check validates the venv is usable, automatically
+    falling back to RECREATE if the symlink is broken. This works around
+    CPython's pyvenv.cfg discovery issue (CPython bug #106045) while maintaining
+    fast worktree creation in the common case where symlinking succeeds.
     """
 
     SYMLINK = "symlink"  # Create a symlink to the source (fast, works for node_modules)

apps/backend/core/workspace/setup.py

@@ -50,6 +50,10 @@ _git_hook_check_done = False
 
 MODULE = "workspace.setup"
 
+# Marker file written inside a recreated venv to indicate setup completed successfully.
+# If the marker is absent, the venv is treated as incomplete and will be rebuilt.
+VENV_SETUP_COMPLETE_MARKER = ".setup_complete"
+
 
 def choose_workspace(
     project_dir: Path,
@@ -624,9 +628,52 @@ def setup_worktree_dependencies(
             results[strategy_name] = []
 
         try:
-            performed = True
+            performed = False
             if config.strategy == DependencyStrategy.SYMLINK:
                 performed = _apply_symlink_strategy(project_dir, worktree_path, config)
+                # For venvs, verify the symlink is usable — fall back to recreate
+                # Run health check whenever a venv symlink exists (not just on creation)
+                if config.dep_type in ("venv", ".venv"):
+                    venv_path = worktree_path / config.source_rel_path
+                    # Check if venv exists (symlinked or otherwise)
+                    if venv_path.exists() or venv_path.is_symlink():
+                        if is_windows():
+                            python_bin = str(venv_path / "Scripts" / "python.exe")
+                        else:
+                            python_bin = str(venv_path / "bin" / "python")
+                        try:
+                            subprocess.run(
+                                [python_bin, "-c", "import sys; print(sys.prefix)"],
+                                capture_output=True,
+                                text=True,
+                                timeout=10,
+                                check=True,
+                            )
+                            debug(
+                                MODULE,
+                                f"Symlinked venv health check passed: {config.source_rel_path}",
+                            )
+                        except (subprocess.SubprocessError, OSError):
+                            debug_warning(
+                                MODULE,
+                                f"Symlinked venv health check failed, falling back to recreate: {config.source_rel_path}",
+                            )
+                            # Remove the broken symlink and recreate
+                            try:
+                                if venv_path.is_symlink():
+                                    venv_path.unlink()
+                                elif venv_path.exists():
+                                    shutil.rmtree(venv_path, ignore_errors=True)
+                            except OSError:
+                                pass  # Best-effort removal; recreate strategy handles existing paths
+                            performed = _apply_recreate_strategy(
+                                project_dir, worktree_path, config
+                            )
+                            # Update strategy name to reflect fallback
+                            if performed:
+                                strategy_name = "recreate"
+                                # Ensure the key exists for the fallback strategy
+                                results.setdefault(strategy_name, [])
             elif config.strategy == DependencyStrategy.RECREATE:
                 performed = _apply_recreate_strategy(project_dir, worktree_path, config)
             elif config.strategy == DependencyStrategy.COPY:
@@ -707,6 +754,54 @@ def _apply_symlink_strategy(
         return False
 
 
+def _popen_with_cleanup(
+    cmd: list[str],
+    timeout: int,
+    label: str,
+) -> tuple[int, str, str]:
+    """Run a command via Popen with proper process cleanup on timeout.
+
+    On timeout: terminate → wait(10) → kill → wait(5) to ensure file locks
+    are released before any cleanup (e.g. shutil.rmtree).
+
+    Returns (returncode, stdout, stderr).
+    Raises subprocess.TimeoutExpired if the command exceeds the given timeout (after cleanup is attempted).
+    """
+    proc = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    try:
+        stdout, stderr = proc.communicate(timeout=timeout)
+        return proc.returncode, stdout, stderr
+    except subprocess.TimeoutExpired:
+        debug_warning(MODULE, f"{label} timed out, terminating process")
+        proc.terminate()
+        try:
+            proc.communicate(timeout=10)
+        except subprocess.TimeoutExpired:
+            debug_warning(MODULE, f"{label} did not terminate, killing process")
+            proc.kill()
+            try:
+                proc.communicate(timeout=5)
+            except subprocess.TimeoutExpired:
+                # Final cleanup attempt if kill() also hangs
+                debug_warning(MODULE, f"{label} could not be stopped even after kill()")
+        raise
+    finally:
+        # Ensure pipes are closed and process is reaped to avoid zombie processes
+        if proc.stdout:
+            proc.stdout.close()
+        if proc.stderr:
+            proc.stderr.close()
+        try:
+            proc.wait(timeout=0.1)
+        except subprocess.TimeoutExpired:
+            pass  # Process still running, already logged warning above
+
+
 def _apply_recreate_strategy(
     project_dir: Path,
     worktree_path: Path,
@@ -717,10 +812,25 @@ def _apply_recreate_strategy(
     Returns True if the venv was successfully created, False if skipped or failed.
     """
     venv_path = worktree_path / config.source_rel_path
+    marker_path = venv_path / VENV_SETUP_COMPLETE_MARKER
 
-    if venv_path.exists():
-        debug(MODULE, f"Skipping recreate {config.source_rel_path} - already exists")
-        return False
+    # Check for broken symlinks that exists() would miss
+    if venv_path.is_symlink() and not venv_path.exists():
+        debug(MODULE, f"Removing broken symlink at {config.source_rel_path}")
+        try:
+            venv_path.unlink()
+        except OSError:
+            pass  # Best-effort removal
+    elif venv_path.exists():
+        if marker_path.exists():
+            debug(
+                MODULE,
+                f"Skipping recreate {config.source_rel_path} - already complete (marker present)",
+            )
+            return False
+        # Venv exists but marker is missing — incomplete, remove and rebuild
+        debug(MODULE, f"Removing incomplete venv {config.source_rel_path} (no marker)")
+        shutil.rmtree(venv_path, ignore_errors=True)
 
     # Detect Python executable from the source venv or fall back to sys.executable
     source_venv = project_dir / config.source_rel_path
@@ -737,29 +847,34 @@ def _apply_recreate_strategy(
     # Create the venv
     try:
         debug(MODULE, f"Creating venv at {venv_path}")
-        result = subprocess.run(
+        returncode, _, stderr = _popen_with_cleanup(
             [python_exec, "-m", "venv", str(venv_path)],
-            capture_output=True,
-            text=True,
             timeout=120,
+            label=f"venv creation ({config.source_rel_path})",
         )
-        if result.returncode != 0:
-            debug_warning(MODULE, f"venv creation failed: {result.stderr}")
+        if returncode != 0:
+            debug_warning(MODULE, f"venv creation failed: {stderr}")
             print_status(
                 f"Warning: Could not create venv at {config.source_rel_path}",
                 "warning",
             )
-            # Clean up partial venv so retries aren't blocked
             if venv_path.exists():
                 shutil.rmtree(venv_path, ignore_errors=True)
             return False
     except subprocess.TimeoutExpired:
-        debug_warning(MODULE, f"venv creation timed out for {config.source_rel_path}")
         print_status(
             f"Warning: venv creation timed out for {config.source_rel_path}",
             "warning",
         )
-        # Clean up partial venv so retries aren't blocked
+        if venv_path.exists():
+            shutil.rmtree(venv_path, ignore_errors=True)
+        return False
+    except OSError as e:
+        debug_warning(MODULE, f"venv creation failed: {e}")
+        print_status(
+            f"Warning: Could not create venv at {config.source_rel_path}",
+            "warning",
+        )
         if venv_path.exists():
             shutil.rmtree(venv_path, ignore_errors=True)
         return False
@@ -800,46 +915,45 @@ def _apply_recreate_strategy(
             if install_cmd:
                 try:
                     debug(MODULE, f"Installing deps from {req_file}")
-                    pip_result = subprocess.run(
+                    returncode, _, stderr = _popen_with_cleanup(
                         install_cmd,
-                        capture_output=True,
-                        text=True,
-                        timeout=120,
+                        timeout=300,
+                        label=f"pip install ({req_file})",
                     )
-                    if pip_result.returncode != 0:
+                    if returncode != 0:
                         debug_warning(
                             MODULE,
-                            f"pip install failed (exit {pip_result.returncode}): "
-                            f"{pip_result.stderr}",
+                            f"pip install failed (exit {returncode}): {stderr}",
                         )
                         print_status(
                             f"Warning: Dependency install failed for {req_file}",
                             "warning",
                         )
-                        # Clean up broken venv so retries aren't blocked
                         if venv_path.exists():
                             shutil.rmtree(venv_path, ignore_errors=True)
                         return False
                 except subprocess.TimeoutExpired:
-                    debug_warning(
-                        MODULE,
-                        f"pip install timed out for {req_file}",
-                    )
                     print_status(
                         f"Warning: Dependency install timed out for {req_file}",
                         "warning",
                     )
-                    # Clean up broken venv so retries aren't blocked
                     if venv_path.exists():
                         shutil.rmtree(venv_path, ignore_errors=True)
                     return False
                 except OSError as e:
                     debug_warning(MODULE, f"pip install failed: {e}")
-                    # Clean up broken venv so retries aren't blocked
                     if venv_path.exists():
                         shutil.rmtree(venv_path, ignore_errors=True)
                     return False
 
+    # Write completion marker so future runs know this venv is complete
+    try:
+        marker_path.touch()
+    except OSError as e:
+        debug_warning(
+            MODULE, f"Failed to write completion marker at {marker_path}: {e}"
+        )
+
     debug(MODULE, f"Recreated venv at {config.source_rel_path}")
     return True
 

apps/backend/core/worktree.py

@@ -1211,6 +1211,9 @@ class WorktreeManager:
             )
 
         target = target_branch or self.base_branch
+        # Strip remote prefix (e.g., "origin/feat/x" → "feat/x") since gh expects branch names only
+        if target.startswith("origin/"):
+            target = target[len("origin/") :]
         pr_title = title or f"auto-claude: {spec_name}"
 
         # Try AI-powered PR body from project's PR template, fall back to spec summary
@@ -1381,6 +1384,9 @@ class WorktreeManager:
             )
 
         target = target_branch or self.base_branch
+        # Strip remote prefix (e.g., "origin/feat/x" → "feat/x") since glab expects branch names only
+        if target.startswith("origin/"):
+            target = target[len("origin/") :]
         mr_title = title or f"auto-claude: {spec_name}"
 
         # Get MR body from spec.md if available

apps/backend/integrations/graphiti/config.py

@@ -635,10 +635,20 @@ def get_graphiti_status() -> dict:
     try:
         # Attempt to import the main graphiti_memory module
         import graphiti_core  # noqa: F401
-        from graphiti_core.driver.falkordb_driver import FalkorDriver  # noqa: F401
 
-        # If we got here, packages are importable
-        status["available"] = True  # pragma: no cover
+        # Try LadybugDB first (preferred for Python 3.12+), fall back to kuzu
+        try:
+            import real_ladybug  # noqa: F401
+        except ImportError:
+            try:
+                import kuzu  # noqa: F401
+            except ImportError:
+                status["available"] = False
+                status["reason"] = (
+                    "Graph database backend not installed (need real_ladybug or kuzu)"
+                )
+                return status
+        status["available"] = True
     except ImportError as e:
         status["available"] = False
         status["reason"] = f"Graphiti packages not installed: {e}"

apps/backend/integrations/graphiti/tests/conftest.py

@@ -81,16 +81,16 @@ def mock_graphiti_core():
 
 
 @pytest.fixture
-def mock_falkor_driver():
-    """Mock graphiti_core.driver.falkordb_driver.FalkorDriver.
+def mock_kuzu_driver():
+    """Mock graphiti_core.driver.kuzu_driver.KuzuDriver.
 
-    Prevents actual FalkorDB connections during tests.
+    Prevents actual LadybugDB/kuzu connections during tests.
 
     Yields:
         tuple: (mock_driver_class, mock_driver_instance)
     """
     with patch(
-        "integrations.graphiti.queries_pkg.graphiti.graphiti_core.driver.falkordb_driver.FalkorDriver"
+        "integrations.graphiti.queries_pkg.graphiti.graphiti_core.driver.kuzu_driver.KuzuDriver"
     ) as mock_driver:
         mock_instance = MagicMock()
         mock_driver.return_value = mock_instance

apps/backend/integrations/graphiti/tests/test_config.py

@@ -15,7 +15,7 @@ Tests cover:
 import json
 import os
 from pathlib import Path
-from unittest.mock import patch
+from unittest.mock import MagicMock, patch
 
 import pytest
 from integrations.graphiti.config import (
@@ -1054,20 +1054,48 @@ class TestModuleLevelFunctions:
         assert "OPENAI_API_KEY" in status["errors"][0]
 
     def test_get_graphiti_status_invalid_config_sets_reason(self, clean_env):
-        """Test get_graphiti_status sets reason when config is invalid.
+        """Test get_graphiti_status with validation errors (embedder misconfigured).
 
-        This tests lines 628-629 where the reason is set from validation errors.
+        When packages are installed but embedder config has errors, available should
+        still be True (embedder is optional - keyword search fallback exists).
+        Validation errors are reported in the errors list for informational purposes.
         """
         os.environ["GRAPHITI_ENABLED"] = "true"
         os.environ["GRAPHITI_EMBEDDER_PROVIDER"] = "voyage"
 
-        status = get_graphiti_status()
+        # Mock imports to ensure test is independent of environment
+        with patch.dict(
+            "sys.modules",
+            {"graphiti_core": MagicMock(), "real_ladybug": MagicMock()},
+        ):
+            status = get_graphiti_status()
+
+        assert status["enabled"] is True
+        # available depends on whether mocked packages are resolved correctly;
+        # sys.modules patching should make imports succeed, but guard against
+        # environment quirks (consistent with test_get_graphiti_status_enabled)
+        assert status["available"] is True
+        assert len(status["errors"]) > 0
+        assert "VOYAGE_API_KEY" in status["errors"][0]
+
+    def test_get_graphiti_status_no_graph_backend(self, clean_env):
+        """Test get_graphiti_status when graphiti_core exists but no graph DB backend.
+
+        This tests the error path in config.py lines 645-650 where graphiti_core
+        imports successfully but neither real_ladybug nor kuzu is available.
+        """
+        os.environ["GRAPHITI_ENABLED"] = "true"
+
+        # Mock graphiti_core as present, but ensure real_ladybug and kuzu are absent
+        with patch.dict(
+            "sys.modules",
+            {"graphiti_core": MagicMock(), "real_ladybug": None, "kuzu": None},
+        ):
+            status = get_graphiti_status()
 
         assert status["enabled"] is True
         assert status["available"] is False
-        # When config is invalid, reason should be set from errors
-        assert status["reason"] != ""
-        assert len(status["errors"]) > 0
+        assert "real_ladybug or kuzu" in status["reason"]
 
     @pytest.mark.slow
     def test_get_graphiti_status_with_graphiti_installed(self, clean_env):
@@ -1089,9 +1117,9 @@ class TestModuleLevelFunctions:
         assert "reason" in status
         assert "errors" in status
 
-        # Note: Line 641 (status["available"] = True) requires falkordb to be installed.
-        # Since falkordb is not installed in the test environment, that line is marked
-        # with pragma: no cover. The except clause (lines 642-644) is tested here.
+        # Note: Line 644 (status["available"] = True) requires LadybugDB/kuzu to be installed.
+        # Since LadybugDB/kuzu may not be installed in all test environments, that line
+        # may be marked with pragma: no cover. The except clause is tested here.
 
     def test_get_available_providers_empty(self, clean_env):
         """Test get_available_providers with no credentials."""

apps/backend/integrations/graphiti/tests/test_memory.py

@@ -264,7 +264,7 @@ class TestTestGraphitiConnection:
 
             # Mock graphiti_core imports to succeed
             mock_graphiti = MagicMock()
-            mock_falkordb_driver = MagicMock()
+            mock_kuzu_driver = MagicMock()
 
             # Mock provider creation to raise ProviderError
             with patch("graphiti_providers.create_llm_client") as mock_create_llm:
@@ -275,7 +275,7 @@ class TestTestGraphitiConnection:
                     {
                         "graphiti_core": MagicMock(Graphiti=mock_graphiti),
                         "graphiti_core.driver": MagicMock(),
-                        "graphiti_core.driver.falkordb_driver": mock_falkordb_driver,
+                        "graphiti_core.driver.kuzu_driver": mock_kuzu_driver,
                         "graphiti_providers": MagicMock(
                             ProviderError=ProviderError,
                             create_embedder=MagicMock(),

apps/backend/integrations/graphiti/tests/test_memory_facade.py

@@ -160,7 +160,7 @@ class TestTestGraphitiConnection:
     """Tests for the test_graphiti_connection async function.
 
     Note: The function now uses embedded LadybugDB via patched KuzuDriver
-    instead of remote FalkorDB with host/port credentials.
+    instead of remote database with host/port credentials.
     """
 
     @pytest.mark.asyncio

apps/backend/progress.py

@@ -14,6 +14,7 @@ from core.progress import (
     get_plan_summary,
     get_progress_percentage,
     is_build_complete,
+    is_build_ready_for_qa,
     print_build_complete_banner,
     print_paused_banner,
     print_progress_summary,
@@ -29,6 +30,7 @@ __all__ = [
     "get_plan_summary",
     "get_progress_percentage",
     "is_build_complete",
+    "is_build_ready_for_qa",
     "print_build_complete_banner",
     "print_paused_banner",
     "print_progress_summary",

apps/backend/prompts/spec_writer.md

@@ -24,7 +24,7 @@ You MUST create `spec.md` with ALL required sections (see template below).
 ## PHASE 0: LOAD ALL CONTEXT (MANDATORY)
 
 ```bash
-# Read all input files
+# Read all input files (some may not exist for greenfield/empty projects)
 cat project_index.json
 cat requirements.json
 cat context.json
@@ -35,6 +35,12 @@ Extract from these files:
 - **From requirements.json**: Task description, workflow type, services, acceptance criteria
 - **From context.json**: Files to modify, files to reference, patterns
 
+**IMPORTANT**: If any input file is missing, empty, or shows 0 files, this is likely a **greenfield/new project**. Adapt accordingly:
+- Skip sections that reference existing code (e.g., "Files to Modify", "Patterns to Follow")
+- Instead, focus on files to CREATE and the initial project structure
+- Define the tech stack, dependencies, and setup instructions from scratch
+- Use industry best practices as patterns rather than referencing existing code
+
 ---
 
 ## PHASE 1: ANALYZE CONTEXT

apps/backend/qa/criteria.py

@@ -8,7 +8,7 @@ Manages acceptance criteria validation and status tracking.
 import json
 from pathlib import Path
 
-from progress import is_build_complete
+from progress import is_build_ready_for_qa
 
 # =============================================================================
 # IMPLEMENTATION PLAN I/O
@@ -95,10 +95,10 @@ def should_run_qa(spec_dir: Path) -> bool:
     Determine if QA validation should run.
 
     QA should run when:
-    - All subtasks are completed
+    - All subtasks have reached a terminal state (completed, failed, or stuck)
     - QA has not yet approved
     """
-    if not is_build_complete(spec_dir):
+    if not is_build_ready_for_qa(spec_dir):
         return False
 
     if is_qa_approved(spec_dir):

apps/backend/qa/fixer.py

@@ -15,7 +15,11 @@ from pathlib import Path
 from agents.base import sanitize_error_message
 from agents.memory_manager import get_graphiti_context, save_session_memory
 from claude_agent_sdk import ClaudeSDKClient
-from core.error_utils import is_rate_limit_error, is_tool_concurrency_error
+from core.error_utils import (
+    is_rate_limit_error,
+    is_tool_concurrency_error,
+    safe_receive_messages,
+)
 from debug import debug, debug_detailed, debug_error, debug_section, debug_success
 from security.tool_input_validator import get_safe_tool_input
 from task_logger import (
@@ -141,7 +145,7 @@ async def run_qa_fixer_session(
 
         response_text = ""
         debug("qa_fixer", "Starting to receive response stream...")
-        async for msg in client.receive_response():
+        async for msg in safe_receive_messages(client, caller="qa_fixer"):
             msg_type = type(msg).__name__
             message_count += 1
             debug_detailed(

apps/backend/qa/loop.py

@@ -28,7 +28,7 @@ from phase_config import (
     get_phase_model_betas,
 )
 from phase_event import ExecutionPhase, emit_phase
-from progress import count_subtasks, is_build_complete
+from progress import count_subtasks, is_build_ready_for_qa
 from security.constants import PROJECT_DIR_ENV_VAR
 from task_logger import (
     LogPhase,
@@ -114,14 +114,25 @@ async def run_qa_validation_loop(
     # Initialize task logger for the validation phase
     task_logger = get_task_logger(spec_dir)
 
-    # Verify build is complete
-    if not is_build_complete(spec_dir):
-        debug_warning("qa_loop", "Build is not complete, cannot run QA")
-        print("\n❌ Build is not complete. Cannot run QA validation.")
-        completed, total = count_subtasks(spec_dir)
-        debug("qa_loop", "Build progress", completed=completed, total=total)
-        print(f"   Progress: {completed}/{total} subtasks completed")
-        return False
+    # Check if there's pending human feedback that needs to be processed
+    fix_request_file = spec_dir / "QA_FIX_REQUEST.md"
+    has_human_feedback = fix_request_file.exists()
+
+    # Human feedback takes priority — if the user explicitly asked to proceed,
+    # skip the build completeness gate entirely
+    if not has_human_feedback:
+        # Verify build is ready for QA (all subtasks in terminal state)
+        if not is_build_ready_for_qa(spec_dir):
+            debug_warning(
+                "qa_loop", "Build is not ready for QA - subtasks still in progress"
+            )
+            print("\n❌ Build is not ready for QA validation.")
+            completed, total = count_subtasks(spec_dir)
+            debug("qa_loop", "Build progress", completed=completed, total=total)
+            print(
+                f"   Progress: {completed}/{total} subtasks in terminal state (completed/failed/stuck)"
+            )
+            return False
 
     # Emit phase event at start of QA validation (before any early returns)
     emit_phase(ExecutionPhase.QA_REVIEW, "Starting QA validation")
@@ -136,10 +147,6 @@ async def run_qa_validation_loop(
         f"[Fast Mode] {'ENABLED' if fast_mode else 'disabled'} for QA validation",
     )
 
-    # Check if there's pending human feedback that needs to be processed
-    fix_request_file = spec_dir / "QA_FIX_REQUEST.md"
-    has_human_feedback = fix_request_file.exists()
-
     # Check if already approved - but if there's human feedback, we need to process it first
     if is_qa_approved(spec_dir) and not has_human_feedback:
         debug_success("qa_loop", "Build already approved by QA")

apps/backend/qa/reviewer.py

@@ -16,7 +16,11 @@ from pathlib import Path
 from agents.base import sanitize_error_message
 from agents.memory_manager import get_graphiti_context, save_session_memory
 from claude_agent_sdk import ClaudeSDKClient
-from core.error_utils import is_rate_limit_error, is_tool_concurrency_error
+from core.error_utils import (
+    is_rate_limit_error,
+    is_tool_concurrency_error,
+    safe_receive_messages,
+)
 from debug import debug, debug_detailed, debug_error, debug_section, debug_success
 from prompts_pkg import get_qa_reviewer_prompt
 from security.tool_input_validator import get_safe_tool_input
@@ -195,7 +199,7 @@ This is attempt {previous_error.get("consecutive_errors", 1) + 1}. If you fail t
 
         response_text = ""
         debug("qa_reviewer", "Starting to receive response stream...")
-        async for msg in client.receive_response():
+        async for msg in safe_receive_messages(client, caller="qa_reviewer"):
             msg_type = type(msg).__name__
             message_count += 1
             debug_detailed(

apps/backend/requirements.txt

@@ -1,7 +1,8 @@
 # Auto-Build Framework Dependencies
-# SDK 0.1.33+ required for Opus 4.6 adaptive thinking support
-# Earlier versions lacked effort parameter and thinking type configuration
-claude-agent-sdk>=0.1.33
+# SDK 0.1.39+ required for Opus 4.6 adaptive thinking support and stability fixes
+# Earlier versions lacked effort parameter, thinking type configuration,
+# and crashed on unhandled CLI message types (e.g., rate_limit_event)
+claude-agent-sdk>=0.1.39
 python-dotenv>=1.0.0
 
 # TOML parsing fallback for Python < 3.11

apps/backend/runners/insights_runner.py

@@ -8,8 +8,10 @@ about a codebase. It can also suggest tasks based on the conversation.
 
 import argparse
 import asyncio
+import base64
 import json
 import sys
+import tempfile
 from pathlib import Path
 
 # Add auto-claude to path
@@ -111,6 +113,107 @@ def load_project_context(project_dir: str) -> str:
     )
 
 
+ALLOWED_MIME_TYPES = frozenset(
+    ["image/png", "image/jpeg", "image/jpg", "image/gif", "image/webp"]
+)
+
+MAX_IMAGE_FILE_SIZE = 10 * 1024 * 1024  # 10 MB (aligned with frontend MAX_IMAGE_SIZE)
+
+
+def load_images_from_manifest(manifest_path: str) -> list[dict]:
+    """Load images from a manifest JSON file.
+
+    The manifest contains an array of objects with 'path' and 'mimeType' fields.
+    Each image file is read as binary and encoded to base64.
+
+    Returns a list of dicts with 'media_type' and 'data' (base64-encoded) fields.
+    """
+    images = []
+    tmp_dir = Path(tempfile.gettempdir()).resolve()
+
+    try:
+        with open(manifest_path, encoding="utf-8") as f:
+            manifest = json.load(f)
+
+        for entry in manifest:
+            image_path = entry.get("path")
+            mime_type = entry.get("mimeType", "image/png")
+
+            if not image_path:
+                debug_error(
+                    "insights_runner",
+                    "Image entry missing path field",
+                )
+                continue
+
+            # Validate path is within temp directory before checking existence
+            try:
+                resolved = Path(image_path).resolve()
+                if not resolved.is_relative_to(tmp_dir):
+                    debug_error(
+                        "insights_runner",
+                        f"Image path outside temp directory, skipping: {image_path}",
+                    )
+                    continue
+            except (ValueError, OSError):
+                debug_error(
+                    "insights_runner",
+                    f"Invalid image path, skipping: {image_path}",
+                )
+                continue
+
+            if not resolved.exists():
+                debug_error(
+                    "insights_runner",
+                    f"Image file not found: {image_path}",
+                )
+                continue
+
+            # Validate MIME type against allowlist
+            if mime_type not in ALLOWED_MIME_TYPES:
+                debug_error(
+                    "insights_runner",
+                    f"Invalid MIME type '{mime_type}', skipping: {image_path}",
+                )
+                continue
+
+            # Validate file size
+            file_size = resolved.stat().st_size
+            if file_size > MAX_IMAGE_FILE_SIZE:
+                debug_error(
+                    "insights_runner",
+                    f"Image too large ({file_size} bytes), skipping: {image_path}",
+                )
+                continue
+
+            try:
+                with open(resolved, "rb") as img_f:
+                    image_data = base64.b64encode(img_f.read()).decode("utf-8")
+                images.append(
+                    {
+                        "media_type": mime_type,
+                        "data": image_data,
+                    }
+                )
+                debug(
+                    "insights_runner",
+                    "Loaded image",
+                    path=image_path,
+                    mime_type=mime_type,
+                    size_bytes=file_size,
+                )
+            except Exception as e:
+                debug_error(
+                    "insights_runner",
+                    f"Failed to read image {image_path}: {e}",
+                )
+
+    except (json.JSONDecodeError, OSError) as e:
+        debug_error("insights_runner", f"Failed to load images manifest: {e}")
+
+    return images
+
+
 def build_system_prompt(project_dir: str) -> str:
     """Build the system prompt for the insights agent."""
     context = load_project_context(project_dir)
@@ -143,11 +246,12 @@ async def run_with_sdk(
     history: list,
     model: str = "sonnet",  # Shorthand - resolved via API Profile if configured
     thinking_level: str = "medium",
+    images: list[dict] | None = None,
 ) -> None:
     """Run the chat using Claude SDK with streaming."""
     if not SDK_AVAILABLE:
         print("Claude SDK not available, falling back to simple mode", file=sys.stderr)
-        run_simple(project_dir, message, history)
+        run_simple(project_dir, message, history, images)
         return
 
     if not get_auth_token():
@@ -155,7 +259,7 @@ async def run_with_sdk(
             "No authentication token found, falling back to simple mode",
             file=sys.stderr,
         )
-        run_simple(project_dir, message, history)
+        run_simple(project_dir, message, history, images)
         return
 
     # Ensure SDK can find the token
@@ -205,8 +309,24 @@ Current question: {message}"""
 
         # Use async context manager pattern
         async with client:
-            # Send the query
-            await client.query(full_prompt)
+            # Build the query - images are stored for reference but SDK doesn't support multi-modal input yet
+            if images:
+                debug(
+                    "insights_runner",
+                    "Images attached but SDK does not support multi-modal input",
+                    image_count=len(images),
+                )
+
+                # TODO: When the SDK adds support for multi-modal content blocks, update this.
+                image_note = f"\n\n[Note: The user attached {len(images)} image(s), but the current SDK version does not support multi-modal input. Please ask the user to describe the image content instead.]"
+                print(
+                    "Warning: Image attachments cannot be sent to the model in SDK mode. Sending text-only query.",
+                    file=sys.stderr,
+                )
+                await client.query(full_prompt + image_note)
+            else:
+                # Send the query as plain text
+                await client.query(full_prompt)
 
             # Stream the response
             response_text = ""
@@ -280,13 +400,21 @@ Current question: {message}"""
         import traceback
 
         traceback.print_exc(file=sys.stderr)
-        run_simple(project_dir, message, history)
+        run_simple(project_dir, message, history, images)
 
 
-def run_simple(project_dir: str, message: str, history: list) -> None:
+def run_simple(
+    project_dir: str, message: str, history: list, images: list[dict] | None = None
+) -> None:
     """Simple fallback mode without SDK - uses subprocess to call claude CLI."""
     import subprocess
 
+    if images:
+        print(
+            "Warning: Image attachments are not supported in simple mode and will be skipped.",
+            file=sys.stderr,
+        )
+
     system_prompt = build_system_prompt(project_dir)
 
     # Build conversation context
@@ -355,6 +483,10 @@ def main():
         default="medium",
         help="Thinking level for extended reasoning (low, medium, high)",
     )
+    parser.add_argument(
+        "--images-file",
+        help="Path to JSON manifest file listing image file paths and MIME types",
+    )
     args = parser.parse_args()
 
     # Validate and sanitize thinking level (handles legacy values like 'ultrathink')
@@ -398,9 +530,25 @@ def main():
         debug_error("insights_runner", f"Failed to load history: {e}")
         history = []
 
+    # Load images from manifest file if provided
+    images = None
+    if args.images_file:
+        debug("insights_runner", "Loading images from manifest", file=args.images_file)
+        images = load_images_from_manifest(args.images_file)
+        if images:
+            debug(
+                "insights_runner",
+                "Loaded images for multi-modal query",
+                image_count=len(images),
+            )
+        else:
+            debug("insights_runner", "No valid images loaded from manifest")
+
     # Run the async SDK function
     debug("insights_runner", "Running SDK query")
-    asyncio.run(run_with_sdk(project_dir, user_message, history, model, thinking_level))
+    asyncio.run(
+        run_with_sdk(project_dir, user_message, history, model, thinking_level, images)
+    )
     debug_success("insights_runner", "Query completed")
 
 

apps/backend/runners/roadmap/competitor_analyzer.py

@@ -31,6 +31,7 @@ class CompetitorAnalyzer:
         self.refresh = refresh
         self.agent_executor = agent_executor
         self.analysis_file = output_dir / "competitor_analysis.json"
+        self.manual_competitors_file = output_dir / "manual_competitors.json"
         self.discovery_file = output_dir / "roadmap_discovery.json"
         self.project_index_file = output_dir / "project_index.json"
 
@@ -42,7 +43,10 @@ class CompetitorAnalyzer:
         """
         if not enabled:
             print_status("Competitor analysis not enabled, skipping", "info")
+            manual_competitors = self._get_manual_competitors()
             self._create_disabled_analysis_file()
+            if manual_competitors:
+                self._merge_manual_competitors(manual_competitors)
             return RoadmapPhaseResult(
                 "competitor_analysis", True, [str(self.analysis_file)], [], 0
             )
@@ -53,6 +57,9 @@ class CompetitorAnalyzer:
                 "competitor_analysis", True, [str(self.analysis_file)], [], 0
             )
 
+        # Preserve manual competitors before any path that overwrites the file
+        manual_competitors = self._get_manual_competitors()
+
         if not self.discovery_file.exists():
             print_status(
                 "Discovery file not found, skipping competitor analysis", "warning"
@@ -60,6 +67,8 @@ class CompetitorAnalyzer:
             self._create_error_analysis_file(
                 "Discovery file not found - cannot analyze competitors without project context"
             )
+            if manual_competitors:
+                self._merge_manual_competitors(manual_competitors)
             return RoadmapPhaseResult(
                 "competitor_analysis",
                 True,
@@ -84,6 +93,8 @@ class CompetitorAnalyzer:
             if success and self.analysis_file.exists():
                 validation_result = self._validate_analysis()
                 if validation_result is not None:
+                    if manual_competitors:
+                        self._merge_manual_competitors(manual_competitors)
                     return validation_result
                 errors.append(f"Attempt {attempt + 1}: Validation failed")
             else:
@@ -100,12 +111,82 @@ class CompetitorAnalyzer:
             print(f"  {muted('Error:')} {err}")
 
         self._create_error_analysis_file("Analysis failed after retries", errors)
+        if manual_competitors:
+            self._merge_manual_competitors(manual_competitors)
 
         # Return success=True for graceful degradation (don't block roadmap generation)
         return RoadmapPhaseResult(
             "competitor_analysis", True, [str(self.analysis_file)], errors, MAX_RETRIES
         )
 
+    def _get_manual_competitors(self) -> list[dict]:
+        """Extract manually-added competitors from the dedicated manual file and analysis file.
+
+        Reads from manual_competitors.json (primary, never overwritten by agent) and
+        falls back to competitor_analysis.json. Deduplicates by competitor ID.
+        Returns a list of competitor dicts where source == 'manual'.
+        """
+        competitors_by_id: dict[str, dict] = {}
+
+        # Primary source: dedicated manual competitors file (never overwritten by agent)
+        if self.manual_competitors_file.exists():
+            try:
+                with open(self.manual_competitors_file, encoding="utf-8") as f:
+                    data = json.load(f)
+                for c in data.get("competitors", []):
+                    if isinstance(c, dict) and c.get("id"):
+                        competitors_by_id[c["id"]] = c
+            except (json.JSONDecodeError, OSError) as e:
+                print_status(
+                    f"Warning: could not read manual competitors file: {e}", "warning"
+                )
+
+        # Fallback: also check analysis file for manual competitors
+        if self.analysis_file.exists():
+            try:
+                with open(self.analysis_file, encoding="utf-8") as f:
+                    data = json.load(f)
+                for c in data.get("competitors", []):
+                    if (
+                        isinstance(c, dict)
+                        and c.get("source") == "manual"
+                        and c.get("id")
+                        and c["id"] not in competitors_by_id
+                    ):
+                        competitors_by_id[c["id"]] = c
+            except (json.JSONDecodeError, OSError) as e:
+                print_status(
+                    f"Warning: could not read manual competitors from analysis: {e}",
+                    "warning",
+                )
+
+        return list(competitors_by_id.values())
+
+    def _merge_manual_competitors(self, manual_competitors: list[dict]) -> None:
+        """Merge manual competitors back into the newly-generated analysis file.
+
+        Appends manual competitors that don't already exist (by ID) in the file.
+        """
+        if not manual_competitors:
+            return
+
+        try:
+            with open(self.analysis_file, encoding="utf-8") as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, OSError) as e:
+            print_status(f"Warning: failed to merge manual competitors: {e}", "warning")
+            return
+
+        existing_ids = {
+            c.get("id") for c in data.get("competitors", []) if isinstance(c, dict)
+        }
+
+        for competitor in manual_competitors:
+            if competitor.get("id") not in existing_ids:
+                data.setdefault("competitors", []).append(competitor)
+
+        write_json_atomic(self.analysis_file, data, indent=2)
+
     def _build_context(self) -> str:
         """Build context string for the competitor analysis agent."""
         return f"""
@@ -140,8 +221,11 @@ Output your findings to competitor_analysis.json.
                     "competitor_analysis", True, [str(self.analysis_file)], [], 0
                 )
 
-        except json.JSONDecodeError:
-            pass
+        except json.JSONDecodeError as e:
+            print_status(
+                f"Warning: competitor analysis file is not valid JSON: {e}",
+                "warning",
+            )
 
         return None
 

apps/backend/runners/roadmap/project_index.json

@@ -2,11 +2,6 @@
   "project_root": "/Users/andremikalsen/Documents/Coding/autonomous-coding",
   "project_type": "single",
   "services": {},
-  "infrastructure": {
-    "docker_compose": "docker-compose.yml",
-    "docker_services": [
-      "falkordb"
-    ]
-  },
+  "infrastructure": {},
   "conventions": {}
 }

apps/backend/runners/spec_runner.py

@@ -136,7 +136,7 @@ Examples:
   python spec_runner.py --task "Update text" --complexity simple
 
   # Complex integration (auto-detected)
-  python spec_runner.py --task "Add Graphiti memory integration with FalkorDB"
+  python spec_runner.py --task "Add Graphiti memory integration with LadybugDB"
 
   # Interactive mode
   python spec_runner.py --interactive

apps/backend/services/recovery.py

@@ -21,6 +21,8 @@ from datetime import datetime, timedelta, timezone
 from enum import Enum
 from pathlib import Path
 
+from core.file_utils import write_json_atomic
+
 # Recovery manager configuration
 ATTEMPT_WINDOW_SECONDS = 7200  # Only count attempts within last 2 hours
 MAX_ATTEMPT_HISTORY_PER_SUBTASK = 50  # Cap stored attempts per subtask
@@ -514,6 +516,36 @@ class RecoveryManager:
 
         self._save_attempt_history(history)
 
+        # Also update the subtask status in implementation_plan.json
+        # so that other callers (like is_build_ready_for_qa) see accurate status
+        try:
+            plan_file = self.spec_dir / "implementation_plan.json"
+            if plan_file.exists():
+                with open(plan_file, encoding="utf-8") as f:
+                    plan = json.load(f)
+
+                updated = False
+                for phase in plan.get("phases", []):
+                    for subtask in phase.get("subtasks", []):
+                        if subtask.get("id") == subtask_id:
+                            subtask["status"] = "failed"
+                            stuck_note = f"Marked as stuck: {reason}"
+                            existing = subtask.get("actual_output", "")
+                            subtask["actual_output"] = (
+                                f"{stuck_note}\n{existing}" if existing else stuck_note
+                            )
+                            updated = True
+                            break
+                    if updated:
+                        break
+
+                if updated:
+                    write_json_atomic(plan_file, plan, indent=2)
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError) as e:
+            logger.warning(
+                f"Failed to update implementation_plan.json for stuck subtask {subtask_id}: {e}"
+            )
+
     def get_stuck_subtasks(self) -> list[dict]:
         """
         Get all subtasks marked as stuck.

apps/backend/spec/phases/spec_phases.py

@@ -6,18 +6,54 @@ Phases for spec document creation and quality assurance.
 """
 
 import json
-from typing import TYPE_CHECKING
+from pathlib import Path
 
 from .. import validator, writer
+from ..discovery import get_project_index_stats
 from .models import MAX_RETRIES, PhaseResult
 
-if TYPE_CHECKING:
-    pass
+
+def _is_greenfield_project(spec_dir: Path) -> bool:
+    """Check if the project is empty/greenfield (0 discovered files)."""
+    stats = get_project_index_stats(spec_dir)
+    if not stats:
+        return False  # Can't determine - don't assume greenfield
+    return stats.get("file_count", 0) == 0
+
+
+def _greenfield_context() -> str:
+    """Return additional context for greenfield/empty projects."""
+    return """
+**GREENFIELD PROJECT**: This is an empty or new project with no existing code.
+There are no existing files to reference or modify. You are creating everything from scratch.
+
+Adapt your approach:
+- Do NOT reference existing files, patterns, or code structures
+- Focus on what needs to be CREATED, not modified
+- Define the initial project structure, files, and directories
+- Specify the tech stack, frameworks, and dependencies to install
+- Provide setup instructions for the new project
+- For "Files to Modify" and "Files to Reference" sections, list files to CREATE instead
+- For "Patterns to Follow", describe industry best practices rather than existing code
+"""
 
 
 class SpecPhaseMixin:
     """Mixin for spec writing and critique phase methods."""
 
+    def _check_and_log_greenfield(self) -> bool:
+        """Check if the project is greenfield and log if so.
+
+        Returns:
+            True if the project is greenfield (no existing files).
+        """
+        is_greenfield = _is_greenfield_project(self.spec_dir)
+        if is_greenfield:
+            self.ui.print_status(
+                "Greenfield project detected - adapting spec for new project", "info"
+            )
+        return is_greenfield
+
     async def phase_quick_spec(self) -> PhaseResult:
         """Quick spec for simple tasks - combines context and spec in one step."""
         spec_file = self.spec_dir / "spec.md"
@@ -29,6 +65,8 @@ class SpecPhaseMixin:
                 "quick_spec", True, [str(spec_file), str(plan_file)], [], 0
             )
 
+        is_greenfield = self._check_and_log_greenfield()
+
         errors = []
         for attempt in range(MAX_RETRIES):
             self.ui.print_status(
@@ -42,7 +80,7 @@ class SpecPhaseMixin:
 
 This is a SIMPLE task. Create a minimal spec and implementation plan directly.
 No research or extensive analysis needed.
-
+{_greenfield_context() if is_greenfield else ""}
 Create:
 1. A concise spec.md with just the essential sections
 2. A simple implementation_plan.json with 1-2 subtasks
@@ -80,6 +118,9 @@ Create:
                 "spec.md exists but has issues, regenerating...", "warning"
             )
 
+        is_greenfield = self._check_and_log_greenfield()
+        greenfield_ctx = _greenfield_context() if is_greenfield else ""
+
         errors = []
         for attempt in range(MAX_RETRIES):
             self.ui.print_status(
@@ -88,6 +129,7 @@ Create:
 
             success, output = await self.run_agent_fn(
                 "spec_writer.md",
+                additional_context=greenfield_ctx,
                 phase_name="spec_writing",
             )
 

apps/backend/spec/pipeline/agent_runner.py

@@ -12,6 +12,7 @@ from ui.capabilities import configure_safe_encoding
 
 configure_safe_encoding()
 
+from core.error_utils import safe_receive_messages
 from debug import debug, debug_detailed, debug_error, debug_section, debug_success
 from security.tool_input_validator import get_safe_tool_input
 from task_logger import (
@@ -162,7 +163,7 @@ class AgentRunner:
 
                 response_text = ""
                 debug("agent_runner", "Starting to receive response stream...")
-                async for msg in client.receive_response():
+                async for msg in safe_receive_messages(client, caller="agent_runner"):
                     msg_type = type(msg).__name__
                     message_count += 1
                     debug_detailed(

apps/backend/spec/pipeline/models.py

@@ -203,19 +203,19 @@ def generate_spec_name(task_description: str) -> str:
     return "-".join(name_parts) if name_parts else "spec"
 
 
-def rename_spec_dir_from_requirements(spec_dir: Path) -> bool:
+def rename_spec_dir_from_requirements(spec_dir: Path) -> Path:
     """Rename spec directory based on requirements.json task description.
 
     Args:
         spec_dir: The current spec directory
 
     Returns:
-        Tuple of (success, new_spec_dir). If success is False, new_spec_dir is the original.
+        The new spec directory path (or the original if no rename was needed/possible).
     """
     requirements_file = spec_dir / "requirements.json"
 
     if not requirements_file.exists():
-        return False
+        return spec_dir
 
     try:
         with open(requirements_file, encoding="utf-8") as f:
@@ -223,7 +223,7 @@ def rename_spec_dir_from_requirements(spec_dir: Path) -> bool:
 
         task_desc = req.get("task_description", "")
         if not task_desc:
-            return False
+            return spec_dir
 
         # Generate new name
         new_name = generate_spec_name(task_desc)
@@ -240,11 +240,11 @@ def rename_spec_dir_from_requirements(spec_dir: Path) -> bool:
 
         # Don't rename if it's already a good name (not "pending")
         if "pending" not in current_name:
-            return True
+            return spec_dir
 
         # Don't rename if target already exists
         if new_spec_dir.exists():
-            return True
+            return spec_dir
 
         # Rename the directory
         shutil.move(str(spec_dir), str(new_spec_dir))
@@ -253,11 +253,11 @@ def rename_spec_dir_from_requirements(spec_dir: Path) -> bool:
         update_task_logger_path(new_spec_dir)
 
         print_status(f"Spec folder: {highlight(new_dir_name)}", "success")
-        return True
+        return new_spec_dir
 
     except (json.JSONDecodeError, OSError) as e:
         print_status(f"Could not rename spec folder: {e}", "warning")
-        return False
+        return spec_dir
 
 
 # Phase display configuration

apps/backend/spec/pipeline/orchestrator.py

@@ -6,6 +6,7 @@ Main orchestration logic for spec creation with dynamic complexity adaptation.
 """
 
 import json
+import types
 from collections.abc import Callable
 from pathlib import Path
 
@@ -18,6 +19,7 @@ from review import run_review_checkpoint
 from task_logger import (
     LogEntryType,
     LogPhase,
+    TaskLogger,
     get_task_logger,
 )
 from ui import (
@@ -238,6 +240,47 @@ class SpecOrchestrator:
         task_logger.start_phase(LogPhase.PLANNING, "Starting spec creation process")
         TaskEventEmitter.from_spec_dir(self.spec_dir).emit("PLANNING_STARTED")
 
+        # Track whether we've already ended the planning phase (to avoid double-end)
+        self._planning_phase_ended = False
+
+        try:
+            return await self._run_phases(interactive, auto_approve, task_logger, ui)
+        except Exception as e:
+            # Emit PLANNING_FAILED so the frontend XState machine transitions to error state
+            # instead of leaving the task stuck in "planning" forever
+            try:
+                task_emitter = TaskEventEmitter.from_spec_dir(self.spec_dir)
+                task_emitter.emit(
+                    "PLANNING_FAILED",
+                    {"error": str(e), "recoverable": True},
+                )
+            except Exception:
+                pass  # Don't mask the original error
+            if not self._planning_phase_ended:
+                self._planning_phase_ended = True
+                try:
+                    task_logger.end_phase(
+                        LogPhase.PLANNING,
+                        success=False,
+                        message=f"Spec creation crashed: {e}",
+                    )
+                except Exception:
+                    pass  # Best effort - don't mask the original error when logging fails
+            raise
+
+    async def _run_phases(
+        self,
+        interactive: bool,
+        auto_approve: bool,
+        task_logger: TaskLogger,
+        ui: types.ModuleType,
+    ) -> bool:
+        """Internal method that runs all spec creation phases.
+
+        Separated from run() so that run() can wrap this in a try/except
+        to emit PLANNING_FAILED on unhandled exceptions.
+        """
+
         print(
             box(
                 f"Spec Directory: {self.spec_dir}\n"
@@ -291,9 +334,11 @@ class SpecOrchestrator:
         results.append(result)
         if not result.success:
             print_status("Discovery failed", "error")
+            self._planning_phase_ended = True
             task_logger.end_phase(
                 LogPhase.PLANNING, success=False, message="Discovery failed"
             )
+            self._emit_planning_failed("Discovery phase failed")
             return False
         # Store summary for subsequent phases (compaction)
         await self._store_phase_summary("discovery")
@@ -305,17 +350,26 @@ class SpecOrchestrator:
         results.append(result)
         if not result.success:
             print_status("Requirements gathering failed", "error")
+            self._planning_phase_ended = True
             task_logger.end_phase(
                 LogPhase.PLANNING,
                 success=False,
                 message="Requirements gathering failed",
             )
+            self._emit_planning_failed("Requirements gathering failed")
             return False
         # Store summary for subsequent phases (compaction)
         await self._store_phase_summary("requirements")
 
         # Rename spec folder with better name from requirements
-        rename_spec_dir_from_requirements(self.spec_dir)
+        # IMPORTANT: Update self.spec_dir after rename so subsequent phases use the correct path
+        new_spec_dir = rename_spec_dir_from_requirements(self.spec_dir)
+        if new_spec_dir != self.spec_dir:
+            self.spec_dir = new_spec_dir
+            self.validator = SpecValidator(self.spec_dir)
+            # Update phase executor to use the renamed directory
+            phase_executor.spec_dir = self.spec_dir
+            phase_executor.spec_validator = self.validator
 
         # Update task description from requirements
         req = requirements.load_requirements(self.spec_dir)
@@ -335,9 +389,11 @@ class SpecOrchestrator:
         results.append(result)
         if not result.success:
             print_status("Complexity assessment failed", "error")
+            self._planning_phase_ended = True
             task_logger.end_phase(
                 LogPhase.PLANNING, success=False, message="Complexity assessment failed"
             )
+            self._emit_planning_failed("Complexity assessment failed")
             return False
 
         # Map of all available phases
@@ -396,17 +452,22 @@ class SpecOrchestrator:
                     f"Phase '{phase_name}' failed: {'; '.join(result.errors)}",
                     LogEntryType.ERROR,
                 )
+                self._planning_phase_ended = True
                 task_logger.end_phase(
                     LogPhase.PLANNING,
                     success=False,
                     message=f"Phase {phase_name} failed",
                 )
+                self._emit_planning_failed(
+                    f"Phase '{phase_name}' failed: {'; '.join(result.errors)}"
+                )
                 return False
 
         # Summary
         self._print_completion_summary(results, phases_executed)
 
         # End planning phase successfully
+        self._planning_phase_ended = True
         task_logger.end_phase(
             LogPhase.PLANNING, success=True, message="Spec creation complete"
         )
@@ -638,6 +699,25 @@ class SpecOrchestrator:
             )
         )
 
+    def _emit_planning_failed(self, error: str) -> None:
+        """Emit PLANNING_FAILED event so the frontend transitions to error state.
+
+        Without this, the task stays stuck in 'planning' / 'in_progress' forever
+        when spec creation fails, because the XState machine never receives a
+        terminal event.
+
+        Args:
+            error: Human-readable error description
+        """
+        try:
+            task_emitter = TaskEventEmitter.from_spec_dir(self.spec_dir)
+            task_emitter.emit(
+                "PLANNING_FAILED",
+                {"error": error, "recoverable": True},
+            )
+        except Exception:
+            pass  # Best effort - don't mask the original failure
+
     def _run_review_checkpoint(self, auto_approve: bool) -> bool:
         """Run the human review checkpoint.
 
@@ -661,9 +741,8 @@ class SpecOrchestrator:
                 print_status("Build will not proceed without approval.", "warning")
                 return False
 
-        except SystemExit as e:
-            if e.code != 0:
-                return False
+        except SystemExit:
+            # Review checkpoint may call sys.exit(); treat any exit as unapproved
             return False
         except KeyboardInterrupt:
             print()
@@ -696,19 +775,25 @@ class SpecOrchestrator:
         The functionality has been moved to models.rename_spec_dir_from_requirements.
 
         Returns:
-            True if successful or not needed, False on error
+            True if successful or not needed, False if prerequisites are missing
         """
-        result = rename_spec_dir_from_requirements(self.spec_dir)
-        # Update self.spec_dir if it was renamed
-        if result and self.spec_dir.name.endswith("-pending"):
-            # Find the renamed directory
-            parent = self.spec_dir.parent
-            prefix = self.spec_dir.name[:4]  # e.g., "001-"
-            for candidate in parent.iterdir():
-                if (
-                    candidate.name.startswith(prefix)
-                    and "pending" not in candidate.name
-                ):
-                    self.spec_dir = candidate
-                    break
-        return result
+        # Check prerequisites first
+        requirements_file = self.spec_dir / "requirements.json"
+        if not requirements_file.exists():
+            return False
+
+        try:
+            with open(requirements_file, encoding="utf-8") as f:
+                req = json.load(f)
+            task_desc = req.get("task_description", "")
+            if not task_desc:
+                return False
+        except (json.JSONDecodeError, OSError):
+            return False
+
+        # Attempt rename
+        new_spec_dir = rename_spec_dir_from_requirements(self.spec_dir)
+        if new_spec_dir != self.spec_dir:
+            self.spec_dir = new_spec_dir
+            self.validator = SpecValidator(self.spec_dir)
+        return True

apps/frontend/XSTATE_MIGRATION_SUMMARY.md

@@ -28,34 +28,19 @@ We encountered and fixed this bug during development as it was blocking our test
 |-------|-------------|--------|
 | Phase 1 | Create XState machine definition (task-machine.ts) | ✅ Complete |
 | Phase 2 | Create TaskStateManager singleton wrapper | ✅ Complete |
-| Phase 3 | Integrate into agent-events-handlers.ts | ⏸️ Partially done |
-| Phase 4 | Remove legacy TaskStateMachine class | ❌ Not started |
+| Phase 3 | Integrate into agent-events-handlers.ts | ✅ Complete |
+| Phase 4 | Remove legacy TaskStateMachine class | ✅ Complete |
 
-### Why We Stopped at Phase 2
+### Migration Complete
 
-The original scope was to introduce XState as the new state management approach. Full integration (Phase 3-4) requires:
-
-- Extensive refactoring of agent-events-handlers.ts to remove all legacy decision logic
-- Removing the old TaskStateMachine class entirely
-- Migration of all status persistence to go through XState
-
-We delivered Phases 1-2 to establish the foundation. The current state has both systems running in parallel with XState as primary:
-
-- **XState is primary:** When TaskStateManager returns a valid state transition, that decision is used
-- **Legacy as fallback:** The old TaskStateMachine logic only applies when XState doesn't produce a decision
-- **Safe rollback:** If XState causes issues, the legacy system is still present and can take over
-
-This dual-system approach allows:
-- Validation that XState produces correct state transitions in production
-- Safe rollback if issues arise
-- Incremental adoption path for Phase 3-4
+All four phases are now complete. The XState-based `TaskStateManager` is the sole state management system — the legacy `TaskStateMachine` class and `validateStatusTransition()` function have been fully removed. `agent-events-handlers.ts` uses the XState-based `taskStateManager` singleton exclusively.
 
 ## What Changed
 
-### Before (Old Architecture)
+### Before (Old Architecture — Now Removed)
 - Status decisions scattered across agent-events-handlers.ts, execution-handlers.ts, worktree-handlers.ts
 - `validateStatusTransition()` function with complex conditional logic
-- TaskStateMachine class that was essentially an event emitter wrapper
+- `TaskStateMachine` class that was essentially an event emitter wrapper
 - Multiple places persisting status to implementation_plan.json
 - Race conditions possible when multiple handlers tried to update status
 
@@ -118,14 +103,6 @@ The state machine responds to these events:
 | CREATE_PR | User initiates PR creation |
 | PR_CREATED | PR successfully created |
 
-## Rollback Plan
-
-If issues arise post-merge:
-
-1. **Quick rollback:** `git revert <merge-commit>`
-2. **Restore point:** Commit 3e5f004a has old code intact
-3. **Legacy persistence still works:** implementation_plan.json continues to store status
-
 ## Testing
 
 | Test Suite | Result |
@@ -163,7 +140,7 @@ If issues arise post-merge:
 - Add @stately-ai/inspect for runtime devtools
 - **Subtask state management** - Track individual subtask states within the machine using XState parallel states
 - Add more granular QA states (qa_round_1, qa_round_2, etc.)
-- Complete Phase 3-4: Full integration and removal of legacy TaskStateMachine class
+
 
 ## Visualization
 

apps/frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-claude-ui",
-  "version": "2.7.6-beta.5",
+  "version": "2.7.6",
   "type": "module",
   "description": "Desktop UI for Auto Claude autonomous coding framework",
   "homepage": "https://github.com/AndyMik90/Auto-Claude",

apps/frontend/src/__tests__/integration/subprocess-spawn.test.ts

@@ -186,7 +186,7 @@ describe('Subprocess Spawn Integration', () => {
           'Test task description'
         ]),
         expect.objectContaining({
-          cwd: AUTO_CLAUDE_SOURCE,  // Process runs from auto-claude source directory
+          cwd: TEST_PROJECT_PATH,  // Process runs from project directory to avoid cross-drive issues on Windows (#1661)
           env: expect.objectContaining({
             PYTHONUNBUFFERED: '1'
           })
@@ -218,7 +218,7 @@ describe('Subprocess Spawn Integration', () => {
           'spec-001'
         ]),
         expect.objectContaining({
-          cwd: AUTO_CLAUDE_SOURCE  // Process runs from auto-claude source directory
+          cwd: TEST_PROJECT_PATH  // Process runs from project directory to avoid cross-drive issues on Windows (#1661)
         })
       );
     }, 30000);  // Increase timeout for Windows CI (dynamic imports are slow)
@@ -248,7 +248,7 @@ describe('Subprocess Spawn Integration', () => {
           '--qa'
         ]),
         expect.objectContaining({
-          cwd: AUTO_CLAUDE_SOURCE  // Process runs from auto-claude source directory
+          cwd: TEST_PROJECT_PATH  // Process runs from project directory to avoid cross-drive issues on Windows (#1661)
         })
       );
     }, 30000);  // Increase timeout for Windows CI (dynamic imports are slow)

apps/frontend/src/main/__tests__/file-watcher.test.ts

@@ -0,0 +1,301 @@
+/**
+ * Unit tests for FileWatcher concurrency mechanisms
+ * Tests deduplication, supersession, cancellation, and unwatchAll behaviour
+ * under concurrent watch()/unwatch() call patterns.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { EventEmitter } from 'events';
+import path from 'path';
+
+// ---------------------------------------------------------------------------
+// Mock chokidar BEFORE importing FileWatcher so the module sees our mock.
+// ---------------------------------------------------------------------------
+
+// A minimal FSWatcher stub that lets us control when close() resolves.
+class MockFSWatcher extends EventEmitter {
+  close: ReturnType<typeof vi.fn>;
+  constructor(closeImpl?: () => Promise<void>) {
+    super();
+    this.close = vi.fn(closeImpl ?? (() => Promise.resolve()));
+  }
+}
+
+// Track every watcher created so tests can inspect them.
+let createdWatchers: MockFSWatcher[] = [];
+// Factory override — tests replace this to inject custom stubs.
+let watchFactory: (() => MockFSWatcher) | null = null;
+
+vi.mock('chokidar', () => ({
+  default: {
+    watch: vi.fn((_path: string, _opts: unknown) => {
+      const watcher = watchFactory ? watchFactory() : new MockFSWatcher();
+      createdWatchers.push(watcher);
+      return watcher;
+    })
+  }
+}));
+
+// Mock 'fs' so we can control existsSync / readFileSync without touching disk.
+vi.mock('fs', () => ({
+  existsSync: vi.fn(() => true),
+  readFileSync: vi.fn(() => JSON.stringify({ phases: [] }))
+}));
+
+// ---------------------------------------------------------------------------
+// Import after mocks are registered
+// ---------------------------------------------------------------------------
+import { FileWatcher } from '../file-watcher';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('FileWatcher concurrency', () => {
+  let fw: FileWatcher;
+
+  beforeEach(() => {
+    fw = new FileWatcher();
+    createdWatchers = [];
+    watchFactory = null;
+    vi.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    // Clean up any watchers that are still open.
+    await fw.unwatchAll();
+  });
+
+  // -------------------------------------------------------------------------
+  // 1. Deduplication — same taskId + same specDir
+  // -------------------------------------------------------------------------
+  describe('deduplication: second watch() with same specDir is a no-op', () => {
+    it('should only create one FSWatcher when watch() is called twice with the same specDir while the first is still in-flight', async () => {
+      const specDir = '/project/.auto-claude/specs/001-task';
+      const taskId = 'task-1';
+
+      // To create a real async gap we need an existing watcher whose close() is slow.
+      // First, set up a watcher for taskId (completes synchronously).
+      await fw.watch(taskId, specDir);
+      expect(createdWatchers).toHaveLength(1);
+
+      // Replace close() with a slow one so the next watch() call has an async gap.
+      const existingWatcher = createdWatchers[0];
+      let resolveClose!: () => void;
+      existingWatcher.close = vi.fn(
+        () => new Promise<void>((res) => { resolveClose = res; })
+      );
+
+      // Now start two concurrent watch() calls for the SAME specDir.
+      // Both will try to enter, but the second should be deduplicated.
+      const watchPromise1 = fw.watch(taskId, specDir);
+      const watchPromise2 = fw.watch(taskId, specDir);
+
+      // Resolve the close so both can proceed.
+      resolveClose();
+      await Promise.all([watchPromise1, watchPromise2]);
+
+      // Only one new FSWatcher should have been created (the second call was a no-op).
+      // createdWatchers[0] is the original; createdWatchers[1] is the new one.
+      expect(createdWatchers).toHaveLength(2);
+      expect(fw.isWatching(taskId)).toBe(true);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // 2. Supersession — same taskId, different specDir
+  // -------------------------------------------------------------------------
+  describe('supersession: watch() with different specDir replaces the in-flight call', () => {
+    it('should let the second call win when the first is awaiting close()', async () => {
+      const taskId = 'task-2';
+      const specDir1 = path.join('/project', '.auto-claude', 'specs', '001-first');
+      const specDir2 = path.join('/project', '.auto-claude', 'specs', '002-second');
+
+      // First call installs an existing watcher (simulate: the watcher for
+      // specDir1 is already set up so the second watch() needs to close it).
+      // We do this by running the first watch() to completion first.
+      await fw.watch(taskId, specDir1);
+      expect(createdWatchers).toHaveLength(1);
+
+      // Now make the close() of the first watcher slow so there's an async gap
+      // during which the second watch() can enter and supersede.
+      const existingWatcher = createdWatchers[0];
+      let resolveClose!: () => void;
+      existingWatcher.close = vi.fn(
+        () => new Promise<void>((res) => { resolveClose = res; })
+      );
+
+      // Start the second watch() — it will try to close the first watcher's
+      // FSWatcher and will be awaiting that.
+      const watch2Promise = fw.watch(taskId, specDir2);
+
+      // While the second watch() is awaiting close, start a THIRD call with
+      // yet another specDir — this supersedes the second call.
+      // Actually for the test described in the finding, we want:
+      // - First call bails, second call creates the watcher.
+      // Let's resolve the close and let watch2 finish.
+      resolveClose();
+      await watch2Promise;
+
+      // The final watcher should be for specDir2.
+      expect(fw.getWatchedSpecDir(taskId)).toBe(specDir2);
+      // Two watchers were created in total (one for each specDir).
+      expect(createdWatchers).toHaveLength(2);
+    });
+
+    it('first watch() bails when pendingWatches changes to a different specDir', async () => {
+      const taskId = 'task-super';
+      const specDir1 = path.join('/project', '.auto-claude', 'specs', 'super-first');
+      const specDir2 = path.join('/project', '.auto-claude', 'specs', 'super-second');
+
+      // Make the first watcher's close() slow so we can interleave.
+      let resolveFirstClose!: () => void;
+      watchFactory = () => {
+        const w = new MockFSWatcher(() => new Promise<void>((res) => { resolveFirstClose = res; }));
+        return w;
+      };
+
+      // Start first watch().
+      const watch1Promise = fw.watch(taskId, specDir1);
+
+      // Immediately start second watch() — before the first has resolved the
+      // slow close(). At this point specDir1 watch hasn't even created an
+      // FSWatcher yet (it's the very first call so there's no existing watcher
+      // to close), so watch1Promise may resolve synchronously up to watcher
+      // creation. Reset factory to normal for subsequent watcher creations.
+      watchFactory = null;
+
+      const watch2Promise = fw.watch(taskId, specDir2);
+
+      // Let any remaining microtasks run.
+      await Promise.resolve();
+      if (resolveFirstClose) resolveFirstClose();
+
+      await Promise.all([watch1Promise, watch2Promise]);
+
+      // The winning call (specDir2) should own the watcher.
+      expect(fw.getWatchedSpecDir(taskId)).toBe(specDir2);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // 3. Cancellation — unwatch() during in-flight watch()
+  // -------------------------------------------------------------------------
+  describe('cancellation: unwatch() during in-flight watch() prevents watcher creation', () => {
+    it('should not create a watcher when unwatch() is called before the async gap resolves', async () => {
+      const taskId = 'task-3';
+      const specDir = '/project/.auto-claude/specs/003-cancel';
+
+      // There's no pre-existing watcher, so watch() won't call close(). But it
+      // does go async (chokidar.watch is sync but we can test the cancellation
+      // flag by calling unwatch() before watch() runs).
+      // The real async gap in watch() is the existing.watcher.close() call.
+      // For this test, let's pre-install a watcher so close() is called.
+
+      // Install a slow-close watcher for taskId by manually populating the map.
+      // We can do that by running a first watch(), then replacing close().
+      await fw.watch(taskId, specDir);
+
+      // Replace the watcher's close() with a slow one.
+      const existingWatcher = createdWatchers[0];
+      let resolveExistingClose!: () => void;
+      existingWatcher.close = vi.fn(
+        () => new Promise<void>((res) => { resolveExistingClose = res; })
+      );
+
+      // Start a second watch() — it will await the slow close().
+      const specDir2 = '/project/.auto-claude/specs/003-cancel-v2';
+      const watchPromise = fw.watch(taskId, specDir2);
+
+      // While watch() is in-flight, call unwatch().
+      await fw.unwatch(taskId);
+
+      // Now resolve the slow close so watch() can continue past the await.
+      resolveExistingClose();
+      await watchPromise;
+
+      // No new watcher should have been registered.
+      expect(fw.isWatching(taskId)).toBe(false);
+      // Only one FSWatcher was ever created (the original one for specDir).
+      expect(createdWatchers).toHaveLength(1);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // 4. unwatchAll() with pending watches
+  // -------------------------------------------------------------------------
+  describe('unwatchAll() cancels all pending watches', () => {
+    it('should cancel pending watch() calls and clear pendingWatches', async () => {
+      const taskId1 = 'task-4a';
+      const taskId2 = 'task-4b';
+      const specDir1 = '/project/.auto-claude/specs/004a';
+      const specDir2 = '/project/.auto-claude/specs/004b';
+
+      // Set up slow-close scenario for taskId1 (so watch() is in-flight).
+      await fw.watch(taskId1, specDir1);
+      const watcher1 = createdWatchers[0];
+      let resolveClose1!: () => void;
+      watcher1.close = vi.fn(
+        () => new Promise<void>((res) => { resolveClose1 = res; })
+      );
+
+      // Start a new watch for taskId1 with a different specDir — this is now in-flight.
+      const newSpecDir1 = '/project/.auto-claude/specs/004a-v2';
+      const watchPromise1 = fw.watch(taskId1, newSpecDir1);
+
+      // Start a fresh watch for taskId2.
+      await fw.watch(taskId2, specDir2);
+
+      // Call unwatchAll() while watchPromise1 is still pending.
+      const unwatchAllPromise = fw.unwatchAll();
+
+      // Resolve the slow close so everything can proceed.
+      resolveClose1();
+      await Promise.all([watchPromise1, unwatchAllPromise]);
+
+      // After unwatchAll, no watchers should be active.
+      expect(fw.isWatching(taskId1)).toBe(false);
+      expect(fw.isWatching(taskId2)).toBe(false);
+
+      // pendingWatches should be cleared (we verify indirectly: a fresh
+      // watch() call for taskId1 must succeed without treating it as a duplicate).
+      const specDirFresh = path.join('/project', '.auto-claude', 'specs', '004a-fresh');
+      await fw.watch(taskId1, specDirFresh);
+      expect(fw.isWatching(taskId1)).toBe(true);
+      expect(fw.getWatchedSpecDir(taskId1)).toBe(specDirFresh);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // 5. getWatchedSpecDir() returns correct specDir
+  // -------------------------------------------------------------------------
+  describe('getWatchedSpecDir()', () => {
+    it('returns the specDir that was passed to watch()', async () => {
+      const taskId = 'task-5';
+      const specDir = path.join('/project', '.auto-claude', 'specs', '005-specdir');
+
+      await fw.watch(taskId, specDir);
+
+      expect(fw.getWatchedSpecDir(taskId)).toBe(specDir);
+    });
+
+    it('returns null when the task is not being watched', () => {
+      expect(fw.getWatchedSpecDir('unknown-task')).toBeNull();
+    });
+
+    it('returns updated specDir after re-watch with different specDir', async () => {
+      const taskId = 'task-5b';
+      const specDir1 = path.join('/project', '.auto-claude', 'specs', '005b-first');
+      const specDir2 = path.join('/project', '.auto-claude', 'specs', '005b-second');
+
+      await fw.watch(taskId, specDir1);
+      expect(fw.getWatchedSpecDir(taskId)).toBe(specDir1);
+
+      await fw.watch(taskId, specDir2);
+      expect(fw.getWatchedSpecDir(taskId)).toBe(specDir2);
+    });
+  });
+});

apps/frontend/src/main/__tests__/pr-review-state-manager.test.ts

@@ -0,0 +1,333 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { PRReviewStateManager } from '../pr-review-state-manager';
+import type { PRReviewResult, PRReviewProgress } from '../../preload/api/modules/github-api';
+
+// Mock dependencies
+const mockSafeSendToRenderer = vi.fn();
+vi.mock('../ipc-handlers/utils', () => ({
+  safeSendToRenderer: (...args: unknown[]) => mockSafeSendToRenderer(...args)
+}));
+
+function createMockGetMainWindow() {
+  return vi.fn(() => ({ id: 1 }) as unknown as Electron.BrowserWindow);
+}
+
+function createMockProgress(overrides: Partial<PRReviewProgress> = {}): PRReviewProgress {
+  return {
+    phase: 'analyzing',
+    progress: 50,
+    message: 'Analyzing files...',
+    ...overrides
+  } as PRReviewProgress;
+}
+
+function createMockResult(overrides: Partial<PRReviewResult> = {}): PRReviewResult {
+  return {
+    overallStatus: 'approved',
+    summary: 'Looks good',
+    ...overrides
+  } as PRReviewResult;
+}
+
+describe('PRReviewStateManager', () => {
+  let manager: PRReviewStateManager;
+  const projectId = 'project-1';
+  const prNumber = 42;
+
+  beforeEach(() => {
+    manager = new PRReviewStateManager(createMockGetMainWindow());
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    manager.clearAll();
+  });
+
+  describe('actor lifecycle', () => {
+    it('should create actor on first handleStartReview call', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const snapshot = manager.getState(projectId, prNumber);
+      expect(snapshot).not.toBeNull();
+    });
+
+    it('should reuse existing actor for same PR key', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const snapshot1 = manager.getState(projectId, prNumber);
+      // Calling again should not create a new actor
+      manager.handleStartReview(projectId, prNumber);
+      const snapshot2 = manager.getState(projectId, prNumber);
+      expect(snapshot1).not.toBeNull();
+      expect(snapshot2).not.toBeNull();
+    });
+
+    it('should create separate actors for different PRs', () => {
+      manager.handleStartReview(projectId, 1);
+      manager.handleStartReview(projectId, 2);
+      const snapshot1 = manager.getState(projectId, 1);
+      const snapshot2 = manager.getState(projectId, 2);
+      expect(snapshot1).not.toBeNull();
+      expect(snapshot2).not.toBeNull();
+    });
+
+    it('should start actor before events are sent', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const snapshot = manager.getState(projectId, prNumber);
+      // If actor wasn't started, getSnapshot would fail or return unexpected state
+      expect(snapshot).not.toBeNull();
+      expect(String(snapshot!.value)).toBe('reviewing');
+    });
+  });
+
+  describe('event routing', () => {
+    it('should transition to reviewing on handleStartReview', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const snapshot = manager.getState(projectId, prNumber);
+      expect(String(snapshot!.value)).toBe('reviewing');
+    });
+
+    it('should send START_FOLLOWUP_REVIEW with previousResult', () => {
+      const previousResult = createMockResult();
+      manager.handleStartFollowupReview(projectId, prNumber, previousResult);
+      const snapshot = manager.getState(projectId, prNumber);
+      expect(String(snapshot!.value)).toBe('reviewing');
+      expect(snapshot!.context.isFollowup).toBe(true);
+      expect(snapshot!.context.previousResult).toBe(previousResult);
+    });
+
+    it('should send START_REVIEW when handleStartFollowupReview has no previousResult', () => {
+      manager.handleStartFollowupReview(projectId, prNumber);
+      const snapshot = manager.getState(projectId, prNumber);
+      expect(String(snapshot!.value)).toBe('reviewing');
+      expect(snapshot!.context.isFollowup).toBe(false);
+    });
+
+    it('should update context on handleProgress', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const progress = createMockProgress();
+      manager.handleProgress(projectId, prNumber, progress);
+      const snapshot = manager.getState(projectId, prNumber);
+      expect(snapshot!.context.progress).toEqual(progress);
+    });
+
+    it('should ignore handleProgress for unknown PR', () => {
+      // Should not throw
+      manager.handleProgress(projectId, 999, createMockProgress());
+      expect(manager.getState(projectId, 999)).toBeNull();
+    });
+
+    it('should transition to completed on handleComplete', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const result = createMockResult();
+      manager.handleComplete(projectId, prNumber, result);
+      const snapshot = manager.getState(projectId, prNumber);
+      expect(String(snapshot!.value)).toBe('completed');
+      expect(snapshot!.context.result).toEqual(result);
+    });
+
+    it('should create actor for handleComplete on unknown PR (late-arriving result)', () => {
+      const result = createMockResult();
+      // No handleStartReview called — handleComplete should create the actor
+      manager.handleComplete(projectId, prNumber, result);
+      const snapshot = manager.getState(projectId, prNumber);
+      expect(snapshot).not.toBeNull();
+      expect(snapshot!.context.result).toEqual(result);
+    });
+
+    it('should send DETECT_EXTERNAL_REVIEW when overallStatus is in_progress', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const result = createMockResult({ overallStatus: 'in_progress' });
+      manager.handleComplete(projectId, prNumber, result);
+      const snapshot = manager.getState(projectId, prNumber);
+      expect(String(snapshot!.value)).toBe('externalReview');
+    });
+
+    it('should transition to error on handleError', () => {
+      manager.handleStartReview(projectId, prNumber);
+      manager.handleError(projectId, prNumber, 'Something went wrong');
+      const snapshot = manager.getState(projectId, prNumber);
+      expect(String(snapshot!.value)).toBe('error');
+      expect(snapshot!.context.error).toBe('Something went wrong');
+    });
+
+    it('should transition to error on handleCancel', () => {
+      manager.handleStartReview(projectId, prNumber);
+      manager.handleCancel(projectId, prNumber);
+      const snapshot = manager.getState(projectId, prNumber);
+      expect(String(snapshot!.value)).toBe('error');
+    });
+  });
+
+  describe('state emission', () => {
+    it('should emit state changes to renderer via safeSendToRenderer', () => {
+      manager.handleStartReview(projectId, prNumber);
+      expect(mockSafeSendToRenderer).toHaveBeenCalled();
+    });
+
+    it('should use GITHUB_PR_REVIEW_STATE_CHANGE IPC channel', () => {
+      manager.handleStartReview(projectId, prNumber);
+      expect(mockSafeSendToRenderer).toHaveBeenCalledWith(
+        expect.any(Function),
+        'github:pr:reviewStateChange',
+        expect.any(String),
+        expect.objectContaining({ state: expect.any(String) })
+      );
+    });
+
+    it('should emit PRReviewStatePayload with correct shape', () => {
+      manager.handleStartReview(projectId, prNumber);
+      // Find the call that emits 'reviewing' state
+      const reviewingCall = mockSafeSendToRenderer.mock.calls.find(
+        (call: unknown[]) => {
+          const payload = call[3] as Record<string, unknown> | undefined;
+          return payload && typeof payload === 'object' && payload.state === 'reviewing';
+        }
+      );
+      expect(reviewingCall).toBeDefined();
+      expect(reviewingCall![2]).toBe(`${projectId}:${prNumber}`);
+      const payload = reviewingCall![3] as Record<string, unknown>;
+      expect(payload).toEqual(expect.objectContaining({
+        state: 'reviewing',
+        prNumber,
+        projectId,
+        isReviewing: true,
+        startedAt: expect.any(String),
+        progress: null,
+        result: null,
+        previousResult: null,
+        error: null,
+        isExternalReview: false,
+        isFollowup: false,
+      }));
+    });
+
+    it('should use projectId:prNumber as key format', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const calls = mockSafeSendToRenderer.mock.calls;
+      const prCall = calls.find((call: unknown[]) => call[2] === `${projectId}:${prNumber}`);
+      expect(prCall).toBeDefined();
+    });
+  });
+
+  describe('deduplication', () => {
+    it('should NOT emit duplicate IPC for same state + same context', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const callCountAfterStart = mockSafeSendToRenderer.mock.calls.length;
+
+      // Sending START_REVIEW again won't transition (guard prevents it), so no new emission
+      manager.handleStartReview(projectId, prNumber);
+      expect(mockSafeSendToRenderer.mock.calls.length).toBe(callCountAfterStart);
+    });
+
+    it('should emit for same state but different context (progress update)', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const callCountAfterStart = mockSafeSendToRenderer.mock.calls.length;
+
+      manager.handleProgress(projectId, prNumber, createMockProgress({ progress: 25, message: 'Step 1' }));
+      expect(mockSafeSendToRenderer.mock.calls.length).toBeGreaterThan(callCountAfterStart);
+
+      const callCountAfterProgress1 = mockSafeSendToRenderer.mock.calls.length;
+      manager.handleProgress(projectId, prNumber, createMockProgress({ progress: 75, message: 'Step 2' }));
+      expect(mockSafeSendToRenderer.mock.calls.length).toBeGreaterThan(callCountAfterProgress1);
+    });
+
+    it('should always emit for different state transitions', () => {
+      manager.handleStartReview(projectId, prNumber);
+      const callCountAfterStart = mockSafeSendToRenderer.mock.calls.length;
+
+      manager.handleComplete(projectId, prNumber, createMockResult());
+      expect(mockSafeSendToRenderer.mock.calls.length).toBeGreaterThan(callCountAfterStart);
+    });
+  });
+
+  describe('cleanup', () => {
+    it('should stop actor and remove from map on handleClearReview', () => {
+      manager.handleStartReview(projectId, prNumber);
+      expect(manager.getState(projectId, prNumber)).not.toBeNull();
+
+      manager.handleClearReview(projectId, prNumber);
+      expect(manager.getState(projectId, prNumber)).toBeNull();
+    });
+
+    it('should emit exactly one cleared state IPC on handleClearReview (no double emission)', () => {
+      manager.handleStartReview(projectId, prNumber);
+      mockSafeSendToRenderer.mockClear();
+
+      manager.handleClearReview(projectId, prNumber);
+
+      // Should emit exactly 1 cleared state, not 2 (no double emission from
+      // sending CLEAR_REVIEW to actor subscription + manual emitClearedState)
+      expect(mockSafeSendToRenderer).toHaveBeenCalledTimes(1);
+      const payload = mockSafeSendToRenderer.mock.calls[0][3] as Record<string, unknown>;
+      expect(payload).toEqual(expect.objectContaining({ state: 'idle' }));
+    });
+
+    it('should stop ALL actors and clear maps on handleAuthChange', () => {
+      manager.handleStartReview(projectId, 1);
+      manager.handleStartReview(projectId, 2);
+
+      manager.handleAuthChange();
+
+      expect(manager.getState(projectId, 1)).toBeNull();
+      expect(manager.getState(projectId, 2)).toBeNull();
+    });
+
+    it('should emit cleared state to renderer on handleAuthChange', () => {
+      manager.handleStartReview(projectId, 1);
+      manager.handleStartReview(projectId, 2);
+      mockSafeSendToRenderer.mockClear();
+
+      manager.handleAuthChange();
+
+      // Should emit idle/null state for each PR
+      expect(mockSafeSendToRenderer).toHaveBeenCalledTimes(2);
+      for (const call of mockSafeSendToRenderer.mock.calls) {
+        const payload = call[3] as Record<string, unknown>;
+        expect(payload).toEqual(expect.objectContaining({ state: 'idle' }));
+      }
+    });
+
+    it('should stop all actors on clearAll', () => {
+      manager.handleStartReview(projectId, 1);
+      manager.handleStartReview(projectId, 2);
+
+      manager.clearAll();
+
+      expect(manager.getState(projectId, 1)).toBeNull();
+      expect(manager.getState(projectId, 2)).toBeNull();
+    });
+  });
+
+  describe('concurrent PRs', () => {
+    it('should support multiple PRs with independent actors', () => {
+      manager.handleStartReview(projectId, 1);
+      manager.handleStartReview(projectId, 2);
+
+      manager.handleComplete(projectId, 1, createMockResult());
+
+      expect(String(manager.getState(projectId, 1)!.value)).toBe('completed');
+      expect(String(manager.getState(projectId, 2)!.value)).toBe('reviewing');
+    });
+
+    it('should route events to correct actor by key', () => {
+      manager.handleStartReview(projectId, 1);
+      manager.handleStartReview(projectId, 2);
+
+      manager.handleError(projectId, 2, 'Error on PR 2');
+
+      expect(String(manager.getState(projectId, 1)!.value)).toBe('reviewing');
+      expect(String(manager.getState(projectId, 2)!.value)).toBe('error');
+      expect(manager.getState(projectId, 2)!.context.error).toBe('Error on PR 2');
+    });
+
+    it('should not affect other PRs when clearing one', () => {
+      manager.handleStartReview(projectId, 1);
+      manager.handleStartReview(projectId, 2);
+
+      manager.handleClearReview(projectId, 1);
+
+      expect(manager.getState(projectId, 1)).toBeNull();
+      expect(manager.getState(projectId, 2)).not.toBeNull();
+      expect(String(manager.getState(projectId, 2)!.value)).toBe('reviewing');
+    });
+  });
+});

apps/frontend/src/main/agent/agent-manager.ts

@@ -329,7 +329,9 @@ export class AgentManager extends EventEmitter {
     this.registerTaskWithOperationRegistry(taskId, 'spec-creation', { projectPath, taskDescription, specDir });
 
     // Note: This is spec-creation but it chains to task-execution via run.py
-    await this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'task-execution', projectId);
+    // Use projectPath as cwd instead of autoBuildSource to avoid cross-drive file access
+    // issues on Windows. The script path is absolute so Python finds its modules via sys.path[0]. (#1661)
+    await this.processManager.spawnProcess(taskId, projectPath, args, combinedEnv, 'task-execution', projectId);
   }
 
   /**
@@ -410,7 +412,10 @@ export class AgentManager extends EventEmitter {
     // Register with unified OperationRegistry for proactive swap support
     this.registerTaskWithOperationRegistry(taskId, 'task-execution', { projectPath, specId, options });
 
-    await this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'task-execution', projectId);
+    // Use projectPath as cwd instead of autoBuildSource to avoid cross-drive file access
+    // issues on Windows. The script path (runPath) is absolute so Python finds its modules
+    // via sys.path[0] which is set to the script's directory. (#1661)
+    await this.processManager.spawnProcess(taskId, projectPath, args, combinedEnv, 'task-execution', projectId);
   }
 
   /**
@@ -448,7 +453,8 @@ export class AgentManager extends EventEmitter {
 
     const args = [runPath, '--spec', specId, '--project-dir', projectPath, '--qa'];
 
-    await this.processManager.spawnProcess(taskId, autoBuildSource, args, combinedEnv, 'qa-process', projectId);
+    // Use projectPath as cwd instead of autoBuildSource to avoid cross-drive issues on Windows (#1661)
+    await this.processManager.spawnProcess(taskId, projectPath, args, combinedEnv, 'qa-process', projectId);
   }
 
   /**

apps/frontend/src/main/agent/agent-process.ts

@@ -22,10 +22,10 @@ import { pythonEnvManager, getConfiguredPythonPath } from '../python-env-manager
 import { buildMemoryEnvVars } from '../memory-env-builder';
 import { readSettingsFile } from '../settings-utils';
 import type { AppSettings } from '../../shared/types/settings';
-import { getOAuthModeClearVars } from './env-utils';
+import { getOAuthModeClearVars, normalizeEnvPathKey, mergePythonEnvPath } from './env-utils';
 import { getAugmentedEnv } from '../env-utils';
 import { getToolInfo, getClaudeCliPathForSdk } from '../cli-tool-manager';
-import { killProcessGracefully, isWindows } from '../platform';
+import { killProcessGracefully, isWindows, getPathDelimiter } from '../platform';
 import { debugLog } from '../../shared/utils/debug-logger';
 
 /**
@@ -679,7 +679,17 @@ export class AgentProcessManager {
       },
     });
 
-    // Parse Python commandto handle space-separated commands like "py -3"
+    // Merge PATH from pythonEnv with augmented PATH from env.
+    // pythonEnv may contain its own PATH (e.g., on Windows with pywin32_system32 prepended).
+    // Simply spreading pythonEnv after env would overwrite the augmented PATH (which includes
+    // npm globals, homebrew, etc.), causing "Claude code not found" on Windows (#1661).
+    // mergePythonEnvPath() normalizes PATH key casing and prepends pythonEnv-specific paths.
+    const mergedPythonEnv = { ...pythonEnv };
+    const pathSep = getPathDelimiter();
+
+    mergePythonEnvPath(env as Record<string, string | undefined>, mergedPythonEnv as Record<string, string | undefined>, pathSep);
+
+    // Parse Python command to handle space-separated commands like "py -3"
     const [pythonCommand, pythonBaseArgs] = parsePythonCommand(this.getPythonPath());
     let childProcess;
     try {
@@ -687,7 +697,7 @@ export class AgentProcessManager {
         cwd,
         env: {
           ...env, // Already includes process.env, extraEnv, profileEnv, PYTHONUNBUFFERED, PYTHONUTF8
-          ...pythonEnv, // Include Python environment (PYTHONPATH for bundled packages)
+          ...mergedPythonEnv, // Python env with merged PATH (preserves augmented PATH entries)
           ...oauthModeClearVars, // Clear stale ANTHROPIC_* vars when in OAuth mode
           ...apiProfileEnv // Include active API profile config (highest priority for ANTHROPIC_* vars)
         }

apps/frontend/src/main/agent/agent-queue.ts

@@ -10,7 +10,7 @@ import type { IdeationConfig, Idea } from '../../shared/types';
 import { AUTO_BUILD_PATHS } from '../../shared/constants';
 import { detectRateLimit, createSDKRateLimitInfo, getBestAvailableProfileEnv } from '../rate-limit-detector';
 import { getAPIProfileEnv } from '../services/profile';
-import { getOAuthModeClearVars } from './env-utils';
+import { getOAuthModeClearVars, normalizeEnvPathKey } from './env-utils';
 import { debugLog, debugError } from '../../shared/utils/debug-logger';
 import { stripAnsiCodes } from '../../shared/utils/ansi-sanitizer';
 import { parsePythonCommand } from '../python-detector';
@@ -397,6 +397,12 @@ export class AgentQueueManager {
       PYTHONUTF8: '1'
     };
 
+    // Normalize PATH key to a single uppercase 'PATH' entry.
+    // On Windows, process.env spread produces 'Path' while pythonEnv may write 'PATH',
+    // resulting in duplicate keys in the final object. Without normalization the child
+    // process inherits both keys, which can cause tool-not-found errors (#1661).
+    normalizeEnvPathKey(finalEnv as Record<string, string | undefined>);
+
     // Debug: Show OAuth token source (token values intentionally omitted for security - AC4)
     const tokenSource = profileEnv['CLAUDE_CODE_OAUTH_TOKEN']
       ? 'Electron app profile'
@@ -730,6 +736,12 @@ export class AgentQueueManager {
       PYTHONUTF8: '1'
     };
 
+    // Normalize PATH key to a single uppercase 'PATH' entry.
+    // On Windows, process.env spread produces 'Path' while pythonEnv may write 'PATH',
+    // resulting in duplicate keys in the final object. Without normalization the child
+    // process inherits both keys, which can cause tool-not-found errors (#1661).
+    normalizeEnvPathKey(finalEnv as Record<string, string | undefined>);
+
     // Debug: Show OAuth token source (token values intentionally omitted for security - AC4)
     const tokenSource = profileEnv['CLAUDE_CODE_OAUTH_TOKEN']
       ? 'Electron app profile'

apps/frontend/src/main/agent/env-utils.test.ts

@@ -4,7 +4,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { getOAuthModeClearVars } from './env-utils';
+import { getOAuthModeClearVars, normalizeEnvPathKey, mergePythonEnvPath } from './env-utils';
 
 describe('getOAuthModeClearVars', () => {
   describe('OAuth mode (no active API profile)', () => {
@@ -132,3 +132,166 @@ describe('getOAuthModeClearVars', () => {
     });
   });
 });
+
+describe('normalizeEnvPathKey', () => {
+  it('should leave an already-uppercase PATH key untouched', () => {
+    const env: Record<string, string | undefined> = { PATH: '/usr/bin:/bin', HOME: '/home/user' };
+    normalizeEnvPathKey(env);
+    expect(env).toEqual({ PATH: '/usr/bin:/bin', HOME: '/home/user' });
+  });
+
+  it('should rename a lowercase-variant "Path" key to "PATH"', () => {
+    const env: Record<string, string | undefined> = { Path: 'C:\\Windows\\system32', HOME: '/home/user' };
+    normalizeEnvPathKey(env);
+    expect(env['PATH']).toBe('C:\\Windows\\system32');
+    expect('Path' in env).toBe(false);
+  });
+
+  it('should prefer existing "PATH" and remove "Path" when both keys coexist', () => {
+    // Simulates process.env spread ('Path') after getAugmentedEnv writes ('PATH')
+    const env: Record<string, string | undefined> = {
+      Path: 'C:\\old',
+      PATH: 'C:\\Windows\\system32;C:\\augmented',
+      HOME: '/home/user'
+    };
+    normalizeEnvPathKey(env);
+    expect(env.PATH).toBe('C:\\Windows\\system32;C:\\augmented');
+    expect('Path' in env).toBe(false);
+  });
+
+  it('should remove all case-variant PATH duplicates when PATH is already present', () => {
+    const env: Record<string, string | undefined> = {
+      PATH: '/correct',
+      Path: '/old1',
+      path: '/old2'
+    };
+    normalizeEnvPathKey(env);
+    expect(env.PATH).toBe('/correct');
+    expect('Path' in env).toBe(false);
+    expect('path' in env).toBe(false);
+  });
+
+  it('should handle env with no PATH-like key gracefully', () => {
+    const env: Record<string, string | undefined> = { HOME: '/home/user', SHELL: '/bin/zsh' };
+    normalizeEnvPathKey(env);
+    expect(env).toEqual({ HOME: '/home/user', SHELL: '/bin/zsh' });
+  });
+
+  it('should return the same env object reference (mutates in place)', () => {
+    const env: Record<string, string | undefined> = { PATH: '/usr/bin' };
+    const result = normalizeEnvPathKey(env);
+    expect(result).toBe(env);
+  });
+});
+
+describe('mergePythonEnvPath - Windows PATH merge logic (#1661)', () => {
+  const SEP = ';'; // Use Windows separator for these tests
+
+  it('should prepend pythonEnv-only entries to the augmented PATH', () => {
+    const env: Record<string, string | undefined> = {
+      PATH: 'C:\\npm;C:\\homebrew'
+    };
+    const mergedPythonEnv: Record<string, string | undefined> = {
+      PATH: 'C:\\pywin32_system32;C:\\npm;C:\\homebrew'
+    };
+
+    mergePythonEnvPath(env, mergedPythonEnv, SEP);
+
+    // pywin32_system32 is unique to pythonEnv, so it should be prepended
+    expect(mergedPythonEnv.PATH).toBe('C:\\pywin32_system32;C:\\npm;C:\\homebrew');
+  });
+
+  it('should deduplicate entries that already exist in augmented PATH', () => {
+    const env: Record<string, string | undefined> = {
+      PATH: 'C:\\npm;C:\\homebrew;C:\\pywin32_system32'
+    };
+    const mergedPythonEnv: Record<string, string | undefined> = {
+      PATH: 'C:\\pywin32_system32;C:\\npm'
+    };
+
+    mergePythonEnvPath(env, mergedPythonEnv, SEP);
+
+    // All pythonEnv entries are already in env.PATH, so mergedPythonEnv.PATH should equal env.PATH
+    expect(mergedPythonEnv.PATH).toBe('C:\\npm;C:\\homebrew;C:\\pywin32_system32');
+  });
+
+  it('should normalize Windows-style "Path" key in pythonEnv to "PATH"', () => {
+    const env: Record<string, string | undefined> = {
+      PATH: 'C:\\npm;C:\\homebrew'
+    };
+    // pythonEnv uses 'Path' (Windows native casing)
+    const mergedPythonEnv: Record<string, string | undefined> = {
+      Path: 'C:\\pywin32_system32;C:\\npm'
+    };
+
+    mergePythonEnvPath(env, mergedPythonEnv, SEP);
+
+    // 'Path' should be normalized to 'PATH' and pythonEnv-specific entry prepended
+    expect('Path' in mergedPythonEnv).toBe(false);
+    expect(mergedPythonEnv.PATH).toBe('C:\\pywin32_system32;C:\\npm;C:\\homebrew');
+  });
+
+  it('should normalize Windows-style "Path" in env and deduplicate duplicates', () => {
+    // Simulates process.env spread ('Path') + getAugmentedEnv write ('PATH') leaving both
+    const env: Record<string, string | undefined> = {
+      Path: 'C:\\old',
+      PATH: 'C:\\npm;C:\\homebrew'
+    };
+    const mergedPythonEnv: Record<string, string | undefined> = {
+      PATH: 'C:\\pywin32_system32;C:\\npm'
+    };
+
+    mergePythonEnvPath(env, mergedPythonEnv, SEP);
+
+    // env 'Path' should be removed; augmented 'PATH' value preserved
+    expect('Path' in env).toBe(false);
+    expect(env.PATH).toBe('C:\\npm;C:\\homebrew');
+    // Only the unique pywin32_system32 entry prepended
+    expect(mergedPythonEnv.PATH).toBe('C:\\pywin32_system32;C:\\npm;C:\\homebrew');
+  });
+
+  it('should use env.PATH unchanged when pythonEnv has no unique entries', () => {
+    const env: Record<string, string | undefined> = {
+      PATH: 'C:\\npm;C:\\homebrew'
+    };
+    const mergedPythonEnv: Record<string, string | undefined> = {
+      PATH: 'C:\\npm;C:\\homebrew'
+    };
+
+    mergePythonEnvPath(env, mergedPythonEnv, SEP);
+
+    expect(mergedPythonEnv.PATH).toBe('C:\\npm;C:\\homebrew');
+  });
+
+  it('should work correctly with Unix colon separator', () => {
+    const unixSep = ':';
+    const env: Record<string, string | undefined> = {
+      PATH: '/usr/bin:/bin'
+    };
+    const mergedPythonEnv: Record<string, string | undefined> = {
+      PATH: '/opt/pyenv/shims:/usr/bin:/bin'
+    };
+
+    mergePythonEnvPath(env, mergedPythonEnv, unixSep);
+
+    // /opt/pyenv/shims is unique and should be prepended
+    expect(mergedPythonEnv.PATH).toBe('/opt/pyenv/shims:/usr/bin:/bin');
+  });
+
+  it('should handle missing PATH in pythonEnv gracefully (no-op)', () => {
+    const env: Record<string, string | undefined> = {
+      PATH: 'C:\\npm;C:\\homebrew'
+    };
+    // pythonEnv has no PATH at all
+    const mergedPythonEnv: Record<string, string | undefined> = {
+      PYTHONPATH: '/site-packages'
+    };
+
+    mergePythonEnvPath(env, mergedPythonEnv, SEP);
+
+    // Nothing should change
+    expect(mergedPythonEnv.PATH).toBeUndefined();
+    expect(mergedPythonEnv.PYTHONPATH).toBe('/site-packages');
+    expect(env.PATH).toBe('C:\\npm;C:\\homebrew');
+  });
+});

apps/frontend/src/main/agent/env-utils.ts

@@ -2,6 +2,88 @@
  * Utility functions for managing environment variables in agent spawning
  */
 
+/**
+ * Normalize the PATH key in an environment object to a single uppercase 'PATH' key.
+ *
+ * On Windows, process.env spreads as 'Path' (the native casing) while getAugmentedEnv()
+ * writes 'PATH'. Without normalization, both keys coexist in the object and the child
+ * process receives duplicate PATH entries, causing tool-not-found errors like #1661.
+ *
+ * Mutates the provided env object in place and returns it for convenience.
+ *
+ * @param env - Mutable environment record to normalize
+ * @returns The same env object with PATH normalized to uppercase
+ */
+export function normalizeEnvPathKey(env: Record<string, string | undefined>): Record<string, string | undefined> {
+  // If 'PATH' already exists, delete all other case-variant keys (e.g. 'Path')
+  if ('PATH' in env) {
+    for (const key of Object.keys(env)) {
+      if (key !== 'PATH' && key.toUpperCase() === 'PATH') {
+        delete env[key];
+      }
+    }
+    return env;
+  }
+
+  // No uppercase 'PATH' key - find the first case-variant and rename it
+  const pathKey = Object.keys(env).find(k => k.toUpperCase() === 'PATH');
+  if (pathKey) {
+    env['PATH'] = env[pathKey];
+    delete env[pathKey];
+    // Remove any remaining case-variant keys
+    for (const key of Object.keys(env)) {
+      if (key !== 'PATH' && key.toUpperCase() === 'PATH') {
+        delete env[key];
+      }
+    }
+  }
+
+  return env;
+}
+
+/**
+ * Merge pythonEnv PATH entries with the augmented PATH in env, deduplicating entries.
+ *
+ * pythonEnv may carry its own PATH (e.g. pywin32_system32 prepended on Windows).
+ * Simply spreading pythonEnv after env would overwrite the augmented PATH (which
+ * includes npm globals, Homebrew, etc.), causing "Claude code not found" (#1661).
+ *
+ * Strategy:
+ *  1. Normalize PATH key casing in both env and pythonEnv to uppercase 'PATH'.
+ *  2. Extract only pythonEnv PATH entries that are not already in env.PATH.
+ *  3. Prepend those unique entries to env.PATH and store the result in pythonEnv.PATH.
+ *
+ * Mutates mergedPythonEnv in place (caller should pass a shallow copy if immutability is needed).
+ *
+ * @param env - The base environment (already augmented with tool paths)
+ * @param mergedPythonEnv - Shallow copy of pythonEnv to merge PATH into
+ * @param pathSep - Platform path separator (';' on Windows, ':' elsewhere)
+ */
+export function mergePythonEnvPath(
+  env: Record<string, string | undefined>,
+  mergedPythonEnv: Record<string, string | undefined>,
+  pathSep: string
+): void {
+  // Normalize PATH key to uppercase in both objects
+  normalizeEnvPathKey(env);
+  normalizeEnvPathKey(mergedPythonEnv);
+
+  if (mergedPythonEnv['PATH'] && env['PATH']) {
+    const augmentedPathEntries = new Set(
+      (env['PATH'] as string).split(pathSep).filter(Boolean)
+    );
+    // Extract only new entries from pythonEnv.PATH that aren't already in the augmented PATH
+    const pythonPathEntries = (mergedPythonEnv['PATH'] as string)
+      .split(pathSep)
+      .filter(entry => entry && !augmentedPathEntries.has(entry));
+
+    // Prepend python-specific paths (e.g., pywin32_system32) to the augmented PATH
+    mergedPythonEnv['PATH'] = pythonPathEntries.length > 0
+      ? [...pythonPathEntries, env['PATH'] as string].join(pathSep)
+      : env['PATH'] as string;
+  }
+}
+
 /**
  * Get environment variables to clear ANTHROPIC_* vars when in OAuth mode
  *

apps/frontend/src/main/app-logger.ts

@@ -38,6 +38,18 @@ log.transports.file.fileName = 'main.log';
 // Console transport - always show warnings and errors, debug only in dev mode
 log.transports.console.level = process.env.NODE_ENV === 'development' ? 'debug' : 'warn';
 log.transports.console.format = '[{h}:{i}:{s}] [{level}] {text}';
+// Guard console transport writes so broken stdio streams do not crash the app.
+{
+  const originalConsoleWriteFn = log.transports.console.writeFn as (...args: unknown[]) => void;
+  log.transports.console.writeFn = (...args: unknown[]) => {
+    try {
+      originalConsoleWriteFn(...args);
+    } catch (error) {
+      const err = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+      safeStderrWrite(`[app-logger] console transport write failed: ${err}`);
+    }
+  };
+}
 
 // Determine if this is a beta version
 function isBetaVersion(): boolean {
@@ -204,14 +216,44 @@ export const appLog = {
   log: (...args: unknown[]) => log.info(...args),
 };
 
+/**
+ * Best-effort stderr fallback used when electron-log itself throws (e.g. EIO).
+ * Must never throw, especially inside uncaught exception handlers.
+ */
+function safeStderrWrite(message: string): void {
+  try {
+    process.stderr.write(`${message}\n`);
+  } catch {
+    // Ignore - nothing else we can safely do here.
+  }
+}
+
+/**
+ * Log an unhandled error without risking recursive crashes if logger transport fails.
+ */
+function safeLogUnhandled(prefix: string, value: unknown): void {
+  try {
+    log.error(prefix, value);
+  } catch (loggingError) {
+    const loggingFailure = loggingError instanceof Error
+      ? `${loggingError.name}: ${loggingError.message}`
+      : String(loggingError);
+    const original = value instanceof Error
+      ? (value.stack || `${value.name}: ${value.message}`)
+      : String(value);
+    safeStderrWrite(`[app-logger] ${prefix} (logger failed: ${loggingFailure})`);
+    safeStderrWrite(original);
+  }
+}
+
 // Log unhandled errors
 export function setupErrorLogging(): void {
   process.on('uncaughtException', (error) => {
-    log.error('Uncaught exception:', error);
+    safeLogUnhandled('Uncaught exception:', error);
   });
 
   process.on('unhandledRejection', (reason) => {
-    log.error('Unhandled rejection:', reason);
+    safeLogUnhandled('Unhandled rejection:', reason);
   });
 
   log.info('Error logging initialized');

apps/frontend/src/main/app-updater.ts

@@ -88,16 +88,18 @@ function htmlToMarkdown(html: string): string {
   md = md.replace(/<br\s*\/?>/gi, '\n');
   md = md.replace(/<hr\s*\/?>/gi, '---\n\n');
 
-  // Remove any remaining HTML tags
-  md = md.replace(/<[^>]+>/g, '');
+  // Remove any remaining HTML tags (loop to handle nested tag fragments)
+  while (/<[^>]+>/.test(md)) {
+    md = md.replace(/<[^>]+>/g, '');
+  }
 
-  // Decode common HTML entities
-  md = md.replace(/&amp;/g, '&');
+  // Decode common HTML entities (&amp; LAST to prevent double-unescaping like &amp;lt; → &lt; → <)
   md = md.replace(/&lt;/g, '<');
   md = md.replace(/&gt;/g, '>');
   md = md.replace(/&quot;/g, '"');
   md = md.replace(/&#39;/g, "'");
   md = md.replace(/&nbsp;/g, ' ');
+  md = md.replace(/&amp;/g, '&');
 
   // Clean up excessive whitespace
   md = md.replace(/\n{3,}/g, '\n\n');

apps/frontend/src/main/claude-profile/session-utils.ts

@@ -6,7 +6,8 @@
  * and can be copied between profiles to enable session continuity after profile switches.
  */
 
-import { existsSync, mkdirSync, copyFileSync, cpSync, unlinkSync } from 'fs';
+import { existsSync } from 'fs';
+import { mkdir, copyFile, cp, unlink } from 'fs/promises';
 import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { isNodeError } from '../utils/type-guards';
@@ -95,12 +96,12 @@ export interface SessionMigrationResult {
  * @param sessionId - The session UUID to migrate
  * @returns Migration result with success status and details
  */
-export function migrateSession(
+export async function migrateSession(
   sourceConfigDir: string,
   targetConfigDir: string,
   cwd: string,
   sessionId: string
-): SessionMigrationResult {
+): Promise<SessionMigrationResult> {
   const result: SessionMigrationResult = {
     success: false,
     sessionId,
@@ -118,13 +119,14 @@ export function migrateSession(
   try {
     // Ensure target directory exists (do this first, before any file operations)
     const targetParentDir = dirname(targetFile);
-    mkdirSync(targetParentDir, { recursive: true });
+    await mkdir(targetParentDir, { recursive: true });
     console.warn('[SessionUtils] Ensured target directory exists:', targetParentDir);
 
     // Attempt to copy the session .jsonl file
     // This will throw if source doesn't exist or target cannot be written
+    // Note: copyFile silently overwrites by default (no COPYFILE_EXCL flag)
     try {
-      copyFileSync(sourceFile, targetFile);
+      await copyFile(sourceFile, targetFile);
       result.filesCopied++;
       console.warn('[SessionUtils] Copied session file:', sourceFile, '->', targetFile);
     } catch (copyError) {
@@ -132,12 +134,6 @@ export function migrateSession(
       if (isNodeError(copyError)) {
         if (copyError.code === 'ENOENT') {
           result.error = `Source session file not found: ${sourceFile}`;
-        } else if (copyError.code === 'EEXIST') {
-          // Target already exists - this is OK, treat as successful skip
-          console.warn('[SessionUtils] Session already exists in target profile, skipping copy');
-          result.success = true;
-          result.filesCopied = 0;
-          return result;
         } else {
           result.error = `Failed to copy session file: ${copyError.message}`;
         }
@@ -153,7 +149,7 @@ export function migrateSession(
     // Attempt to copy the session directory (tool-results) if it exists
     // Use try-catch instead of existsSync to avoid TOCTOU race
     try {
-      cpSync(sourceDir, targetDir, { recursive: true });
+      await cp(sourceDir, targetDir, { recursive: true });
       result.filesCopied++;
       console.warn('[SessionUtils] Copied session directory:', sourceDir, '->', targetDir);
     } catch (dirCopyError) {
@@ -182,7 +178,7 @@ export function migrateSession(
     // Clean up partially migrated session file to enable retry
     // Use try-catch instead of existsSync to avoid TOCTOU race
     try {
-      unlinkSync(targetFile);
+      await unlink(targetFile);
       console.warn('[SessionUtils] Cleaned up partial migration file:', targetFile);
     } catch (cleanupError) {
       // If file doesn't exist during cleanup, that's fine

apps/frontend/src/main/file-watcher.ts

@@ -15,64 +15,122 @@ interface WatcherInfo {
  */
 export class FileWatcher extends EventEmitter {
   private watchers: Map<string, WatcherInfo> = new Map();
+  // Maps taskId -> specDir for the in-flight watch() call.
+  // Allows re-watch calls with a different specDir to proceed while
+  // still preventing duplicate calls for the exact same specDir.
+  private pendingWatches: Map<string, string> = new Map();
+  // Tracks taskIds that had unwatch() called while watch() was in-flight.
+  // Checked after each await point in watch() to avoid creating a leaked watcher.
+  private cancelledWatches: Set<string> = new Set();
 
   /**
    * Start watching a task's implementation plan
    */
   async watch(taskId: string, specDir: string): Promise<void> {
-    // Stop any existing watcher for this task
-    await this.unwatch(taskId);
-
-    const planPath = path.join(specDir, 'implementation_plan.json');
-
-    // Check if plan file exists
-    if (!existsSync(planPath)) {
-      this.emit('error', taskId, `Plan file not found: ${planPath}`);
+    // Prevent overlapping watch() calls for the same taskId + specDir combination.
+    // Since watch() is async, rapid-fire callers could enter concurrently
+    // before the first call updates state, creating duplicate watchers.
+    // A call with a different specDir is a legitimate re-watch and is allowed through.
+    const pendingSpecDir = this.pendingWatches.get(taskId);
+    if (pendingSpecDir !== undefined && pendingSpecDir === specDir) {
       return;
     }
+    this.pendingWatches.set(taskId, specDir);
 
-    // Create watcher with settings to handle frequent writes
-    const watcher = chokidar.watch(planPath, {
-      persistent: true,
-      ignoreInitial: true,
-      awaitWriteFinish: {
-        stabilityThreshold: 300,
-        pollInterval: 100
+    try {
+      // Close any existing watcher for this task.
+      // Delete from the map BEFORE awaiting close so that a concurrent watch()
+      // call entering after the await cannot obtain the same FSWatcher reference
+      // and attempt a second close() on the same object.
+      const existing = this.watchers.get(taskId);
+      if (existing) {
+        this.watchers.delete(taskId);
+        await existing.watcher.close();
       }
-    });
 
-    // Store watcher info
-    this.watchers.set(taskId, {
-      taskId,
-      watcher,
-      planPath
-    });
+      // Check if a newer watch() call has superseded this one while we were awaiting.
+      // If the pending specDir changed, another concurrent watch() took over — bail out
+      // to avoid overwriting the watcher it is about to create.
+      if (this.pendingWatches.get(taskId) !== specDir) {
+        return;
+      }
 
-    // Handle file changes
-    watcher.on('change', () => {
+      // Check if unwatch() was called while we were awaiting above.
+      if (this.cancelledWatches.has(taskId)) {
+        this.cancelledWatches.delete(taskId);
+        return;
+      }
+
+      const planPath = path.join(specDir, 'implementation_plan.json');
+
+      // Check if plan file exists
+      if (!existsSync(planPath)) {
+        this.emit('error', taskId, `Plan file not found: ${planPath}`);
+        return;
+      }
+
+      // Create watcher with settings to handle frequent writes
+      const watcher = chokidar.watch(planPath, {
+        persistent: true,
+        ignoreInitial: true,
+        awaitWriteFinish: {
+          stabilityThreshold: 300,
+          pollInterval: 100
+        }
+      });
+
+      // Check again after the synchronous watcher creation (no await, but defensive).
+      if (this.cancelledWatches.has(taskId)) {
+        this.cancelledWatches.delete(taskId);
+        await watcher.close();
+        return;
+      }
+
+      // Store watcher info
+      this.watchers.set(taskId, {
+        taskId,
+        watcher,
+        planPath
+      });
+
+      // Handle file changes
+      watcher.on('change', () => {
+        try {
+          const content = readFileSync(planPath, 'utf-8');
+          const plan: ImplementationPlan = JSON.parse(content);
+          this.emit('progress', taskId, plan);
+        } catch {
+          // File might be in the middle of being written
+          // Ignore parse errors, next change event will have complete file
+        }
+      });
+
+      // Handle errors
+      watcher.on('error', (error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error);
+        this.emit('error', taskId, message);
+      });
+
+      // Read and emit initial state
       try {
         const content = readFileSync(planPath, 'utf-8');
         const plan: ImplementationPlan = JSON.parse(content);
         this.emit('progress', taskId, plan);
       } catch {
-        // File might be in the middle of being written
-        // Ignore parse errors, next change event will have complete file
+        // Initial read failed - not critical
+      }
+    } finally {
+      // Only clean up if this call still owns the entry. If a superseding
+      // concurrent watch() call has already updated pendingWatches with a
+      // different specDir, leave that entry intact so the superseding call
+      // can proceed correctly.
+      if (this.pendingWatches.get(taskId) === specDir) {
+        this.pendingWatches.delete(taskId);
+        // The delete above guarantees has() is now false, so there is no
+        // longer any in-flight watch() for this taskId. Clear the
+        // cancellation flag so it doesn't linger for future watch() calls.
+        this.cancelledWatches.delete(taskId);
       }
-    });
-
-    // Handle errors
-    watcher.on('error', (error: unknown) => {
-      const message = error instanceof Error ? error.message : String(error);
-      this.emit('error', taskId, message);
-    });
-
-    // Read and emit initial state
-    try {
-      const content = readFileSync(planPath, 'utf-8');
-      const plan: ImplementationPlan = JSON.parse(content);
-      this.emit('progress', taskId, plan);
-    } catch {
-      // Initial read failed - not critical
     }
   }
 
@@ -80,6 +138,13 @@ export class FileWatcher extends EventEmitter {
    * Stop watching a task
    */
   async unwatch(taskId: string): Promise<void> {
+    // If watch() is currently in-flight for this taskId, it is already closing the
+    // existing watcher. Just set the cancellation flag and return to avoid a
+    // double-close of the same FSWatcher.
+    if (this.pendingWatches.has(taskId)) {
+      this.cancelledWatches.add(taskId);
+      return;
+    }
     const watcherInfo = this.watchers.get(taskId);
     if (watcherInfo) {
       await watcherInfo.watcher.close();
@@ -91,6 +156,17 @@ export class FileWatcher extends EventEmitter {
    * Stop all watchers
    */
   async unwatchAll(): Promise<void> {
+    // Cancel any in-flight watch() calls so they don't create new watchers
+    // after this cleanup completes.
+    for (const taskId of this.pendingWatches.keys()) {
+      this.cancelledWatches.add(taskId);
+    }
+    this.pendingWatches.clear();
+    // Clear cancellation flags now that pendingWatches is empty: the in-flight
+    // calls will bail via the supersession check (pendingWatches.get() returns
+    // undefined) and will not clean up cancelledWatches themselves. Clearing
+    // here ensures the instance is fully reset for subsequent use.
+    this.cancelledWatches.clear();
     const closePromises = Array.from(this.watchers.values()).map(
       async (info) => {
         await info.watcher.close();
@@ -107,6 +183,15 @@ export class FileWatcher extends EventEmitter {
     return this.watchers.has(taskId);
   }
 
+  /**
+   * Get the spec directory currently being watched for a task
+   */
+  getWatchedSpecDir(taskId: string): string | null {
+    const watcherInfo = this.watchers.get(taskId);
+    if (!watcherInfo) return null;
+    return path.dirname(watcherInfo.planPath);
+  }
+
   /**
    * Get current plan state for a task
    */

apps/frontend/src/main/index.ts

@@ -49,7 +49,7 @@ import { initializeAppUpdater, stopPeriodicUpdates } from './app-updater';
 import { DEFAULT_APP_SETTINGS, IPC_CHANNELS, SPELL_CHECK_LANGUAGE_MAP, DEFAULT_SPELL_CHECK_LANGUAGE, ADD_TO_DICTIONARY_LABELS } from '../shared/constants';
 import { getAppLanguage, initAppLanguage } from './app-language';
 import { readSettingsFile } from './settings-utils';
-import { setupErrorLogging } from './app-logger';
+import { appLog, setupErrorLogging } from './app-logger';
 import { initSentryMain } from './sentry';
 import { preWarmToolCache } from './cli-tool-manager';
 import { initializeClaudeProfileManager, getClaudeProfileManager } from './claude-profile-manager';
@@ -143,6 +143,11 @@ let mainWindow: BrowserWindow | null = null;
 let agentManager: AgentManager | null = null;
 let terminalManager: TerminalManager | null = null;
 
+// Capture child process exits (renderer/GPU/utility) for crash diagnostics.
+app.on('child-process-gone', (_event, details) => {
+  appLog.error('[main] child-process-gone:', details);
+});
+
 // Re-entrancy guard for before-quit handler.
 // The first before-quit call pauses quit for async cleanup, then calls app.quit() again.
 // The second call sees isQuitting=true and allows quit to proceed immediately.
@@ -214,6 +219,11 @@ function createWindow(): void {
     mainWindow?.show();
   });
 
+  // Capture renderer process crashes/termination reasons for diagnostics.
+  mainWindow.webContents.on('render-process-gone', (_event, details) => {
+    appLog.error('[main] render-process-gone:', details);
+  });
+
   // Configure initial spell check languages with proper fallback logic
   // Uses shared constant for consistency with the IPC handler
   const defaultLanguage = 'en';

apps/frontend/src/main/insights-service.ts

@@ -3,8 +3,10 @@ import type {
   InsightsSession,
   InsightsSessionSummary,
   InsightsChatMessage,
-  InsightsModelConfig
+  InsightsModelConfig,
+  ImageAttachment
 } from '../shared/types';
+import { MAX_IMAGES_PER_TASK } from '../shared/constants';
 import { InsightsConfig } from './insights/config';
 import { InsightsPaths } from './insights/paths';
 import { SessionStorage } from './insights/session-storage';
@@ -70,8 +72,8 @@ export class InsightsService extends EventEmitter {
   /**
    * List all sessions for a project
    */
-  listSessions(projectPath: string): InsightsSessionSummary[] {
-    return this.sessionManager.listSessions(projectPath);
+  listSessions(projectPath: string, includeArchived = false): InsightsSessionSummary[] {
+    return this.sessionManager.listSessions(projectPath, includeArchived);
   }
 
   /**
@@ -95,6 +97,34 @@ export class InsightsService extends EventEmitter {
     return this.sessionManager.deleteSession(projectId, projectPath, sessionId);
   }
 
+  /**
+   * Archive a session
+   */
+  archiveSession(projectId: string, projectPath: string, sessionId: string): boolean {
+    return this.sessionManager.archiveSession(projectId, projectPath, sessionId);
+  }
+
+  /**
+   * Unarchive a session
+   */
+  unarchiveSession(projectPath: string, sessionId: string): boolean {
+    return this.sessionManager.unarchiveSession(projectPath, sessionId);
+  }
+
+  /**
+   * Delete multiple sessions
+   */
+  deleteSessions(projectId: string, projectPath: string, sessionIds: string[]): { deletedIds: string[]; failedIds: string[] } {
+    return this.sessionManager.deleteSessions(projectId, projectPath, sessionIds);
+  }
+
+  /**
+   * Archive multiple sessions
+   */
+  archiveSessions(projectId: string, projectPath: string, sessionIds: string[]): { archivedIds: string[]; failedIds: string[] } {
+    return this.sessionManager.archiveSessions(projectId, projectPath, sessionIds);
+  }
+
   /**
    * Rename a session
    */
@@ -116,7 +146,8 @@ export class InsightsService extends EventEmitter {
     projectId: string,
     projectPath: string,
     message: string,
-    modelConfig?: InsightsModelConfig
+    modelConfig?: InsightsModelConfig,
+    images?: ImageAttachment[]
   ): Promise<void> {
     // Cancel any existing session
     this.executor.cancelSession(projectId);
@@ -139,22 +170,44 @@ export class InsightsService extends EventEmitter {
       session.title = this.storage.generateTitle(message);
     }
 
-    // Add user message
+    // Guard: cap images to MAX_IMAGES_PER_TASK
+    if (images && images.length > MAX_IMAGES_PER_TASK) {
+      images = images.slice(0, MAX_IMAGES_PER_TASK);
+    }
+
+    // Add user message (store thumbnails only for persistence, strip full data)
+    const persistImages = images?.map(img => ({
+      ...img,
+      data: undefined
+    }));
     const userMessage: InsightsChatMessage = {
       id: `msg-${Date.now()}`,
       role: 'user',
       content: message,
-      timestamp: new Date()
+      timestamp: new Date(),
+      images: persistImages && persistImages.length > 0 ? persistImages : undefined
     };
     session.messages.push(userMessage);
     session.updatedAt = new Date();
     this.sessionManager.saveSession(projectPath, session);
 
     // Build conversation history for context
-    const conversationHistory = session.messages.map(m => ({
-      role: m.role,
-      content: m.content
-    }));
+    // Add notation when images are present so the AI has context
+    // For historical messages (all but the last), use past tense to avoid confusion
+    const conversationHistory = session.messages.map((m, index) => {
+      const imageCount = m.images?.length ?? 0;
+      const isLastMessage = index === session.messages.length - 1;
+      let imageNotation = '';
+      if (imageCount > 0 && m.role === 'user') {
+        imageNotation = isLastMessage
+          ? `\n[User attached ${imageCount} image(s)]`
+          : `\n[User previously attached ${imageCount} image(s) - not visible in this context]`;
+      }
+      return {
+        role: m.role,
+        content: imageNotation ? m.content + imageNotation : m.content
+      };
+    });
 
     // Use provided modelConfig or fall back to session's config
     const configToUse = modelConfig || session.modelConfig;
@@ -166,7 +219,8 @@ export class InsightsService extends EventEmitter {
         projectPath,
         message,
         conversationHistory,
-        configToUse
+        configToUse,
+        images
       );
 
       // Add assistant message to session

apps/frontend/src/main/insights/insights-executor.ts

@@ -1,5 +1,7 @@
 import { spawn, ChildProcess } from 'child_process';
-import { existsSync, writeFileSync, unlinkSync } from 'fs';
+import { existsSync, unlinkSync } from 'fs';
+import { writeFile } from 'fs/promises';
+import { randomBytes } from 'crypto';
 import path from 'path';
 import os from 'os';
 import { EventEmitter } from 'events';
@@ -8,12 +10,23 @@ import type {
   InsightsChatStatus,
   InsightsStreamChunk,
   InsightsToolUsage,
-  InsightsModelConfig
+  InsightsModelConfig,
+  ImageAttachment
 } from '../../shared/types';
-import { MODEL_ID_MAP } from '../../shared/constants';
+import { MODEL_ID_MAP, MAX_IMAGES_PER_TASK, MAX_IMAGE_SIZE } from '../../shared/constants';
 import { InsightsConfig } from './config';
 import { detectRateLimit, createSDKRateLimitInfo } from '../rate-limit-detector';
 
+// Safe extension map for image MIME types — prevents path traversal via crafted mimeType
+// SVG excluded: contains active script content and is unsupported by Claude Vision API
+const SAFE_EXT_MAP: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp'
+};
+
 /**
  * Message processor result
  */
@@ -63,7 +76,8 @@ export class InsightsExecutor extends EventEmitter {
     projectPath: string,
     message: string,
     conversationHistory: Array<{ role: string; content: string }>,
-    modelConfig?: InsightsModelConfig
+    modelConfig?: InsightsModelConfig,
+    images?: ImageAttachment[]
   ): Promise<ProcessorResult> {
     // Cancel any existing session
     this.cancelSession(projectId);
@@ -90,18 +104,80 @@ export class InsightsExecutor extends EventEmitter {
     // Write conversation history to temp file to avoid Windows command-line length limit
     const historyFile = path.join(
       os.tmpdir(),
-      `insights-history-${projectId}-${Date.now()}.json`
+      `insights-history-${projectId}-${Date.now()}-${randomBytes(8).toString('hex')}.json`
     );
 
     let historyFileCreated = false;
     try {
-      writeFileSync(historyFile, JSON.stringify(conversationHistory), 'utf-8');
+      await writeFile(historyFile, JSON.stringify(conversationHistory), { encoding: 'utf-8', mode: 0o600 });
       historyFileCreated = true;
     } catch (err) {
       console.error('[Insights] Failed to write history file:', err);
       throw new Error('Failed to write conversation history to temp file');
     }
 
+    // Write image files and manifest if images are provided
+    const imagesTempFiles: string[] = [];
+    let imagesManifestFile: string | undefined;
+
+    // Defense-in-depth: cap image count and filter oversized images in the executor
+    if (images && images.length > MAX_IMAGES_PER_TASK) {
+      images = images.slice(0, MAX_IMAGES_PER_TASK);
+    }
+    if (images) {
+      images = images.filter(img => !img.data || Buffer.byteLength(img.data, 'base64') <= MAX_IMAGE_SIZE);
+    }
+
+    if (images && images.length > 0) {
+      try {
+        const manifest: Array<{ path: string; mimeType: string }> = [];
+        const timestamp = Date.now();
+
+        for (let i = 0; i < images.length; i++) {
+          const image = images[i];
+          if (!image.data) continue;
+
+          // Validate mimeType against allowlist (defense-in-depth for main process)
+          const ext = SAFE_EXT_MAP[image.mimeType];
+          if (!ext) {
+            console.warn(`[Insights] Skipping image with invalid mimeType: ${image.mimeType}`);
+            continue;
+          }
+
+          const imagePath = path.join(
+            os.tmpdir(),
+            `insights-image-${projectId}-${timestamp}-${i}-${randomBytes(8).toString('hex')}.${ext}`
+          );
+          await writeFile(imagePath, Buffer.from(image.data, 'base64'), { mode: 0o600 });
+          imagesTempFiles.push(imagePath);
+          manifest.push({ path: imagePath, mimeType: image.mimeType });
+        }
+
+        // Only write manifest file if we actually wrote any images
+        if (manifest.length > 0) {
+          imagesManifestFile = path.join(
+            os.tmpdir(),
+            `insights-images-manifest-${projectId}-${timestamp}-${randomBytes(8).toString('hex')}.json`
+          );
+          imagesTempFiles.push(imagesManifestFile); // Push before writeFile for cleanup on failure
+          await writeFile(imagesManifestFile, JSON.stringify(manifest), { encoding: 'utf-8', mode: 0o600 });
+        }
+      } catch (err) {
+        // Clean up any already-written image files
+        for (const tmpFile of imagesTempFiles) {
+          try {
+            if (existsSync(tmpFile)) unlinkSync(tmpFile);
+          } catch { /* ignore cleanup errors */ }
+        }
+        // Also clean up the history file (cleanupTempFiles isn't defined yet at this point)
+        if (existsSync(historyFile)) {
+          try { unlinkSync(historyFile); } catch { /* ignore */ }
+        }
+        console.error('[Insights] Failed to write image files:', err);
+        throw new Error('Failed to write image files to temp directory');
+      }
+    }
+
     // Build command arguments
     const args = [
       runnerPath,
@@ -110,6 +186,11 @@ export class InsightsExecutor extends EventEmitter {
       '--history-file', historyFile
     ];
 
+    // Add images manifest file if images were provided
+    if (imagesManifestFile) {
+      args.push('--images-file', imagesManifestFile);
+    }
+
     // Add model config if provided
     if (modelConfig) {
       const modelId = MODEL_ID_MAP[modelConfig.model] || MODEL_ID_MAP['sonnet'];
@@ -125,6 +206,27 @@ export class InsightsExecutor extends EventEmitter {
 
     this.activeSessions.set(projectId, proc);
 
+    // Shared cleanup for temp files used across close/error handlers
+    let cleanedUp = false;
+    const cleanupTempFiles = () => {
+      if (cleanedUp) return;
+      cleanedUp = true;
+      if (historyFileCreated && existsSync(historyFile)) {
+        try {
+          unlinkSync(historyFile);
+        } catch (cleanupErr) {
+          console.error('[Insights] Failed to cleanup history file:', cleanupErr);
+        }
+      }
+      for (const tmpFile of imagesTempFiles) {
+        try {
+          if (existsSync(tmpFile)) unlinkSync(tmpFile);
+        } catch (cleanupErr) {
+          console.error('[Insights] Failed to cleanup image temp file:', cleanupErr);
+        }
+      }
+    };
+
     return new Promise((resolve, reject) => {
       let fullResponse = '';
       const suggestedTasks: InsightsChatMessage['suggestedTasks'] = [];
@@ -170,15 +272,7 @@ export class InsightsExecutor extends EventEmitter {
 
       proc.on('close', (code) => {
         this.activeSessions.delete(projectId);
-
-        // Cleanup temp file
-        if (historyFileCreated && existsSync(historyFile)) {
-          try {
-            unlinkSync(historyFile);
-          } catch (cleanupErr) {
-            console.error('[Insights] Failed to cleanup history file:', cleanupErr);
-          }
-        }
+        cleanupTempFiles();
 
         // Check for rate limit if process failed
         if (code !== 0) {
@@ -217,15 +311,7 @@ export class InsightsExecutor extends EventEmitter {
 
       proc.on('error', (err) => {
         this.activeSessions.delete(projectId);
-
-        // Cleanup temp file
-        if (historyFileCreated && existsSync(historyFile)) {
-          try {
-            unlinkSync(historyFile);
-          } catch (cleanupErr) {
-            console.error('[Insights] Failed to cleanup history file:', cleanupErr);
-          }
-        }
+        cleanupTempFiles();
 
         this.emit('error', projectId, err.message);
         reject(err);

apps/frontend/src/main/insights/paths.ts

@@ -23,10 +23,21 @@ export class InsightsPaths {
     return path.join(this.getInsightsDir(projectPath), SESSIONS_DIR);
   }
 
+  /**
+   * Validate that a session ID matches the expected safe pattern.
+   * Prevents path traversal attacks via crafted session IDs.
+   */
+  private validateSessionId(sessionId: string): void {
+    if (!/^session-\d{1,20}$/.test(sessionId)) {
+      throw new Error('Invalid session ID format');
+    }
+  }
+
   /**
    * Get session file path for a specific session
    */
   getSessionPath(projectPath: string, sessionId: string): string {
+    this.validateSessionId(sessionId);
     return path.join(this.getSessionsDir(projectPath), `${sessionId}.json`);
   }
 

apps/frontend/src/main/insights/session-manager.ts

@@ -20,8 +20,9 @@ export class SessionManager {
    */
   loadSession(projectId: string, projectPath: string): InsightsSession | null {
     // Check in-memory cache first
-    if (this.sessions.has(projectId)) {
-      return this.sessions.get(projectId)!;
+    const cachedSession = this.sessions.get(projectId);
+    if (cachedSession) {
+      return cachedSession;
     }
 
     // Migrate old format if needed
@@ -40,10 +41,10 @@ export class SessionManager {
   /**
    * List all sessions for a project
    */
-  listSessions(projectPath: string): InsightsSessionSummary[] {
+  listSessions(projectPath: string, includeArchived = false): InsightsSessionSummary[] {
     // Migrate old format if needed
     this.storage.migrateOldSession(projectPath);
-    return this.storage.listSessions(projectPath);
+    return this.storage.listSessions(projectPath, includeArchived);
   }
 
   /**
@@ -105,6 +106,80 @@ export class SessionManager {
     return true;
   }
 
+  /**
+   * Archive a session
+   */
+  archiveSession(projectId: string, projectPath: string, sessionId: string): boolean {
+    const success = this.storage.archiveSession(projectPath, sessionId);
+    if (!success) return false;
+
+    // If this was the current session, auto-switch
+    const currentSession = this.sessions.get(projectId);
+    if (currentSession?.id === sessionId) {
+      this.sessions.delete(projectId);
+
+      const remaining = this.listSessions(projectPath);
+      if (remaining.length > 0) {
+        this.switchSession(projectId, projectPath, remaining[0].id);
+      } else {
+        this.storage.clearCurrentSessionId(projectPath);
+      }
+    }
+
+    return true;
+  }
+
+  /**
+   * Unarchive a session
+   */
+  unarchiveSession(projectPath: string, sessionId: string): boolean {
+    return this.storage.unarchiveSession(projectPath, sessionId);
+  }
+
+  /**
+   * Delete multiple sessions
+   */
+  deleteSessions(projectId: string, projectPath: string, sessionIds: string[]): { deletedIds: string[]; failedIds: string[] } {
+    const result = this.storage.deleteSessions(projectPath, sessionIds);
+
+    // Check if current cached session was among deleted
+    const currentSession = this.sessions.get(projectId);
+    if (currentSession && result.deletedIds.includes(currentSession.id)) {
+      this.sessions.delete(projectId);
+
+      const remaining = this.listSessions(projectPath);
+      if (remaining.length > 0) {
+        this.switchSession(projectId, projectPath, remaining[0].id);
+      } else {
+        this.storage.clearCurrentSessionId(projectPath);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Archive multiple sessions
+   */
+  archiveSessions(projectId: string, projectPath: string, sessionIds: string[]): { archivedIds: string[]; failedIds: string[] } {
+    const result = this.storage.archiveSessions(projectPath, sessionIds);
+
+    // Check if current cached session was among archived
+    const currentSession = this.sessions.get(projectId);
+    if (currentSession && result.archivedIds.includes(currentSession.id)) {
+      this.sessions.delete(projectId);
+
+      const remaining = this.listSessions(projectPath);
+      if (remaining.length > 0) {
+        this.switchSession(projectId, projectPath, remaining[0].id);
+      } else {
+        this.storage.clearCurrentSessionId(projectPath);
+      }
+    }
+
+    return result;
+  }
+
   /**
    * Rename a session
    */
@@ -115,6 +190,17 @@ export class SessionManager {
     session.title = newTitle;
     session.updatedAt = new Date();
     this.storage.saveSession(projectPath, session);
+
+    // Update cache if this session is cached
+    for (const [projectId, cachedSession] of this.sessions) {
+      if (cachedSession.id === sessionId) {
+        cachedSession.title = newTitle;
+        cachedSession.updatedAt = session.updatedAt;
+        this.sessions.set(projectId, cachedSession);
+        break;
+      }
+    }
+
     return true;
   }
 
@@ -133,7 +219,7 @@ export class SessionManager {
     for (const [projectId, cachedSession] of this.sessions) {
       if (cachedSession.id === sessionId) {
         cachedSession.modelConfig = modelConfig;
-        cachedSession.updatedAt = new Date();
+        cachedSession.updatedAt = session.updatedAt;
         this.sessions.set(projectId, cachedSession);
         break;
       }

apps/frontend/src/main/insights/session-storage.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
 import path from 'path';
-import type { InsightsSession, InsightsSessionSummary } from '../../shared/types';
+import type { InsightsSession, InsightsSessionSummary, ImageAttachment } from '../../shared/types';
 import { InsightsPaths } from './paths';
 
 /**
@@ -27,15 +27,18 @@ export class SessionStorage {
    * Load a specific session from disk
    */
   loadSessionById(projectPath: string, sessionId: string): InsightsSession | null {
-    const sessionPath = this.paths.getSessionPath(projectPath, sessionId);
-    if (!existsSync(sessionPath)) return null;
-
     try {
+      const sessionPath = this.paths.getSessionPath(projectPath, sessionId);
+      if (!existsSync(sessionPath)) return null;
+
       const content = readFileSync(sessionPath, 'utf-8');
       const session = JSON.parse(content) as InsightsSession;
       // Convert date strings back to Date objects
       session.createdAt = new Date(session.createdAt);
       session.updatedAt = new Date(session.updatedAt);
+      if (session.archivedAt) {
+        session.archivedAt = new Date(session.archivedAt);
+      }
       session.messages = session.messages.map(m => ({
         ...m,
         timestamp: new Date(m.timestamp),
@@ -55,23 +58,98 @@ export class SessionStorage {
    * Save session to disk
    */
   saveSession(projectPath: string, session: InsightsSession): void {
-    const sessionsDir = this.paths.getSessionsDir(projectPath);
-    if (!existsSync(sessionsDir)) {
-      mkdirSync(sessionsDir, { recursive: true });
+    try {
+      const sessionsDir = this.paths.getSessionsDir(projectPath);
+      if (!existsSync(sessionsDir)) {
+        mkdirSync(sessionsDir, { recursive: true });
+      }
+
+      const sessionPath = this.paths.getSessionPath(projectPath, session.id);
+      writeFileSync(sessionPath, JSON.stringify(session, null, 2), 'utf-8');
+    } catch (error) {
+      console.error(`[SessionStorage] Failed to save session ${session.id}:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Archive a session
+   */
+  archiveSession(projectPath: string, sessionId: string): boolean {
+    const session = this.loadSessionById(projectPath, sessionId);
+    if (!session) return false;
+
+    try {
+      session.archivedAt = new Date();
+      this.saveSession(projectPath, session);
+      return true;
+    } catch (error) {
+      console.error(`[SessionStorage] Failed to archive session ${sessionId}:`, error);
+      return false;
+    }
+  }
+
+  /**
+   * Unarchive a session
+   */
+  unarchiveSession(projectPath: string, sessionId: string): boolean {
+    const session = this.loadSessionById(projectPath, sessionId);
+    if (!session) return false;
+
+    try {
+      delete session.archivedAt;
+      this.saveSession(projectPath, session);
+      return true;
+    } catch (error) {
+      console.error(`[SessionStorage] Failed to unarchive session ${sessionId}:`, error);
+      return false;
+    }
+  }
+
+  /**
+   * Delete multiple sessions
+   */
+  deleteSessions(projectPath: string, sessionIds: string[]): { deletedIds: string[]; failedIds: string[] } {
+    const deletedIds: string[] = [];
+    const failedIds: string[] = [];
+
+    for (const sessionId of sessionIds) {
+      if (this.deleteSession(projectPath, sessionId)) {
+        deletedIds.push(sessionId);
+      } else {
+        failedIds.push(sessionId);
+      }
     }
 
-    const sessionPath = this.paths.getSessionPath(projectPath, session.id);
-    writeFileSync(sessionPath, JSON.stringify(session, null, 2), 'utf-8');
+    return { deletedIds, failedIds };
+  }
+
+  /**
+   * Archive multiple sessions
+   */
+  archiveSessions(projectPath: string, sessionIds: string[]): { archivedIds: string[]; failedIds: string[] } {
+    const archivedIds: string[] = [];
+    const failedIds: string[] = [];
+
+    for (const sessionId of sessionIds) {
+      if (this.archiveSession(projectPath, sessionId)) {
+        archivedIds.push(sessionId);
+      } else {
+        failedIds.push(sessionId);
+      }
+    }
+
+    return { archivedIds, failedIds };
   }
 
   /**
    * Delete a session from disk
    */
   deleteSession(projectPath: string, sessionId: string): boolean {
-    const sessionPath = this.paths.getSessionPath(projectPath, sessionId);
-    if (!existsSync(sessionPath)) return false;
-
     try {
+      const sessionPath = this.paths.getSessionPath(projectPath, sessionId);
+      if (!existsSync(sessionPath)) return false;
+
       unlinkSync(sessionPath);
       return true;
     } catch {
@@ -82,7 +160,7 @@ export class SessionStorage {
   /**
    * List all sessions for a project
    */
-  listSessions(projectPath: string): InsightsSessionSummary[] {
+  listSessions(projectPath: string, includeArchived = false): InsightsSessionSummary[] {
     const sessionsDir = this.paths.getSessionsDir(projectPath);
     if (!existsSync(sessionsDir)) return [];
 
@@ -104,13 +182,20 @@ export class SessionStorage {
               : 'Untitled Conversation';
           }
 
+          // Skip archived sessions unless explicitly included
+          if (!includeArchived && session.archivedAt) {
+            continue;
+          }
+
           sessions.push({
             id: session.id,
             projectId: session.projectId,
             title: title || 'New Conversation',
             messageCount: session.messages.length,
+            modelConfig: session.modelConfig,
             createdAt: new Date(session.createdAt),
-            updatedAt: new Date(session.updatedAt)
+            updatedAt: new Date(session.updatedAt),
+            ...(session.archivedAt ? { archivedAt: new Date(session.archivedAt) } : {})
           });
         } catch {
           // Skip invalid session files
@@ -165,6 +250,23 @@ export class SessionStorage {
     }
   }
 
+  /**
+   * Strip full-resolution image data from a session for persistence.
+   * Keeps only thumbnail, id, filename, mimeType, and size to prevent bloated JSON files.
+   */
+  private stripImageDataForPersistence(session: InsightsSession): InsightsSession {
+    return {
+      ...session,
+      messages: session.messages.map(m => {
+        if (!m.images || m.images.length === 0) return m;
+        return {
+          ...m,
+          images: m.images.map(({ data, path: _path, ...rest }: ImageAttachment) => rest)
+        };
+      })
+    };
+  }
+
   /**
    * Migrate old session format to new multi-session format
    */

apps/frontend/src/main/ipc-handlers/agent-events-handlers.ts

@@ -7,19 +7,25 @@ import type {
   AuthFailureInfo,
   ImplementationPlan,
 } from "../../shared/types";
-import { XSTATE_SETTLED_STATES, XSTATE_TO_PHASE, mapStateToLegacy } from "../../shared/state-machines";
+import { XSTATE_SETTLED_STATES, XSTATE_ACTIVE_STATES, XSTATE_TO_PHASE, mapStateToLegacy } from "../../shared/state-machines";
 import { AgentManager } from "../agent";
 import type { ProcessType, ExecutionProgressData } from "../agent";
 import { titleGenerator } from "../title-generator";
 import { fileWatcher } from "../file-watcher";
 import { notificationService } from "../notification-service";
-import { persistPlanLastEventSync, getPlanPath, persistPlanPhaseSync, persistPlanStatusAndReasonSync } from "./task/plan-file-utils";
+import { persistPlanLastEventSync, getPlanPath, persistPlanPhaseSync, persistPlanStatusAndReasonSync, hasPlanWithSubtasks } from "./task/plan-file-utils";
 import { findTaskWorktree } from "../worktree-paths";
 import { findTaskAndProject } from "./task/shared";
 import { safeSendToRenderer } from "./utils";
 import { getClaudeProfileManager } from "../claude-profile-manager";
 import { taskStateManager } from "../task-state-manager";
 
+// Timeout for fallback safety net to check if task is still stuck after process exit
+const STUCK_TASK_FALLBACK_TIMEOUT_MS = 500;
+
+// Map to store active fallback timers so they can be cancelled on task restart
+const fallbackTimers = new Map<string, NodeJS.Timeout>();
+
 /**
  * Register all agent-events-related IPC handlers
  */
@@ -96,9 +102,53 @@ export function registerAgenteventsHandlers(
 
     taskStateManager.handleProcessExited(taskId, code, exitTask, exitProject);
 
+    // Fallback safety net: If XState failed to transition the task out of an active state,
+    // force it to human_review after a short delay. This prevents tasks from getting stuck
+    // when the process exits without XState properly handling it.
+    // We check XState's current state directly to avoid stale cache issues from projectStore.
+    // Store timer reference so it can be cancelled if task restarts within the window.
+    const timer = setTimeout(() => {
+      const currentState = taskStateManager.getCurrentState(taskId);
+
+      if (currentState && XSTATE_ACTIVE_STATES.has(currentState)) {
+        const { task: checkTask, project: checkProject } = findTaskAndProject(taskId, projectId);
+        if (checkTask && checkProject) {
+          // Use shared utility to determine if a valid implementation plan exists
+          const hasPlan = hasPlanWithSubtasks(checkProject, checkTask);
+
+          console.warn(
+            `[agent-events-handlers] Task ${taskId} still in XState ${currentState} ` +
+            `${STUCK_TASK_FALLBACK_TIMEOUT_MS}ms after exit, forcing USER_STOPPED (hasPlan: ${hasPlan})`
+          );
+          taskStateManager.handleUiEvent(taskId, { type: 'USER_STOPPED', hasPlan }, checkTask, checkProject);
+        }
+      }
+      // Clean up timer reference after it fires
+      fallbackTimers.delete(taskId);
+    }, STUCK_TASK_FALLBACK_TIMEOUT_MS);
+
+    // Store timer reference for potential cancellation
+    fallbackTimers.set(taskId, timer);
+
     // Send final plan state to renderer BEFORE unwatching
     // This ensures the renderer has the final subtask data (fixes 0/0 subtask bug)
-    const finalPlan = fileWatcher.getCurrentPlan(taskId);
+    // Try the file watcher's current path first, then fall back to worktree path
+    let finalPlan = fileWatcher.getCurrentPlan(taskId);
+    if (!finalPlan && exitTask && exitProject) {
+      // File watcher may have been watching the wrong path (main vs worktree)
+      // Try reading directly from the worktree
+      const worktreePath = findTaskWorktree(exitProject.path, exitTask.specId);
+      if (worktreePath) {
+        const specsBaseDir = getSpecsDir(exitProject.autoBuildPath);
+        const worktreePlanPath = path.join(worktreePath, specsBaseDir, exitTask.specId, AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN);
+        try {
+          const content = readFileSync(worktreePlanPath, 'utf-8');
+          finalPlan = JSON.parse(content);
+        } catch {
+          // Worktree plan file not readable - not critical
+        }
+      }
+    }
     if (finalPlan) {
       safeSendToRenderer(
         getMainWindow,
@@ -109,7 +159,9 @@ export function registerAgenteventsHandlers(
       );
     }
 
-    fileWatcher.unwatch(taskId);
+    fileWatcher.unwatch(taskId).catch((err) => {
+      console.error(`[agent-events-handlers] Failed to unwatch for ${taskId}:`, err);
+    });
 
     if (processType === "spec-creation") {
       console.warn(`[Task ${taskId}] Spec creation completed with code ${code}`);
@@ -211,25 +263,46 @@ export function registerAgenteventsHandlers(
       const worktreePath = findTaskWorktree(project.path, task.specId);
       if (worktreePath) {
         const specsBaseDir = getSpecsDir(project.autoBuildPath);
+        const worktreeSpecDir = path.join(worktreePath, specsBaseDir, task.specId);
         const worktreePlanPath = path.join(
-          worktreePath,
-          specsBaseDir,
-          task.specId,
+          worktreeSpecDir,
           AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN
         );
         if (existsSync(worktreePlanPath)) {
           persistPlanPhaseSync(worktreePlanPath, progress.phase, project.id);
         }
+
+        // Re-watch the worktree path if the file watcher is still watching the main project path.
+        // This handles the case where the task started before the worktree existed:
+        // the initial watch fell back to the main project spec dir, but now the worktree
+        // is available and implementation_plan.json is being written there.
+        const currentWatchDir = fileWatcher.getWatchedSpecDir(taskId);
+        if (currentWatchDir && currentWatchDir !== worktreeSpecDir && existsSync(worktreePlanPath)) {
+          console.warn(`[agent-events-handlers] Re-watching worktree path for ${taskId}: ${worktreeSpecDir}`);
+          fileWatcher.watch(taskId, worktreeSpecDir).catch((err) => {
+            console.error(`[agent-events-handlers] Failed to re-watch worktree for ${taskId}:`, err);
+          });
+        }
       }
     } else if (xstateInTerminalState && progress.phase) {
       console.debug(`[agent-events-handlers] Skipping persistPlanPhaseSync for ${taskId}: XState in '${currentXState}', not overwriting with phase '${progress.phase}'`);
     }
 
-    // Skip sending execution-progress to renderer when XState has settled.
-    // XState's emitPhaseFromState already sent the correct phase to the renderer.
+    // Skip sending execution-progress to renderer when XState has settled,
+    // UNLESS this is a final phase update (complete/failed) AND the task is still in_progress.
+    // This prevents UI flicker where a failed phase arrives after the status has already changed to human_review.
+    const isFinalPhaseUpdate = progress.phase === 'complete' || progress.phase === 'failed';
     if (xstateInTerminalState) {
-      console.debug(`[agent-events-handlers] Skipping execution-progress to renderer for ${taskId}: XState in '${currentXState}', ignoring phase '${progress.phase}'`);
-      return;
+      if (!isFinalPhaseUpdate) {
+        console.debug(`[agent-events-handlers] Skipping execution-progress to renderer for ${taskId}: XState in '${currentXState}', ignoring phase '${progress.phase}'`);
+        return;
+      }
+      // For final phase updates, only send if task is still in_progress to prevent flicker
+      const { task } = findTaskAndProject(taskId, taskProjectId);
+      if (task && task.status !== 'in_progress') {
+        console.debug(`[agent-events-handlers] Skipping final phase '${progress.phase}' for ${taskId}: task status is '${task.status}', not 'in_progress'`);
+        return;
+      }
     }
     safeSendToRenderer(
       getMainWindow,
@@ -285,3 +358,17 @@ export function registerAgenteventsHandlers(
     safeSendToRenderer(getMainWindow, IPC_CHANNELS.TASK_ERROR, taskId, error, project?.id);
   });
 }
+
+/**
+ * Cancel any pending fallback timer for a task.
+ * Should be called when a task is restarted to prevent the stale timer
+ * from incorrectly stopping the new process.
+ */
+export function cancelFallbackTimer(taskId: string): void {
+  const timer = fallbackTimers.get(taskId);
+  if (timer) {
+    clearTimeout(timer);
+    fallbackTimers.delete(taskId);
+    console.debug(`[agent-events-handlers] Cancelled fallback timer for task ${taskId}`);
+  }
+}

apps/frontend/src/main/ipc-handlers/github/oauth-handlers.ts

@@ -51,6 +51,10 @@ function sendAuthChangedToRenderer(oldUsername: string | null, newUsername: stri
   for (const win of windows) {
     win.webContents.send(IPC_CHANNELS.GITHUB_AUTH_CHANGED, payload);
   }
+  // Uses EventEmitter.emit (not IPC send) so main-process listeners can react.
+  // The listener (PRReviewStateManager) intentionally ignores all args — it only
+  // needs the event signal, not the payload.
+  ipcMain.emit(IPC_CHANNELS.GITHUB_AUTH_CHANGED, payload);
 }
 
 /**

apps/frontend/src/main/ipc-handlers/github/pr-handlers.ts

@@ -26,7 +26,7 @@ import { getMemoryService, getDefaultDbPath } from "../../memory-service";
 import type { Project, AppSettings } from "../../../shared/types";
 import { createContextLogger } from "./utils/logger";
 import { withProjectOrNull } from "./utils/project-middleware";
-import { createIPCCommunicators } from "./utils/ipc-communicator";
+import { PRReviewStateManager } from "../../pr-review-state-manager";
 import { getRunnerEnv } from "./utils/runner-env";
 import {
   runPythonSubprocess,
@@ -1384,7 +1384,7 @@ function sendReviewStateUpdate(
   project: Project,
   prNumber: number,
   projectId: string,
-  getMainWindow: () => BrowserWindow | null,
+  prReviewStateManager: PRReviewStateManager,
   context: string
 ): void {
   try {
@@ -1393,18 +1393,8 @@ function sendReviewStateUpdate(
       debugLog("Could not retrieve updated review result for UI notification", { prNumber, context });
       return;
     }
-    const mainWindow = getMainWindow();
-    if (!mainWindow) return;
-    const { sendComplete } = createIPCCommunicators<PRReviewProgress, PRReviewResult>(
-      mainWindow,
-      {
-        progress: IPC_CHANNELS.GITHUB_PR_REVIEW_PROGRESS,
-        error: IPC_CHANNELS.GITHUB_PR_REVIEW_ERROR,
-        complete: IPC_CHANNELS.GITHUB_PR_REVIEW_COMPLETE,
-      },
-      projectId
-    );
-    sendComplete(updatedResult);
+    // Route through state manager so the XState actor emits the state change
+    prReviewStateManager.handleComplete(projectId, prNumber, updatedResult);
     debugLog(`Sent PR review state update ${context}`, { prNumber });
   } catch (uiError) {
     debugLog("Failed to send UI update (non-critical)", {
@@ -1445,7 +1435,8 @@ function getGitHubPRSettings(): { model: string; thinkingLevel: string } {
 async function runPRReview(
   project: Project,
   prNumber: number,
-  mainWindow: BrowserWindow
+  mainWindow: BrowserWindow,
+  prReviewStateManager: PRReviewStateManager
 ): Promise<PRReviewResult> {
   // Comprehensive validation of GitHub module
   const validation = await validateGitHubModule(project);
@@ -1456,15 +1447,9 @@ async function runPRReview(
 
   const backendPath = validation.backendPath!;
 
-  const { sendProgress } = createIPCCommunicators<PRReviewProgress, PRReviewResult>(
-    mainWindow,
-    {
-      progress: IPC_CHANNELS.GITHUB_PR_REVIEW_PROGRESS,
-      error: IPC_CHANNELS.GITHUB_PR_REVIEW_ERROR,
-      complete: IPC_CHANNELS.GITHUB_PR_REVIEW_COMPLETE,
-    },
-    project.id
-  );
+  const sendProgress = (progress: PRReviewProgress): void => {
+    prReviewStateManager.handleProgress(project.id, prNumber, progress);
+  };
 
   const { model, thinkingLevel } = getGitHubPRSettings();
   const args = buildRunnerArgs(
@@ -1499,6 +1484,19 @@ async function runPRReview(
   // Build environment with project settings
   const subprocessEnv = await getRunnerEnv(getClaudeMdEnv(project));
 
+  safeBreadcrumb({
+    category: 'github.pr-review',
+    message: `Subprocess env for PR #${prNumber} review`,
+    level: 'info',
+    data: {
+      prNumber,
+      hasGITHUB_CLI_PATH: !!subprocessEnv.GITHUB_CLI_PATH,
+      GITHUB_CLI_PATH: subprocessEnv.GITHUB_CLI_PATH ?? 'NOT SET',
+      hasGITHUB_TOKEN: !!subprocessEnv.GITHUB_TOKEN,
+      hasPYTHONPATH: !!subprocessEnv.PYTHONPATH,
+    },
+  });
+
   // Create operation ID for this review
   const reviewKey = getReviewKey(project.id, prNumber);
 
@@ -1682,6 +1680,32 @@ async function fetchPRsFromGraphQL(
 export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): void {
   debugLog("Registering PR handlers");
 
+  // Create the XState-based PR review state manager
+  const prReviewStateManager = new PRReviewStateManager(getMainWindow);
+
+  // Clear all PR review actors when GitHub auth changes (account swap)
+  ipcMain.on(IPC_CHANNELS.GITHUB_AUTH_CHANGED, () => {
+    // Cancel all running review subprocesses and CI wait controllers
+    for (const [reviewKey, entry] of runningReviews) {
+      if (entry === CI_WAIT_PLACEHOLDER) {
+        const abortController = ciWaitAbortControllers.get(reviewKey);
+        if (abortController) {
+          abortController.abort();
+          ciWaitAbortControllers.delete(reviewKey);
+        }
+      } else {
+        try {
+          entry.kill("SIGTERM");
+        } catch {
+          // Process may have already exited
+        }
+      }
+    }
+    runningReviews.clear();
+    ciWaitAbortControllers.clear();
+    prReviewStateManager.handleAuthChange();
+  });
+
   // List open PRs - fetches up to 100 open PRs at once, returns hasNextPage and endCursor from API
   ipcMain.handle(
     IPC_CHANNELS.GITHUB_PR_LIST,
@@ -1889,31 +1913,27 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
 
     try {
       await withProjectOrNull(projectId, async (project) => {
-        const { sendProgress, sendComplete } = createIPCCommunicators<
-          PRReviewProgress,
-          PRReviewResult
-        >(
-          mainWindow,
-          {
-            progress: IPC_CHANNELS.GITHUB_PR_REVIEW_PROGRESS,
-            error: IPC_CHANNELS.GITHUB_PR_REVIEW_ERROR,
-            complete: IPC_CHANNELS.GITHUB_PR_REVIEW_COMPLETE,
-          },
-          projectId
-        );
+        const sendProgress = (progress: PRReviewProgress): void => {
+          prReviewStateManager.handleProgress(projectId, prNumber, progress);
+        };
 
         // Check if already running — notify renderer so it can display ongoing logs
         if (runningReviews.has(reviewKey)) {
           debugLog("Review already running, notifying renderer", { reviewKey });
+          const currentSnapshot = prReviewStateManager.getState(projectId, prNumber);
+          const currentProgress = currentSnapshot?.context?.progress?.progress ?? 50;
           sendProgress({
             phase: "analyzing",
             prNumber,
-            progress: 50,
+            progress: currentProgress,
             message: "Review is already in progress. Reconnecting to ongoing review...",
           });
           return;
         }
 
+        // Notify state manager that review is starting (after duplicate check)
+        prReviewStateManager.handleStartReview(projectId, prNumber);
+
         // Register as running BEFORE CI wait to prevent race conditions
         // Use CI_WAIT_PLACEHOLDER sentinel until real process is spawned
         runningReviews.set(reviewKey, CI_WAIT_PLACEHOLDER);
@@ -1978,31 +1998,18 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
             message: "Fetching PR data...",
           });
 
-          const result = await runPRReview(project, prNumber, mainWindow);
-
-          if (result.overallStatus === "in_progress") {
-            // Review is already running externally (detected by BotDetector).
-            // Send the result as-is so the renderer can activate external review polling.
-            debugLog("PR review already in progress externally", { prNumber });
-            sendProgress({
-              phase: "complete",
-              prNumber,
-              progress: 100,
-              message: "Review already in progress",
-            });
-            sendComplete(result);
-            return;
-          }
+          const result = await runPRReview(project, prNumber, mainWindow, prReviewStateManager);
 
           debugLog("PR review completed", { prNumber, findingsCount: result.findings.length });
           sendProgress({
             phase: "complete",
             prNumber,
             progress: 100,
-            message: "Review complete!",
+            message: result.overallStatus === "in_progress" ? "Review already in progress" : "Review complete!",
           });
 
-          sendComplete(result);
+          // Route through manager — handles external review detection internally
+          prReviewStateManager.handleComplete(projectId, prNumber, result);
         } finally {
           // Clean up in case we exit before runPRReview was called (e.g., cancelled during CI wait)
           // runPRReview also has its own cleanup, but delete is idempotent
@@ -2019,16 +2026,7 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
         prNumber,
         error: error instanceof Error ? error.message : error,
       });
-      const { sendError } = createIPCCommunicators<PRReviewProgress, PRReviewResult>(
-        mainWindow,
-        {
-          progress: IPC_CHANNELS.GITHUB_PR_REVIEW_PROGRESS,
-          error: IPC_CHANNELS.GITHUB_PR_REVIEW_ERROR,
-          complete: IPC_CHANNELS.GITHUB_PR_REVIEW_COMPLETE,
-        },
-        projectId
-      );
-      sendError(error instanceof Error ? error.message : "Failed to run PR review");
+      prReviewStateManager.handleError(projectId, prNumber, error instanceof Error ? error.message : "Failed to run PR review");
     }
   });
 
@@ -2233,7 +2231,7 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
           }
 
           // Send state update event to refresh UI immediately (non-blocking)
-          sendReviewStateUpdate(project, prNumber, projectId, getMainWindow, "after posting");
+          sendReviewStateUpdate(project, prNumber, projectId, prReviewStateManager, "after posting");
 
           return true;
         } catch (error) {
@@ -2272,7 +2270,7 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
           debugLog("Marked review as posted", { prNumber });
 
           // Send state update event to refresh UI immediately (non-blocking)
-          sendReviewStateUpdate(project, prNumber, projectId, getMainWindow, "after marking posted");
+          sendReviewStateUpdate(project, prNumber, projectId, prReviewStateManager, "after marking posted");
 
           return true;
         } catch (error) {
@@ -2390,7 +2388,7 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
           }
 
           // Send state update event to refresh UI immediately (non-blocking)
-          sendReviewStateUpdate(project, prNumber, projectId, getMainWindow, "after deletion");
+          sendReviewStateUpdate(project, prNumber, projectId, prReviewStateManager, "after deletion");
 
           return true;
         } catch (error) {
@@ -2502,6 +2500,8 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
           ciWaitAbortControllers.delete(reviewKey);
         }
         runningReviews.delete(reviewKey);
+        // Notify state manager of cancellation
+        prReviewStateManager.handleCancel(projectId, prNumber);
         debugLog("CI wait cancelled", { reviewKey });
         return true;
       }
@@ -2522,6 +2522,8 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
 
         // Clean up the registry
         runningReviews.delete(reviewKey);
+        // Notify state manager of cancellation
+        prReviewStateManager.handleCancel(projectId, prNumber);
         debugLog("Review process cancelled", { reviewKey });
         return true;
       } catch (error) {
@@ -2534,6 +2536,21 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
     }
   );
 
+  // Notify main process about external review completion or timeout
+  // Called by renderer when its polling detects an external review has finished on disk
+  ipcMain.handle(
+    IPC_CHANNELS.GITHUB_PR_NOTIFY_EXTERNAL_REVIEW_COMPLETE,
+    async (_, projectId: string, prNumber: number, result: PRReviewResult | null): Promise<void> => {
+      debugLog("notifyExternalReviewComplete handler called", { projectId, prNumber, hasResult: !!result });
+      if (result) {
+        prReviewStateManager.handleComplete(projectId, prNumber, result);
+      } else {
+        // Timeout — no result found within polling window
+        prReviewStateManager.handleError(projectId, prNumber, "External review timed out after 30 minutes");
+      }
+    }
+  );
+
   // Check for new commits since last review
   ipcMain.handle(
     IPC_CHANNELS.GITHUB_PR_CHECK_NEW_COMMITS,
@@ -2919,34 +2936,40 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
 
       try {
         await withProjectOrNull(projectId, async (project) => {
-          const { sendProgress, sendError, sendComplete } = createIPCCommunicators<
-            PRReviewProgress,
-            PRReviewResult
-          >(
-            mainWindow,
-            {
-              progress: IPC_CHANNELS.GITHUB_PR_REVIEW_PROGRESS,
-              error: IPC_CHANNELS.GITHUB_PR_REVIEW_ERROR,
-              complete: IPC_CHANNELS.GITHUB_PR_REVIEW_COMPLETE,
-            },
-            projectId
-          );
+          const sendProgress = (progress: PRReviewProgress): void => {
+            prReviewStateManager.handleProgress(projectId, prNumber, progress);
+          };
+
+          const reviewKey = getReviewKey(projectId, prNumber);
+
+          // Check if already running — notify renderer so it can display ongoing logs
+          if (runningReviews.has(reviewKey)) {
+            debugLog("Follow-up review already running, notifying renderer", { reviewKey });
+            const currentSnapshot = prReviewStateManager.getState(projectId, prNumber);
+            const currentProgress = currentSnapshot?.context?.progress?.progress ?? 50;
+            sendProgress({
+              phase: "analyzing",
+              prNumber,
+              progress: currentProgress,
+              message: "Follow-up review is already in progress. Reconnecting to ongoing review...",
+            });
+            return;
+          }
+
+          // Get previous result for followup context
+          const previousResult = getReviewResult(project, prNumber) ?? undefined;
+
+          // Notify state manager that followup review is starting (after duplicate check)
+          prReviewStateManager.handleStartFollowupReview(projectId, prNumber, previousResult);
 
           // Comprehensive validation of GitHub module
           const validation = await validateGitHubModule(project);
           if (!validation.valid) {
-            sendError({ prNumber, error: validation.error || "GitHub module validation failed" });
+            prReviewStateManager.handleError(projectId, prNumber, validation.error || "GitHub module validation failed");
             return;
           }
 
           const backendPath = validation.backendPath!;
-          const reviewKey = getReviewKey(projectId, prNumber);
-
-          // Check if already running
-          if (runningReviews.has(reviewKey)) {
-            debugLog("Follow-up review already running", { reviewKey });
-            return;
-          }
 
           // Register as running BEFORE CI wait to prevent race conditions
           // Use CI_WAIT_PLACEHOLDER sentinel until real process is spawned
@@ -3015,6 +3038,19 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
           // Build environment with project settings
           const followupEnv = await getRunnerEnv(getClaudeMdEnv(project));
 
+          safeBreadcrumb({
+            category: 'github.pr-review',
+            message: `Subprocess env for PR #${prNumber} follow-up review`,
+            level: 'info',
+            data: {
+              prNumber,
+              hasGITHUB_CLI_PATH: !!followupEnv.GITHUB_CLI_PATH,
+              GITHUB_CLI_PATH: followupEnv.GITHUB_CLI_PATH ?? 'NOT SET',
+              hasGITHUB_TOKEN: !!followupEnv.GITHUB_TOKEN,
+              hasPYTHONPATH: !!followupEnv.PYTHONPATH,
+            },
+          });
+
           const { process: childProcess, promise } = runPythonSubprocess<PRReviewResult>({
             pythonPath: getPythonPath(backendPath),
             args,
@@ -3103,7 +3139,8 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
               message: "Follow-up review complete!",
             });
 
-            sendComplete(result.data!);
+            // Route through state manager
+            prReviewStateManager.handleComplete(projectId, prNumber, result.data!);
           } finally {
             // Always clean up registry, whether we exit normally or via error
             runningReviews.delete(reviewKey);
@@ -3116,19 +3153,7 @@ export function registerPRHandlers(getMainWindow: () => BrowserWindow | null): v
           prNumber,
           error: error instanceof Error ? error.message : error,
         });
-        const { sendError } = createIPCCommunicators<PRReviewProgress, PRReviewResult>(
-          mainWindow,
-          {
-            progress: IPC_CHANNELS.GITHUB_PR_REVIEW_PROGRESS,
-            error: IPC_CHANNELS.GITHUB_PR_REVIEW_ERROR,
-            complete: IPC_CHANNELS.GITHUB_PR_REVIEW_COMPLETE,
-          },
-          projectId
-        );
-        sendError({
-          prNumber,
-          error: error instanceof Error ? error.message : "Failed to run follow-up review",
-        });
+        prReviewStateManager.handleError(projectId, prNumber, error instanceof Error ? error.message : "Failed to run follow-up review");
       }
     }
   );

apps/frontend/src/main/ipc-handlers/github/utils/__tests__/runner-env.test.ts

@@ -30,6 +30,15 @@ vi.mock('../../utils', () => ({
   getGitHubTokenForSubprocess: () => mockGetGitHubTokenForSubprocess(),
 }));
 
+vi.mock('../../../../cli-tool-manager', () => ({
+  getToolInfo: () => ({ found: false, path: undefined, source: undefined }),
+}));
+
+vi.mock('../../../../sentry', () => ({
+  getSentryEnvForSubprocess: () => ({}),
+  safeBreadcrumb: () => {},
+}));
+
 import { getRunnerEnv } from '../runner-env';
 
 describe('getRunnerEnv', () => {

apps/frontend/src/main/ipc-handlers/github/utils/runner-env.ts

@@ -3,7 +3,8 @@ import { getAPIProfileEnv } from '../../../services/profile';
 import { getBestAvailableProfileEnv } from '../../../rate-limit-detector';
 import { pythonEnvManager } from '../../../python-env-manager';
 import { getGitHubTokenForSubprocess } from '../utils';
-import { getSentryEnvForSubprocess } from '../../../sentry';
+import { getSentryEnvForSubprocess, safeBreadcrumb } from '../../../sentry';
+import { getToolInfo } from '../../../cli-tool-manager';
 
 /**
  * Get environment variables for Python runner subprocesses.
@@ -43,12 +44,30 @@ export async function getRunnerEnv(
   const githubToken = await getGitHubTokenForSubprocess();
   const githubEnv: Record<string, string> = githubToken ? { GITHUB_TOKEN: githubToken } : {};
 
+  // Resolve gh CLI path so Python subprocess can find it in bundled apps
+  // (bundled Electron apps have a stripped PATH that doesn't include Homebrew etc.)
+  const ghInfo = getToolInfo('gh');
+  const ghCliEnv: Record<string, string> = ghInfo.found && ghInfo.path ? { GITHUB_CLI_PATH: ghInfo.path } : {};
+  safeBreadcrumb({
+    category: 'github.runner-env',
+    message: `gh CLI for subprocess: found=${ghInfo.found}, path=${ghInfo.path ?? 'none'}, source=${ghInfo.source ?? 'none'}`,
+    level: ghInfo.found ? 'info' : 'warning',
+    data: {
+      found: ghInfo.found,
+      path: ghInfo.path ?? null,
+      source: ghInfo.source ?? null,
+      willSetGITHUB_CLI_PATH: !!(ghInfo.found && ghInfo.path),
+      hasGITHUB_TOKEN: !!githubToken,
+    },
+  });
+
   return {
     ...pythonEnv,  // Python environment including PYTHONPATH (fixes #139)
     ...apiProfileEnv,
     ...oauthModeClearVars,
     ...profileEnv,  // OAuth token from profile manager (fixes #563, rate-limit aware)
     ...githubEnv,  // Fresh GitHub token from gh CLI (fixes #151)
+    ...ghCliEnv,  // gh CLI path for bundled apps (Python backend uses GITHUB_CLI_PATH)
     ...getSentryEnvForSubprocess(),  // Sentry DSN + sample rates for Python subprocess
     ...extraEnv,  // extraEnv last so callers can still override
   };

apps/frontend/src/main/ipc-handlers/github/utils/subprocess-runner.ts

@@ -20,7 +20,8 @@ import { isWindows, isMacOS } from '../../../platform';
 import { getEffectiveSourcePath } from '../../../updater/path-resolver';
 import { pythonEnvManager, getConfiguredPythonPath } from '../../../python-env-manager';
 import { getTaskkillExePath, getWhereExePath } from '../../../utils/windows-paths';
-import { safeCaptureException } from '../../../sentry';
+import { safeCaptureException, safeBreadcrumb } from '../../../sentry';
+import { getToolInfo } from '../../../cli-tool-manager';
 
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
@@ -559,6 +560,7 @@ export interface GitHubModuleValidation {
   pythonEnvValid: boolean;
   error?: string;
   backendPath?: string;
+  ghCliPath?: string;
 }
 
 /**
@@ -622,33 +624,36 @@ export async function validateGitHubModule(project: Project): Promise<GitHubModu
     return result;
   }
 
-  // 2. Check gh CLI installation (cross-platform)
-  try {
-    if (isWindows()) {
-      await execFileAsync(getWhereExePath(), ['gh'], { timeout: 5000 });
-    } else {
-      await execAsync('which gh');
-    }
+  // 2. Check gh CLI installation (uses CLI tool manager for bundled app compatibility)
+  const ghInfo = getToolInfo('gh');
+  safeBreadcrumb({
+    category: 'github.validation',
+    message: `gh CLI lookup: found=${ghInfo.found}, path=${ghInfo.path ?? 'none'}, source=${ghInfo.source ?? 'none'}`,
+    level: ghInfo.found ? 'info' : 'warning',
+    data: { found: ghInfo.found, path: ghInfo.path ?? null, source: ghInfo.source ?? null },
+  });
+  if (ghInfo.found && ghInfo.path) {
     result.ghCliInstalled = true;
-  } catch (error: unknown) {
+    result.ghCliPath = ghInfo.path;
+  } else {
     result.ghCliInstalled = false;
-    const errCode = (error as NodeJS.ErrnoException).code;
-    if (errCode === 'ENOENT' && isWindows()) {
-      result.error = `System utility 'where.exe' not found. Check Windows installation.`;
-    } else {
-      const installInstructions = isWindows()
-        ? 'winget install --id GitHub.cli'
-        : isMacOS()
-          ? 'brew install gh'
-          : 'See https://cli.github.com/';
-      result.error = `GitHub CLI (gh) is not installed. Install it with:\n  ${installInstructions}`;
-    }
+    const installInstructions = isWindows()
+      ? 'winget install --id GitHub.cli'
+      : isMacOS()
+        ? 'brew install gh'
+        : 'See https://cli.github.com/';
+    result.error = `GitHub CLI (gh) is not installed. Install it with:\n  ${installInstructions}`;
+    safeCaptureException(new Error('gh CLI not found in bundled app'), {
+      tags: { component: 'github-validation' },
+      extra: { ghInfo, isPackaged: require('electron').app?.isPackaged ?? 'unknown' },
+    });
     return result;
   }
 
-  // 3. Check gh authentication
+  // 3. Check gh authentication (use resolved path for bundled app compatibility)
   try {
-    await execAsync('gh auth status 2>&1');
+    const ghPath = result.ghCliPath || 'gh';
+    await execAsync(`"${ghPath}" auth status 2>&1`);
     result.ghAuthenticated = true;
   } catch (error: any) {
     // gh auth status returns non-zero when not authenticated

apps/frontend/src/main/ipc-handlers/insights-handlers.ts

@@ -16,6 +16,7 @@ import type {
   InsightsSession,
   InsightsSessionSummary,
   InsightsModelConfig,
+  ImageAttachment,
   Task,
   TaskMetadata,
   AppSettings,
@@ -81,7 +82,7 @@ export function registerInsightsHandlers(getMainWindow: () => BrowserWindow | nu
 
   ipcMain.on(
     IPC_CHANNELS.INSIGHTS_SEND_MESSAGE,
-    async (_, projectId: string, message: string, modelConfig?: InsightsModelConfig) => {
+    async (_, projectId: string, message: string, modelConfig?: InsightsModelConfig, images?: ImageAttachment[]) => {
       const project = projectStore.getProject(projectId);
       if (!project) {
         safeSendToRenderer(
@@ -112,7 +113,7 @@ export function registerInsightsHandlers(getMainWindow: () => BrowserWindow | nu
       // the handler returns. This fixes race conditions on Windows where
       // environment setup wouldn't complete before process spawn.
       try {
-        await insightsService.sendMessage(projectId, project.path, message, configWithSettings);
+        await insightsService.sendMessage(projectId, project.path, message, configWithSettings, images);
       } catch (error) {
         // Errors during sendMessage (executor errors) are already emitted via
         // the 'error' event, but we catch here to prevent unhandled rejection
@@ -249,17 +250,95 @@ export function registerInsightsHandlers(getMainWindow: () => BrowserWindow | nu
   // List all sessions for a project
   ipcMain.handle(
     IPC_CHANNELS.INSIGHTS_LIST_SESSIONS,
-    async (_, projectId: string): Promise<IPCResult<InsightsSessionSummary[]>> => {
+    async (_, projectId: string, includeArchived?: boolean): Promise<IPCResult<InsightsSessionSummary[]>> => {
       const project = projectStore.getProject(projectId);
       if (!project) {
         return { success: false, error: "Project not found" };
       }
 
-      const sessions = insightsService.listSessions(project.path);
+      const sessions = insightsService.listSessions(project.path, includeArchived ?? false);
       return { success: true, data: sessions };
     }
   );
 
+  // Delete multiple sessions
+  ipcMain.handle(
+    IPC_CHANNELS.INSIGHTS_DELETE_SESSIONS,
+    async (_, projectId: string, sessionIds: string[]): Promise<IPCResult<{ deletedIds: string[]; failedIds: string[] }>> => {
+      if (!Array.isArray(sessionIds) || sessionIds.length === 0) {
+        return { success: false, error: "No sessions specified" };
+      }
+
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: "Project not found" };
+      }
+
+      const result = insightsService.deleteSessions(projectId, project.path, sessionIds);
+      return {
+        success: result.failedIds.length === 0,
+        data: result,
+        ...(result.failedIds.length > 0 && { error: `Failed to delete ${result.failedIds.length} session(s)` })
+      };
+    }
+  );
+
+  // Archive a session
+  ipcMain.handle(
+    IPC_CHANNELS.INSIGHTS_ARCHIVE_SESSION,
+    async (_, projectId: string, sessionId: string): Promise<IPCResult> => {
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: "Project not found" };
+      }
+
+      const success = insightsService.archiveSession(projectId, project.path, sessionId);
+      if (success) {
+        return { success: true };
+      }
+      return { success: false, error: "Failed to archive session" };
+    }
+  );
+
+  // Archive multiple sessions
+  ipcMain.handle(
+    IPC_CHANNELS.INSIGHTS_ARCHIVE_SESSIONS,
+    async (_, projectId: string, sessionIds: string[]): Promise<IPCResult<{ archivedIds: string[]; failedIds: string[] }>> => {
+      if (!Array.isArray(sessionIds) || sessionIds.length === 0) {
+        return { success: false, error: "No sessions specified" };
+      }
+
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: "Project not found" };
+      }
+
+      const result = insightsService.archiveSessions(projectId, project.path, sessionIds);
+      return {
+        success: result.failedIds.length === 0,
+        data: result,
+        ...(result.failedIds.length > 0 && { error: `Failed to archive ${result.failedIds.length} session(s)` })
+      };
+    }
+  );
+
+  // Unarchive a session
+  ipcMain.handle(
+    IPC_CHANNELS.INSIGHTS_UNARCHIVE_SESSION,
+    async (_, projectId: string, sessionId: string): Promise<IPCResult> => {
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: "Project not found" };
+      }
+
+      const success = insightsService.unarchiveSession(project.path, sessionId);
+      if (success) {
+        return { success: true };
+      }
+      return { success: false, error: "Failed to unarchive session" };
+    }
+  );
+
   // Create a new session
   ipcMain.handle(
     IPC_CHANNELS.INSIGHTS_NEW_SESSION,

apps/frontend/src/main/ipc-handlers/project-handlers.ts

@@ -153,16 +153,24 @@ function getGitBranchesWithInfo(projectPath: string): GitBranchDetail[] {
         .map(b => b.trim())
         // Remove HEAD pointer entries like "origin/HEAD"
         .filter(b => !b.endsWith('/HEAD'))
-        .map(name => ({
-          name,
-          type: 'remote' as const,
-          displayName: name,
-          isCurrent: false
-        }));
+        .map(fullName => {
+          // Strip "origin/" prefix so branch names are clean for PR targets etc.
+          const name = fullName.replace(/^origin\//, '');
+          return {
+            name,
+            type: 'remote' as const,
+            displayName: name,
+            isCurrent: false
+          };
+        });
     } catch {
       // Remote branches may not exist, continue with local only
     }
 
+    // Deduplicate: if a branch exists locally and remotely, keep only the local entry
+    const localNames = new Set(localBranches.map(b => b.name));
+    remoteBranches = remoteBranches.filter(b => !localNames.has(b.name));
+
     // Combine and sort: local branches first, then remote branches, alphabetically within each group
     const allBranches = [...localBranches, ...remoteBranches];
 

apps/frontend/src/main/ipc-handlers/roadmap-handlers.ts

@@ -127,6 +127,7 @@ export function registerRoadmapHandlers(
                 })),
                 strengths: (c.strengths as string[]) || [],
                 marketPosition: (c.market_position as string) || "",
+                source: c.source || undefined,
               })),
               marketGaps: (rawCompetitor.market_gaps || []).map((g: Record<string, unknown>) => ({
                 id: g.id,
@@ -792,6 +793,148 @@ ${(feature.acceptance_criteria || []).map((c: string) => `- [ ] ${c}`).join("\n"
     }
   );
 
+  // ============================================
+  // Competitor Analysis Save
+  // ============================================
+
+  ipcMain.handle(
+    IPC_CHANNELS.COMPETITOR_ANALYSIS_SAVE,
+    async (
+      _,
+      projectId: string,
+      competitorAnalysis: CompetitorAnalysis
+    ): Promise<IPCResult> => {
+      const project = projectStore.getProject(projectId);
+      if (!project) {
+        return { success: false, error: "Project not found" };
+      }
+
+      const roadmapDir = path.join(project.path, AUTO_BUILD_PATHS.ROADMAP_DIR);
+      const competitorAnalysisPath = path.join(
+        roadmapDir,
+        AUTO_BUILD_PATHS.COMPETITOR_ANALYSIS
+      );
+
+      try {
+        // Ensure roadmap directory exists
+        if (!existsSync(roadmapDir)) {
+          mkdirSync(roadmapDir, { recursive: true });
+        }
+
+        await withFileLock(competitorAnalysisPath, async () => {
+          // Transform camelCase to snake_case for JSON file
+          const serialized = {
+            project_context: {
+              project_name: competitorAnalysis.projectContext.projectName,
+              project_type: competitorAnalysis.projectContext.projectType,
+              target_audience: competitorAnalysis.projectContext.targetAudience,
+            },
+            competitors: competitorAnalysis.competitors.map((c) => ({
+              id: c.id,
+              name: c.name,
+              url: c.url,
+              description: c.description,
+              relevance: c.relevance,
+              pain_points: c.painPoints.map((p) => ({
+                id: p.id,
+                description: p.description,
+                source: p.source,
+                severity: p.severity,
+                frequency: p.frequency,
+                opportunity: p.opportunity,
+              })),
+              strengths: c.strengths,
+              market_position: c.marketPosition,
+              source: c.source,
+            })),
+            market_gaps: competitorAnalysis.marketGaps.map((g) => ({
+              id: g.id,
+              description: g.description,
+              affected_competitors: g.affectedCompetitors,
+              opportunity_size: g.opportunitySize,
+              suggested_feature: g.suggestedFeature,
+            })),
+            insights_summary: {
+              top_pain_points: competitorAnalysis.insightsSummary.topPainPoints,
+              differentiator_opportunities:
+                competitorAnalysis.insightsSummary.differentiatorOpportunities,
+              market_trends: competitorAnalysis.insightsSummary.marketTrends,
+            },
+            research_metadata: {
+              search_queries_used:
+                competitorAnalysis.researchMetadata.searchQueriesUsed,
+              sources_consulted:
+                competitorAnalysis.researchMetadata.sourcesConsulted,
+              limitations: competitorAnalysis.researchMetadata.limitations,
+            },
+            metadata: {
+              created_at: competitorAnalysis.createdAt
+                ? new Date(competitorAnalysis.createdAt).toISOString()
+                : new Date().toISOString(),
+              updated_at: new Date().toISOString(),
+            },
+          };
+
+          await writeFileWithRetry(
+            competitorAnalysisPath,
+            JSON.stringify(serialized, null, 2),
+            { encoding: 'utf-8' }
+          );
+        });
+
+        // Also persist manual competitors to a separate file that the backend
+        // agent never overwrites, preventing data loss during concurrent analysis
+        const manualCompetitors = competitorAnalysis.competitors.filter(
+          (c) => c.source === "manual"
+        );
+        if (manualCompetitors.length > 0) {
+          const manualCompetitorsPath = path.join(
+            roadmapDir,
+            AUTO_BUILD_PATHS.MANUAL_COMPETITORS
+          );
+          const manualSerialized = {
+            competitors: manualCompetitors.map((c) => ({
+              id: c.id,
+              name: c.name,
+              url: c.url,
+              description: c.description,
+              relevance: c.relevance,
+              pain_points: c.painPoints.map((p) => ({
+                id: p.id,
+                description: p.description,
+                source: p.source,
+                severity: p.severity,
+                frequency: p.frequency,
+                opportunity: p.opportunity,
+              })),
+              strengths: c.strengths,
+              market_position: c.marketPosition,
+              source: c.source,
+            })),
+            updated_at: new Date().toISOString(),
+          };
+          await writeFileWithRetry(
+            manualCompetitorsPath,
+            JSON.stringify(manualSerialized, null, 2),
+            { encoding: "utf-8" }
+          );
+        }
+
+        debugLog("[Roadmap Handler] Saved competitor analysis:", { projectId });
+        return { success: true };
+      } catch (error) {
+        debugError("[Roadmap Handler] Failed to save competitor analysis:", error);
+        return {
+          success: false,
+          error:
+            error instanceof Error
+              ? error.message
+              : "Failed to save competitor analysis",
+        };
+      }
+    }
+  );
+
   // ============================================
   // Roadmap Agent Events → Renderer
   // ============================================

apps/frontend/src/main/ipc-handlers/task/execution-handlers.ts

@@ -15,12 +15,14 @@ import {
   getPlanPath,
   persistPlanStatus,
   createPlanIfNotExists,
-  resetStuckSubtasks
+  resetStuckSubtasks,
+  hasPlanWithSubtasks
 } from './plan-file-utils';
 import { writeFileAtomicSync } from '../../utils/atomic-file';
 import { findTaskWorktree } from '../../worktree-paths';
 import { projectStore } from '../../project-store';
 import { getIsolatedGitEnv, detectWorktreeBranch } from '../../utils/git-isolation';
+import { cancelFallbackTimer } from '../agent-events-handlers';
 
 /**
  * Safe file read that handles missing files without TOCTOU issues.
@@ -81,6 +83,22 @@ async function ensureProfileManagerInitialized(): Promise<
   }
 }
 
+/**
+ * Get the spec directory for file watching, preferring the worktree path if it exists.
+ * When a task runs in a worktree, implementation_plan.json is written there,
+ * not in the main project's spec directory.
+ */
+function getSpecDirForWatcher(projectPath: string, specsBaseDir: string, specId: string): string {
+  const worktreePath = findTaskWorktree(projectPath, specId);
+  if (worktreePath) {
+    const worktreeSpecDir = path.join(worktreePath, specsBaseDir, specId);
+    if (existsSync(path.join(worktreeSpecDir, 'implementation_plan.json'))) {
+      return worktreeSpecDir;
+    }
+  }
+  return path.join(projectPath, specsBaseDir, specId);
+}
+
 /**
  * Register task execution handlers (start, stop, review, status management, recovery)
  */
@@ -95,6 +113,11 @@ export function registerTaskExecutionHandlers(
     IPC_CHANNELS.TASK_START,
     async (_, taskId: string, _options?: TaskStartOptions) => {
       console.warn('[TASK_START] Received request for taskId:', taskId);
+
+      // Cancel any pending fallback timer from previous process exit
+      // This prevents the stale timer from incorrectly stopping the newly restarted task
+      cancelFallbackTimer(taskId);
+
       const mainWindow = getMainWindow();
       if (!mainWindow) {
         console.warn('[TASK_START] No main window found');
@@ -161,6 +184,31 @@ export function registerTaskExecutionHandlers(
 
       console.warn('[TASK_START] Found task:', task.specId, 'status:', task.status, 'reviewReason:', task.reviewReason, 'subtasks:', task.subtasks.length);
 
+      // Clear stale tracking state from any previous execution so that:
+      // - terminalEventSeen doesn't suppress future PROCESS_EXITED events
+      // - lastSequenceByTask doesn't drop events from the new process
+      taskStateManager.prepareForRestart(taskId);
+
+      // Check if implementation_plan.json has valid subtasks BEFORE XState handling.
+      // This is more reliable than task.subtasks.length which may not be loaded yet.
+      const specsBaseDir = getSpecsDir(project.autoBuildPath);
+      const specDir = path.join(
+        project.path,
+        specsBaseDir,
+        task.specId
+      );
+      const planFilePath = path.join(specDir, AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN);
+      let planHasSubtasks = false;
+      const planContent = safeReadFileSync(planFilePath);
+      if (planContent) {
+        try {
+          const plan = JSON.parse(planContent);
+          planHasSubtasks = checkSubtasksCompletion(plan).totalCount > 0;
+        } catch {
+          // Invalid/corrupt plan file - treat as no subtasks
+        }
+      }
+
       // Immediately mark as started so the UI moves the card to In Progress.
       // Use XState actor state as source of truth (if actor exists), with task data as fallback.
       // - plan_review: User approved the plan, send PLAN_APPROVED to transition to coding
@@ -173,6 +221,11 @@ export function registerTaskExecutionHandlers(
         // XState says plan_review - send PLAN_APPROVED
         console.warn('[TASK_START] XState: plan_review -> coding via PLAN_APPROVED');
         taskStateManager.handleUiEvent(taskId, { type: 'PLAN_APPROVED' }, task, project);
+      } else if (currentXState === 'error' && !planHasSubtasks) {
+        // FIX (#1562): Task crashed during planning (no subtasks yet).
+        // Uses planHasSubtasks from implementation_plan.json (more reliable than task.subtasks.length).
+        console.warn('[TASK_START] XState: error with no plan subtasks -> planning via PLANNING_STARTED');
+        taskStateManager.handleUiEvent(taskId, { type: 'PLANNING_STARTED' }, task, project);
       } else if (currentXState === 'human_review' || currentXState === 'error') {
         // XState says human_review or error - send USER_RESUMED
         console.warn('[TASK_START] XState:', currentXState, '-> coding via USER_RESUMED');
@@ -186,6 +239,11 @@ export function registerTaskExecutionHandlers(
         // No XState actor - fallback to task data (e.g., after app restart)
         console.warn('[TASK_START] No XState actor, task data: plan_review -> coding via PLAN_APPROVED');
         taskStateManager.handleUiEvent(taskId, { type: 'PLAN_APPROVED' }, task, project);
+      } else if (task.status === 'error' && !planHasSubtasks) {
+        // FIX (#1562): No XState actor, task crashed during planning (no subtasks).
+        // Uses planHasSubtasks from implementation_plan.json (more reliable than task.subtasks.length).
+        console.warn('[TASK_START] No XState actor, error with no plan subtasks -> planning via PLANNING_STARTED');
+        taskStateManager.handleUiEvent(taskId, { type: 'PLANNING_STARTED' }, task, project);
       } else if (task.status === 'human_review' || task.status === 'error') {
         // No XState actor - fallback to task data for resuming
         console.warn('[TASK_START] No XState actor, task data:', task.status, '-> coding via USER_RESUMED');
@@ -205,24 +263,27 @@ export function registerTaskExecutionHandlers(
       }
 
       // Start file watcher for this task
-      const specsBaseDir = getSpecsDir(project.autoBuildPath);
-      const specDir = path.join(
-        project.path,
-        specsBaseDir,
-        task.specId
-      );
-      fileWatcher.watch(taskId, specDir);
+      // Use worktree path if it exists, since the backend writes implementation_plan.json there
+      const watchSpecDir = getSpecDirForWatcher(project.path, specsBaseDir, task.specId);
+      fileWatcher.watch(taskId, watchSpecDir).catch((err) => {
+        console.error(`[TASK_START] Failed to watch spec dir for ${taskId}:`, err);
+      });
 
       // Check if spec.md exists (indicates spec creation was already done or in progress)
+      // Check main project path for spec file (spec is created before worktree)
       const specFilePath = path.join(specDir, AUTO_BUILD_PATHS.SPEC_FILE);
       const hasSpec = existsSync(specFilePath);
 
       // Check if this task needs spec creation first (no spec file = not yet created)
       // OR if it has a spec but no implementation plan subtasks (spec created, needs planning/building)
       const needsSpecCreation = !hasSpec;
-      const needsImplementation = hasSpec && task.subtasks.length === 0;
+      // FIX (#1562): Check actual plan file for subtasks, not just task.subtasks.length.
+      // When a task crashes during planning, it may have spec.md but an empty/missing
+      // implementation_plan.json. Previously, this path would call startTaskExecution
+      // (run.py) which expects subtasks to exist. Now we check the actual plan file.
+      const needsImplementation = hasSpec && !planHasSubtasks;
 
-      console.warn('[TASK_START] hasSpec:', hasSpec, 'needsSpecCreation:', needsSpecCreation, 'needsImplementation:', needsImplementation);
+      console.warn('[TASK_START] hasSpec:', hasSpec, 'planHasSubtasks:', planHasSubtasks, 'needsSpecCreation:', needsSpecCreation, 'needsImplementation:', needsImplementation);
 
       // Get base branch: task-level override takes precedence over project settings
       const baseBranch = task.metadata?.baseBranch || project.settings?.mainBranch;
@@ -237,18 +298,12 @@ export function registerTaskExecutionHandlers(
         // Also pass baseBranch so worktrees are created from the correct branch
         agentManager.startSpecCreation(taskId, project.path, taskDescription, specDir, task.metadata, baseBranch, project.id);
       } else if (needsImplementation) {
-        // Spec exists but no subtasks - run run.py to create implementation plan and execute
-        // Read the spec.md to get the task description
-        const _taskDescription = task.description || task.title;
-        try {
-          readFileSync(specFilePath, 'utf-8');
-        } catch {
-          // Use default description
-        }
-
-        console.warn('[TASK_START] Starting task execution (no subtasks) for:', task.specId);
-        // Start task execution which will create the implementation plan
-        // Note: No parallel mode for planning phase - parallel only makes sense with multiple subtasks
+        // Spec exists but no valid subtasks in implementation plan
+        // FIX (#1562): Use startTaskExecution (run.py) which will create the planner
+        // agent session to generate the implementation plan. run.py handles the case
+        // where implementation_plan.json is missing or has no subtasks - the planner
+        // agent will generate the plan before the coder starts.
+        console.warn('[TASK_START] Starting task execution (no valid subtasks in plan) for:', task.specId);
         agentManager.startTaskExecution(
           taskId,
           project.path,
@@ -289,25 +344,17 @@ export function registerTaskExecutionHandlers(
    */
   ipcMain.on(IPC_CHANNELS.TASK_STOP, (_, taskId: string) => {
     agentManager.killTask(taskId);
-    fileWatcher.unwatch(taskId);
+    fileWatcher.unwatch(taskId).catch((err) => {
+      console.error('[TASK_STOP] Failed to unwatch:', err);
+    });
 
     // Find task and project to emit USER_STOPPED with plan context
     const { task, project } = findTaskAndProject(taskId);
 
     if (!task || !project) return;
 
-    let hasPlan = false;
-    try {
-      const planPath = getPlanPath(project, task);
-      const planContent = safeReadFileSync(planPath);
-      if (planContent) {
-        const plan = JSON.parse(planContent);
-        const { totalCount } = checkSubtasksCompletion(plan);
-        hasPlan = totalCount > 0;
-      }
-    } catch {
-      hasPlan = false;
-    }
+    // Use shared utility to determine if a valid implementation plan exists
+    const hasPlan = hasPlanWithSubtasks(project, task);
 
     taskStateManager.handleUiEvent(
       taskId,
@@ -315,6 +362,9 @@ export function registerTaskExecutionHandlers(
       task,
       project
     );
+
+    // Clear stale tracking state so a subsequent restart works correctly
+    taskStateManager.prepareForRestart(taskId);
   });
 
   /**
@@ -484,6 +534,9 @@ export function registerTaskExecutionHandlers(
           return { success: false, error: 'Failed to write QA fix request file' };
         }
 
+        // Clear stale tracking state before starting new QA process
+        taskStateManager.prepareForRestart(taskId);
+
         // Restart QA process - use worktree path if it exists, otherwise main project
         // The QA process needs to run where the implementation_plan.json with completed subtasks is
         const qaProjectPath = hasWorktree ? worktreePath : project.path;
@@ -513,7 +566,7 @@ export function registerTaskExecutionHandlers(
       _,
       taskId: string,
       status: TaskStatus,
-      options?: { forceCleanup?: boolean }
+      options?: { forceCleanup?: boolean; keepWorktree?: boolean }
     ): Promise<IPCResult & { worktreeExists?: boolean; worktreePath?: string }> => {
       // Find task and project first (needed for worktree check)
       const { task, project } = findTaskAndProject(taskId);
@@ -525,13 +578,17 @@ export function registerTaskExecutionHandlers(
       // Validate status transition - 'done' can only be set through merge handler
       // UNLESS there's no worktree (limbo state - already merged/discarded or failed)
       // OR forceCleanup is requested (user confirmed they want to delete the worktree)
+      // OR keepWorktree is requested (user wants to mark done without deleting worktree)
       if (status === 'done') {
         // Check if worktree exists (task.specId matches worktree folder name)
         const worktreePath = findTaskWorktree(project.path, task.specId);
         const hasWorktree = worktreePath !== null;
 
         if (hasWorktree) {
-          if (options?.forceCleanup) {
+          if (options?.keepWorktree) {
+            // User explicitly chose to keep worktree - allow marking as done
+            console.warn(`[TASK_UPDATE_STATUS] Marking task ${taskId} as done while keeping worktree at ${worktreePath}`);
+          } else if (options?.forceCleanup) {
             // User confirmed cleanup - delete worktree and branch
             console.warn(`[TASK_UPDATE_STATUS] Cleaning up worktree for task ${taskId} (user confirmed)`);
             try {
@@ -658,6 +715,8 @@ export function registerTaskExecutionHandlers(
 
         // Auto-start task when status changes to 'in_progress' and no process is running
         if (status === 'in_progress' && !agentManager.isRunning(taskId)) {
+          // Clear stale tracking state before starting a new process
+          taskStateManager.prepareForRestart(taskId);
           const mainWindow = getMainWindow();
 
           // Check git status before auto-starting
@@ -702,6 +761,10 @@ export function registerTaskExecutionHandlers(
 
           console.warn('[TASK_UPDATE_STATUS] Auto-starting task:', taskId);
 
+          // Cancel any pending fallback timer from previous process exit
+          // This prevents the stale timer from incorrectly stopping the newly started task
+          cancelFallbackTimer(taskId);
+
           // Reset any stuck subtasks before starting execution
           // This handles recovery from previous rate limits or crashes
           const resetResult = await resetStuckSubtasks(planPath, project.id);
@@ -710,13 +773,29 @@ export function registerTaskExecutionHandlers(
           }
 
           // Start file watcher for this task
-          fileWatcher.watch(taskId, specDir);
+          // Use worktree path if it exists, since the backend writes implementation_plan.json there
+          const watchSpecDir = getSpecDirForWatcher(project.path, specsBaseDir, task.specId);
+          fileWatcher.watch(taskId, watchSpecDir).catch((err) => {
+            console.error(`[TASK_UPDATE_STATUS] Failed to watch spec dir for ${taskId}:`, err);
+          });
 
           // Check if spec.md exists
           const specFilePath = path.join(specDir, AUTO_BUILD_PATHS.SPEC_FILE);
           const hasSpec = existsSync(specFilePath);
           const needsSpecCreation = !hasSpec;
-          const needsImplementation = hasSpec && task.subtasks.length === 0;
+          // FIX (#1562): Check actual plan file for subtasks, not just task.subtasks.length
+          const updatePlanFilePath = path.join(specDir, AUTO_BUILD_PATHS.IMPLEMENTATION_PLAN);
+          let updatePlanHasSubtasks = false;
+          const updatePlanContent = safeReadFileSync(updatePlanFilePath);
+          if (updatePlanContent) {
+            try {
+              const plan = JSON.parse(updatePlanContent);
+              updatePlanHasSubtasks = checkSubtasksCompletion(plan).totalCount > 0;
+            } catch {
+              // Invalid/corrupt plan file - treat as no subtasks
+            }
+          }
+          const needsImplementation = hasSpec && !updatePlanHasSubtasks;
 
           console.warn('[TASK_UPDATE_STATUS] hasSpec:', hasSpec, 'needsSpecCreation:', needsSpecCreation, 'needsImplementation:', needsImplementation);
 
@@ -1062,14 +1141,64 @@ export function registerTaskExecutionHandlers(
           }
 
           console.log(`[Recovery] Total ${totalResetCount} subtask(s) reset across all locations`);
+
+          // Clear attempt_history.json to break infinite recovery loops.
+          // Without this, the backend re-reads stuck markers from attempt_history
+          // and immediately re-stucks the same subtasks after recovery.
+          const specDirsToClean = new Set<string>([specDir]);
+          if (mainSpecDir !== specDir) specDirsToClean.add(mainSpecDir);
+          if (worktreeSpecDir && worktreeSpecDir !== specDir) specDirsToClean.add(worktreeSpecDir);
+
+          for (const dir of specDirsToClean) {
+            const attemptHistoryPath = path.join(dir, 'memory', 'attempt_history.json');
+            const historyContent = safeReadFileSync(attemptHistoryPath);
+            if (!historyContent) continue;
+
+            try {
+              const history = JSON.parse(historyContent);
+
+              // Collect stuck subtask IDs before clearing
+              const stuckIds = new Set<string>(
+                (history.stuck_subtasks || [])
+                  .map((s: { subtask_id?: string }) => s.subtask_id)
+                  .filter((id: string | undefined): id is string => Boolean(id))
+              );
+
+              // Clear stuck_subtasks array
+              history.stuck_subtasks = [];
+
+              // Reset attempt entries for previously-stuck subtasks
+              if (history.subtasks && stuckIds.size > 0) {
+                for (const stuckId of stuckIds) {
+                  if (history.subtasks[stuckId]) {
+                    history.subtasks[stuckId] = { attempts: [], status: 'pending' };
+                  }
+                }
+              }
+
+              history.metadata = {
+                ...history.metadata,
+                last_updated: new Date().toISOString()
+              };
+
+              writeFileAtomicSync(attemptHistoryPath, JSON.stringify(history, null, 2));
+              console.log(`[Recovery] Cleared attempt_history.json at: ${dir} (reset ${stuckIds.size} stuck entries)`);
+            } catch (historyErr) {
+              console.warn(`[Recovery] Could not parse attempt_history at ${dir}:`, historyErr);
+            }
+          }
         }
 
         // Stop file watcher if it was watching this task
-        fileWatcher.unwatch(taskId);
+        fileWatcher.unwatch(taskId).catch((err) => {
+          console.error('[TASK_RECOVER_STUCK] Failed to unwatch:', err);
+        });
 
         // Auto-restart the task if requested
         let autoRestarted = false;
         if (autoRestart) {
+          // Clear stale tracking state before restarting
+          taskStateManager.prepareForRestart(taskId);
           // Check git status before auto-restarting
           const gitStatusForRestart = checkGitStatus(project.path);
           if (!gitStatusForRestart.isGitRepo || !gitStatusForRestart.hasCommits) {
@@ -1120,6 +1249,10 @@ export function registerTaskExecutionHandlers(
           }
 
           try {
+            // Cancel any pending fallback timer from previous process exit
+            // This prevents the stale timer from incorrectly stopping the restarted task
+            cancelFallbackTimer(taskId);
+
             // Set status to in_progress for the restart
             newStatus = 'in_progress';
 
@@ -1146,12 +1279,16 @@ export function registerTaskExecutionHandlers(
 
             // Start the task execution
             // Start file watcher for this task
-            const specsBaseDir = getSpecsDir(project.autoBuildPath);
-            const specDirForWatcher = path.join(project.path, specsBaseDir, task.specId);
-            fileWatcher.watch(taskId, specDirForWatcher);
+            // Use worktree path if it exists, since the backend writes implementation_plan.json there
+            const watchSpecDir = getSpecDirForWatcher(project.path, specsBaseDir, task.specId);
+            fileWatcher.watch(taskId, watchSpecDir).catch((err) => {
+              console.error(`[Recovery] Failed to watch spec dir for ${taskId}:`, err);
+            });
 
             // Check if spec.md exists to determine whether to run spec creation or task execution
-            const specFilePath = path.join(specDirForWatcher, AUTO_BUILD_PATHS.SPEC_FILE);
+            // Check main project path for spec file (spec is created before worktree)
+            // mainSpecDir is declared earlier in the handler scope
+            const specFilePath = path.join(mainSpecDir, AUTO_BUILD_PATHS.SPEC_FILE);
             const hasSpec = existsSync(specFilePath);
             const needsSpecCreation = !hasSpec;
 
@@ -1162,7 +1299,7 @@ export function registerTaskExecutionHandlers(
               // No spec file - need to run spec_runner.py to create the spec
               const taskDescription = task.description || task.title;
               console.warn(`[Recovery] Starting spec creation for: ${task.specId}`);
-              agentManager.startSpecCreation(taskId, project.path, taskDescription, specDirForWatcher, task.metadata, baseBranchForRecovery, project.id);
+              agentManager.startSpecCreation(taskId, project.path, taskDescription, mainSpecDir, task.metadata, baseBranchForRecovery, project.id);
             } else {
               // Spec exists - run task execution
               console.warn(`[Recovery] Starting task execution for: ${task.specId}`);

apps/frontend/src/main/ipc-handlers/task/plan-file-utils.ts

@@ -538,3 +538,30 @@ export function updateTaskMetadataPrUrl(metadataPath: string, prUrl: string): bo
     return false;
   }
 }
+
+/**
+ * Check if a task has a valid implementation plan with subtasks.
+ * A plan is considered valid if it has at least one subtask across all phases.
+ *
+ * @param project - The project containing the task
+ * @param task - The task to check
+ * @returns true if the task has a valid plan with subtasks, false otherwise
+ */
+export function hasPlanWithSubtasks(project: Project, task: Task): boolean {
+  try {
+    const planPath = getPlanPath(project, task);
+    const planContent = readFileSync(planPath, 'utf-8');
+    if (!planContent) {
+      return false;
+    }
+
+    const plan = JSON.parse(planContent);
+    // A plan exists if it has phases with subtasks (totalCount > 0)
+    const phases = plan.phases as Array<{ subtasks?: Array<unknown> }> | undefined;
+    const totalCount = phases?.flatMap(p => p.subtasks || []).length || 0;
+    return totalCount > 0;
+  } catch {
+    // File doesn't exist or is malformed
+    return false;
+  }
+}

apps/frontend/src/main/ipc-handlers/task/worktree-handlers.ts

@@ -1370,7 +1370,9 @@ function getTaskBaseBranch(specDir: string): string | undefined {
       if (metadata.baseBranch &&
           metadata.baseBranch !== '__project_default__' &&
           GIT_BRANCH_REGEX.test(metadata.baseBranch)) {
-        return metadata.baseBranch;
+        // Strip remote prefix if present (e.g., "origin/feat/x" → "feat/x")
+        const branch = metadata.baseBranch.replace(/^origin\//, '');
+        return branch;
       }
     }
   } catch (e) {

apps/frontend/src/main/ipc-handlers/terminal-handlers.ts

@@ -252,6 +252,8 @@ export function registerTerminalHandlers(
             id: string;
             sessionId?: string;
             sessionMigrated?: boolean;
+            isClaudeMode?: boolean;
+            dangerouslySkipPermissions?: boolean;
           }> = [];
 
           // Process each terminal
@@ -273,7 +275,7 @@ export function registerTerminalHandlers(
                 to: targetConfigDir
               });
 
-              const migrationResult = migrateSession(
+              const migrationResult = await migrateSession(
                 sourceConfigDir,
                 targetConfigDir,
                 terminal.cwd,
@@ -284,11 +286,19 @@ export function registerTerminalHandlers(
               debugLog('[terminal-handlers:CLAUDE_PROFILE_SET_ACTIVE] Session migration result:', migrationResult);
             }
 
+            // Store YOLO mode flag server-side for migrated sessions
+            // (consumed by resumeClaudeAsync when the new terminal resumes)
+            if (sessionMigrated && terminal.claudeSessionId && terminal.dangerouslySkipPermissions) {
+              terminalManager.storeMigratedSessionFlag(terminal.claudeSessionId, terminal.dangerouslySkipPermissions);
+            }
+
             // All terminals need refresh (PTY env vars can't be updated)
             terminalsNeedingRefresh.push({
               id: terminal.id,
               sessionId: terminal.claudeSessionId,
-              sessionMigrated
+              sessionMigrated,
+              isClaudeMode: terminal.isClaudeMode,
+              dangerouslySkipPermissions: terminal.dangerouslySkipPermissions
             });
           }
 
@@ -613,9 +623,9 @@ export function registerTerminalHandlers(
 
   ipcMain.on(
     IPC_CHANNELS.TERMINAL_RESUME_CLAUDE,
-    (_, id: string, sessionId?: string) => {
+    (_, id: string, sessionId?: string, options?: { migratedSession?: boolean }) => {
       // Use async version to avoid blocking main process during CLI detection
-      terminalManager.resumeClaudeAsync(id, sessionId).catch((error) => {
+      terminalManager.resumeClaudeAsync(id, sessionId, options).catch((error) => {
         console.warn('[terminal-handlers] Failed to resume Claude:', error);
       });
     }

apps/frontend/src/main/ipc-handlers/terminal/worktree-handlers.ts

@@ -8,7 +8,7 @@ import type {
   OtherWorktreeInfo,
 } from '../../../shared/types';
 import path from 'path';
-import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync, symlinkSync, lstatSync, copyFileSync, cpSync, statSync } from 'fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, rmSync, symlinkSync, lstatSync, copyFileSync, cpSync, statSync, readlinkSync } from 'fs';
 import { execFileSync, execFile } from 'child_process';
 import { promisify } from 'util';
 import { minimatch } from 'minimatch';
@@ -57,6 +57,21 @@ function isTimeoutError(error: unknown): boolean {
   );
 }
 
+/**
+ * Check if a path is a symlink or Windows junction (including broken ones).
+ * Uses readlinkSync which works for both symlinks and junctions on all platforms.
+ */
+function isSymlinkOrJunction(targetPath: string): boolean {
+  try {
+    // readlinkSync throws if the path is not a symlink/junction
+    // It works for both symlinks and junctions on Windows and Unix
+    readlinkSync(targetPath);
+    return true;
+  } catch {
+    return false; // Path doesn't exist or is not a symlink/junction
+  }
+}
+
 /**
  * Fix repositories that are incorrectly marked with core.bare=true.
  * This can happen when git worktree operations incorrectly set bare=true
@@ -250,11 +265,12 @@ interface DependencyConfig {
 const DEFAULT_STRATEGY_MAP: Record<string, 'symlink' | 'recreate' | 'copy' | 'skip'> = {
   // JavaScript / Node.js — symlink is safe and fast
   node_modules: 'symlink',
-  // Python — venvs MUST be recreated, not symlinked.
-  // CPython bug #106045: pyvenv.cfg discovery does not resolve symlinks,
-  // so a symlinked venv resolves paths relative to the target, not the worktree.
-  venv: 'recreate',
-  '.venv': 'recreate',
+  // Python — symlink for fast worktree creation.
+  // CPython bug #106045 (pyvenv.cfg symlink resolution) does not affect
+  // typical usage (running scripts, imports, pip). If the health check
+  // after symlinking fails, we fall back to recreate automatically.
+  venv: 'symlink',
+  '.venv': 'symlink',
   // PHP — Composer vendor dir is safe to symlink
   vendor_php: 'symlink',
   // Ruby — Bundler vendor/bundle is safe to symlink
@@ -364,6 +380,32 @@ async function setupWorktreeDependencies(projectPath: string, worktreePath: stri
       switch (config.strategy) {
         case 'symlink':
           performed = applySymlinkStrategy(projectPath, worktreePath, config);
+          // For venvs, verify the symlink is usable — fall back to recreate if not
+          // Run health check whenever a venv exists (not just on fresh creation)
+          if (config.depType === 'venv' || config.depType === '.venv') {
+            const venvPath = path.join(worktreePath, config.sourceRelPath);
+            // Check if venv path exists (as symlink or otherwise)
+            if (existsSync(venvPath) || isSymlinkOrJunction(venvPath)) {
+              const pythonBin = isWindows()
+                ? path.join(venvPath, 'Scripts', 'python.exe')
+                : path.join(venvPath, 'bin', 'python');
+              try {
+                await execFileAsync(pythonBin, ['-c', 'import sys; print(sys.prefix)'], {
+                  timeout: 10000,
+                });
+                debugLog('[TerminalWorktree] Symlinked venv health check passed:', config.sourceRelPath);
+              } catch {
+                debugLog('[TerminalWorktree] Symlinked venv health check failed, falling back to recreate:', config.sourceRelPath);
+                debugLog('[TerminalWorktree] Venv fallback: removing broken symlink and recreating for', config.sourceRelPath);
+                // Remove the broken symlink and recreate
+                try { rmSync(venvPath, { recursive: true, force: true }); } catch { /* best-effort */ }
+                performed = await applyRecreateStrategy(projectPath, worktreePath, config);
+                if (performed) {
+                  debugLog('[TerminalWorktree] Venv fallback to recreate succeeded:', config.sourceRelPath);
+                }
+              }
+            }
+          }
           break;
         case 'recreate':
           performed = await applyRecreateStrategy(projectPath, worktreePath, config);
@@ -403,13 +445,15 @@ function applySymlinkStrategy(projectPath: string, worktreePath: string, config:
     return false;
   }
 
-  // Check for broken symlinks
-  try {
-    lstatSync(targetPath);
-    debugLog('[TerminalWorktree] Skipping symlink', config.sourceRelPath, '- target exists (possibly broken symlink)');
-    return false;
-  } catch {
-    // Target doesn't exist at all — good, we can create symlink
+  // Check for broken symlinks and remove them so a fresh symlink can be created
+  if (isSymlinkOrJunction(targetPath)) {
+    if (!existsSync(targetPath)) {
+      debugLog('[TerminalWorktree] Removing broken symlink for', config.sourceRelPath);
+      try { rmSync(targetPath, { force: true }); } catch { /* best-effort */ }
+    } else {
+      debugLog('[TerminalWorktree] Skipping symlink', config.sourceRelPath, '- target exists (symlink)');
+      return false;
+    }
   }
 
   const targetDir = path.dirname(targetPath);
@@ -434,19 +478,31 @@ function applySymlinkStrategy(projectPath: string, worktreePath: string, config:
   }
 }
 
+/** Marker file written inside a recreated venv to indicate setup completed successfully. */
+const VENV_SETUP_COMPLETE_MARKER = '.setup_complete';
+
 /**
  * Apply recreate strategy: create a fresh virtual environment in the worktree.
  *
- * Python venvs cannot be symlinked due to CPython bug #106045 — pyvenv.cfg
- * discovery does not resolve symlinks, so paths resolve relative to the
- * symlink target instead of the worktree.
+ * Used as a fallback when venv symlinking fails (CPython bug #106045).
+ * Writes a completion marker so incomplete venvs can be detected and rebuilt.
  */
 async function applyRecreateStrategy(projectPath: string, worktreePath: string, config: DependencyConfig): Promise<boolean> {
   const venvPath = path.join(worktreePath, config.sourceRelPath);
+  const markerPath = path.join(venvPath, VENV_SETUP_COMPLETE_MARKER);
 
-  if (existsSync(venvPath)) {
-    debugLog('[TerminalWorktree] Skipping recreate', config.sourceRelPath, '- already exists');
-    return false;
+  // Check for broken symlinks that existsSync would miss
+  if (isSymlinkOrJunction(venvPath) && !existsSync(venvPath)) {
+    debugLog('[TerminalWorktree] Removing broken symlink at', config.sourceRelPath);
+    try { rmSync(venvPath, { recursive: true, force: true }); } catch { /* best-effort */ }
+  } else if (existsSync(venvPath)) {
+    if (existsSync(markerPath)) {
+      debugLog('[TerminalWorktree] Skipping recreate', config.sourceRelPath, '- already complete (marker present)');
+      return false;
+    }
+    // Venv exists but marker is missing — incomplete, remove and rebuild
+    debugLog('[TerminalWorktree] Removing incomplete venv', config.sourceRelPath, '(no marker)');
+    try { rmSync(venvPath, { recursive: true, force: true }); } catch { /* best-effort */ }
   }
 
   // Detect Python executable from the source venv or fall back to system Python
@@ -514,7 +570,7 @@ async function applyRecreateStrategy(projectPath: string, worktreePath: string,
           debugLog('[TerminalWorktree] Installing deps from', config.requirementsFile);
           await execFileAsync(pipExec, installArgs, {
             encoding: 'utf-8',
-            timeout: 120000,
+            timeout: 300000,
           });
         } catch (error) {
           if (isTimeoutError(error)) {
@@ -533,6 +589,13 @@ async function applyRecreateStrategy(projectPath: string, worktreePath: string,
     }
   }
 
+  // Write completion marker so future runs know this venv is complete
+  try {
+    writeFileSync(markerPath, '');
+  } catch (error) {
+    debugLog('[TerminalWorktree] Failed to write completion marker at', markerPath, ':', error);
+  }
+
   debugLog('[TerminalWorktree] Recreated venv at', config.sourceRelPath);
   return true;
 }

apps/frontend/src/main/pr-review-state-manager.ts

@@ -0,0 +1,217 @@
+import { createActor } from 'xstate';
+import type { ActorRefFrom } from 'xstate';
+import type { BrowserWindow } from 'electron';
+import { prReviewMachine, type PRReviewEvent, type PRReviewContext } from '../shared/state-machines';
+import type { PRReviewProgress, PRReviewResult, PRReviewStatePayload } from '../preload/api/modules/github-api';
+import { IPC_CHANNELS } from '../shared/constants';
+import { safeSendToRenderer } from './ipc-handlers/utils';
+
+type PRReviewActor = ActorRefFrom<typeof prReviewMachine>;
+
+/**
+ * Build a deduplication key from snapshot state + relevant context fields.
+ * PR reviews need to emit even when state stays the same but context changes
+ * (e.g., progress updates within 'reviewing' state).
+ */
+function buildContextKey(snapshot: { context: PRReviewContext }): string {
+  const ctx = snapshot.context;
+  const progressKey = ctx.progress
+    ? `${ctx.progress.phase}:${ctx.progress.progress}:${ctx.progress.message}`
+    : 'none';
+  const resultKey = ctx.result ? ctx.result.overallStatus : 'none';
+  const errorKey = ctx.error ?? 'none';
+  return `${progressKey}|${resultKey}|${errorKey}`;
+}
+
+export class PRReviewStateManager {
+  private actors = new Map<string, PRReviewActor>();
+  private lastStateByPR = new Map<string, string>();
+  private getMainWindow: () => BrowserWindow | null;
+
+  constructor(getMainWindow: () => BrowserWindow | null) {
+    this.getMainWindow = getMainWindow;
+  }
+
+  handleStartReview(projectId: string, prNumber: number): void {
+    const actor = this.getOrCreateActor(projectId, prNumber);
+    actor.send({ type: 'START_REVIEW', prNumber, projectId } satisfies PRReviewEvent);
+  }
+
+  handleStartFollowupReview(projectId: string, prNumber: number, previousResult?: PRReviewResult): void {
+    const actor = this.getOrCreateActor(projectId, prNumber);
+    if (previousResult) {
+      actor.send({ type: 'START_FOLLOWUP_REVIEW', prNumber, projectId, previousResult } satisfies PRReviewEvent);
+    } else {
+      actor.send({ type: 'START_REVIEW', prNumber, projectId } satisfies PRReviewEvent);
+    }
+  }
+
+  handleProgress(projectId: string, prNumber: number, progress: PRReviewProgress): void {
+    const actor = this.getActor(projectId, prNumber);
+    if (!actor) return;
+    actor.send({ type: 'SET_PROGRESS', progress } satisfies PRReviewEvent);
+  }
+
+  handleComplete(projectId: string, prNumber: number, result: PRReviewResult): void {
+    // Use getOrCreateActor so late-arriving results (e.g. after auth change or
+    // app restart) still get processed instead of silently dropped.
+    const actor = this.getOrCreateActor(projectId, prNumber);
+
+    // If the actor is in idle state (freshly created for a late-arriving result),
+    // transition to reviewing first so REVIEW_COMPLETE is accepted.
+    const snapshot = actor.getSnapshot();
+    if (String(snapshot.value) === 'idle') {
+      actor.send({ type: 'START_REVIEW', prNumber, projectId } satisfies PRReviewEvent);
+    }
+
+    // Detect external review (result arrives with 'in_progress' status from outside)
+    if (result.overallStatus === 'in_progress') {
+      actor.send({ type: 'DETECT_EXTERNAL_REVIEW' } satisfies PRReviewEvent);
+    } else {
+      actor.send({ type: 'REVIEW_COMPLETE', result } satisfies PRReviewEvent);
+    }
+  }
+
+  handleError(projectId: string, prNumber: number, error: string): void {
+    const actor = this.getActor(projectId, prNumber);
+    if (!actor) return;
+    actor.send({ type: 'REVIEW_ERROR', error } satisfies PRReviewEvent);
+  }
+
+  handleCancel(projectId: string, prNumber: number): void {
+    const actor = this.getActor(projectId, prNumber);
+    if (!actor) return;
+    actor.send({ type: 'CANCEL_REVIEW' } satisfies PRReviewEvent);
+  }
+
+  handleClearReview(projectId: string, prNumber: number): void {
+    const key = this.getKey(projectId, prNumber);
+    const actor = this.actors.get(key);
+    if (actor) {
+      // Capture snapshot before stopping so the emitted payload has real context.
+      // Don't send CLEAR_REVIEW to the actor — that would trigger the subscription
+      // and cause a duplicate IPC emission alongside emitClearedState below.
+      const snapshot = actor.getSnapshot();
+      actor.stop();
+      this.actors.delete(key);
+      this.emitClearedState(key, snapshot?.context ?? null);
+    }
+    this.lastStateByPR.delete(key);
+  }
+
+  handleAuthChange(): void {
+    for (const [key, actor] of this.actors) {
+      // Capture the last known snapshot before stopping so the emitted payload
+      // contains the real projectId/prNumber instead of zeros.
+      const snapshot = actor.getSnapshot();
+      actor.stop();
+      // Emit cleared (idle) state to renderer for each PR
+      this.emitClearedState(key, snapshot?.context ?? null);
+    }
+    this.actors.clear();
+    this.lastStateByPR.clear();
+  }
+
+  getState(projectId: string, prNumber: number): ReturnType<PRReviewActor['getSnapshot']> | null {
+    const actor = this.getActor(projectId, prNumber);
+    if (!actor) return null;
+    return actor.getSnapshot();
+  }
+
+  clearAll(): void {
+    for (const [, actor] of this.actors) {
+      actor.stop();
+    }
+    this.actors.clear();
+    this.lastStateByPR.clear();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private
+  // ---------------------------------------------------------------------------
+
+  private getOrCreateActor(projectId: string, prNumber: number): PRReviewActor {
+    const key = this.getKey(projectId, prNumber);
+    const existing = this.actors.get(key);
+    if (existing) return existing;
+
+    const actor = createActor(prReviewMachine);
+
+    actor.subscribe((snapshot) => {
+      const stateValue = String(snapshot.value);
+      const contextKey = buildContextKey(snapshot);
+      const currentKey = `${stateValue}:${contextKey}`;
+      if (this.lastStateByPR.get(key) === currentKey) return;
+      this.lastStateByPR.set(key, currentKey);
+      this.emitStateToRenderer(key, snapshot);
+    });
+
+    actor.start();
+    this.actors.set(key, actor);
+    return actor;
+  }
+
+  private getActor(projectId: string, prNumber: number): PRReviewActor | null {
+    return this.actors.get(this.getKey(projectId, prNumber)) ?? null;
+  }
+
+  private getKey(projectId: string, prNumber: number): string {
+    return `${projectId}:${prNumber}`;
+  }
+
+  private emitStateToRenderer(
+    key: string,
+    snapshot: ReturnType<PRReviewActor['getSnapshot']> | null
+  ): void {
+    const stateValue = snapshot ? String(snapshot.value) : 'idle';
+    const ctx = snapshot?.context ?? null;
+
+    const payload: PRReviewStatePayload = {
+      state: stateValue,
+      prNumber: ctx?.prNumber ?? 0,
+      projectId: ctx?.projectId ?? '',
+      isReviewing: stateValue === 'reviewing' || stateValue === 'externalReview',
+      startedAt: ctx?.startedAt ?? null,
+      progress: ctx?.progress ?? null,
+      result: ctx?.result ?? null,
+      previousResult: ctx?.previousResult ?? null,
+      error: ctx?.error ?? null,
+      isExternalReview: ctx?.isExternalReview ?? false,
+      isFollowup: ctx?.isFollowup ?? false,
+    };
+
+    safeSendToRenderer(
+      this.getMainWindow,
+      IPC_CHANNELS.GITHUB_PR_REVIEW_STATE_CHANGE,
+      key,
+      payload
+    );
+  }
+
+  /**
+   * Emit a cleared (idle) state using context from the last snapshot
+   * so the payload contains the real projectId/prNumber.
+   */
+  private emitClearedState(key: string, ctx: PRReviewContext | null): void {
+    const payload: PRReviewStatePayload = {
+      state: 'idle',
+      prNumber: ctx?.prNumber ?? 0,
+      projectId: ctx?.projectId ?? '',
+      isReviewing: false,
+      startedAt: null,
+      progress: null,
+      result: null,
+      previousResult: null,
+      error: null,
+      isExternalReview: false,
+      isFollowup: false,
+    };
+
+    safeSendToRenderer(
+      this.getMainWindow,
+      IPC_CHANNELS.GITHUB_PR_REVIEW_STATE_CHANGE,
+      key,
+      payload
+    );
+  }
+}

apps/frontend/src/main/python-env-manager.ts

@@ -6,6 +6,7 @@ import { app } from 'electron';
 import { findPythonCommand, getBundledPythonPath } from './python-detector';
 import { isLinux, isWindows, getPathDelimiter } from './platform';
 import { getIsolatedGitEnv } from './utils/git-isolation';
+import { normalizeEnvPathKey } from './agent/env-utils';
 
 export interface PythonEnvStatus {
   ready: boolean;
@@ -726,17 +727,10 @@ if sys.version_info >= (3, 12):
       const pywin32System32 = path.join(this.sitePackagesPath, 'pywin32_system32');
 
       // Add pywin32_system32 to PATH for DLL loading
-      // Fix PATH case sensitivity: On Windows, env vars are case-insensitive but Node.js
-      // preserves case. If we have both 'PATH' and 'Path', Node.js lexicographically sorts
-      // and uses the first match, causing issues. Normalize to single 'PATH' key.
-      // See: https://github.com/nodejs/node/issues/9157
-      const pathKey = Object.keys(baseEnv).find(k => k.toUpperCase() === 'PATH');
-      const currentPath = pathKey ? baseEnv[pathKey] : '';
-
-      // Remove any existing PATH variants to avoid duplicates
-      if (pathKey && pathKey !== 'PATH') {
-        delete baseEnv[pathKey];
-      }
+      // Normalize to single 'PATH' key before reading/writing, using the shared utility.
+      // This prevents duplicate 'Path'/'PATH' keys that cause DLL-load failures on Windows.
+      normalizeEnvPathKey(baseEnv);
+      const currentPath = baseEnv['PATH'] ?? '';
 
       if (currentPath && !currentPath.includes(pywin32System32)) {
         windowsEnv['PATH'] = `${pywin32System32};${currentPath}`;

apps/frontend/src/main/task-state-manager.ts

@@ -169,6 +169,18 @@ export class TaskStateManager {
     return this.getCurrentState(taskId) === 'plan_review';
   }
 
+  /**
+   * Reset tracking state for a task that is about to be restarted.
+   * Clears terminalEventSeen (so process exits aren't swallowed) and
+   * lastSequenceByTask (so events from the new process aren't dropped
+   * as duplicates). Does NOT stop or remove the XState actor, since
+   * the caller may still need to send events to it.
+   */
+  prepareForRestart(taskId: string): void {
+    this.terminalEventSeen.delete(taskId);
+    this.lastSequenceByTask.delete(taskId);
+  }
+
   clearTask(taskId: string): void {
     this.lastSequenceByTask.delete(taskId);
     this.lastStateByTask.delete(taskId);

apps/frontend/src/main/terminal-session-store.ts

@@ -195,8 +195,20 @@ export class TerminalSessionStore {
    * 1. Write to temp file
    * 2. Rotate current file to backup
    * 3. Rename temp to target (atomic on most filesystems)
+   *
+   * If an async write is in progress, defers to the async writer to avoid
+   * both operations competing for the same temp file (ENOENT race condition).
    */
   private save(): void {
+    // If an async write is in progress, don't write synchronously — the async
+    // writer shares the same temp file path. Instead, mark a pending write so
+    // saveAsync() will re-save with the latest in-memory data when it finishes.
+    if (this.writeInProgress) {
+      this.writePending = true;
+      debugLog('[TerminalSessionStore] Deferring sync save — async write in progress');
+      return;
+    }
+
     try {
       const content = JSON.stringify(this.data, null, 2);
 
@@ -366,7 +378,9 @@ export class TerminalSessionStore {
   private updateSessionInMemory(session: TerminalSession): boolean {
     // Check if session was deleted - skip if pending deletion
     if (this.pendingDelete.has(session.id)) {
-      console.warn('[TerminalSessionStore] Skipping save for deleted session:', session.id);
+      debugLog('[TerminalSessionStore] Skipping save for deleted session:', session.id,
+        'pendingDelete size:', this.pendingDelete.size,
+        'all pending IDs:', [...this.pendingDelete].join(', '));
       return false;
     }
 
@@ -596,6 +610,27 @@ export class TerminalSessionStore {
     return sessions.find(s => s.id === sessionId);
   }
 
+  /**
+   * Clear a session ID from pendingDelete, allowing saves to proceed.
+   *
+   * Called when a terminal is legitimately re-created with the same ID
+   * (e.g., worktree switching, terminal restart after exit). Without this,
+   * the 5-second pendingDelete window blocks session persistence for the
+   * new terminal.
+   */
+  clearPendingDelete(sessionId: string): void {
+    if (this.pendingDelete.has(sessionId)) {
+      this.pendingDelete.delete(sessionId);
+      // Also clear the cleanup timer since we're explicitly clearing
+      const timer = this.pendingDeleteTimers.get(sessionId);
+      if (timer) {
+        clearTimeout(timer);
+        this.pendingDeleteTimers.delete(sessionId);
+      }
+      debugLog('[TerminalSessionStore] Cleared pendingDelete for re-created terminal:', sessionId);
+    }
+  }
+
   /**
    * Remove a session (from today's sessions)
    *
@@ -606,6 +641,9 @@ export class TerminalSessionStore {
     // Mark as pending delete BEFORE modifying data to prevent race condition
     // with in-flight saveSessionAsync() calls
     this.pendingDelete.add(sessionId);
+    debugLog('[TerminalSessionStore] removeSession: added to pendingDelete:', sessionId,
+      'pendingDelete size:', this.pendingDelete.size,
+      'all pending IDs:', [...this.pendingDelete].join(', '));
 
     const todaySessions = this.getTodaysSessions();
     if (todaySessions[projectPath]) {
@@ -627,6 +665,8 @@ export class TerminalSessionStore {
     const timer = setTimeout(() => {
       this.pendingDelete.delete(sessionId);
       this.pendingDeleteTimers.delete(sessionId);
+      debugLog('[TerminalSessionStore] Cleanup timer fired for:', sessionId,
+        'removing from pendingDelete. Remaining:', this.pendingDelete.size);
     }, 5000);
     this.pendingDeleteTimers.set(sessionId, timer);
   }

apps/frontend/src/main/terminal/__tests__/claude-integration-handler.test.ts

@@ -109,7 +109,16 @@ function mockPlatform(platform: 'win32' | 'darwin' | 'linux') {
 /**
  * Helper to get platform-specific expectations for PATH prefix
  */
-function getPathPrefixExpectation(platform: 'win32' | 'darwin' | 'linux', pathValue: string): string {
+function getPathPrefixExpectation(
+  platform: 'win32' | 'darwin' | 'linux',
+  pathValue: string,
+  command: string
+): string {
+  // Absolute executable commands no longer need PATH prefix injection.
+  if (path.isAbsolute(command)) {
+    return '';
+  }
+
   if (platform === 'win32') {
     // Windows: set "PATH=value" &&
     return `set "PATH=${pathValue}" && `;
@@ -118,6 +127,20 @@ function getPathPrefixExpectation(platform: 'win32' | 'darwin' | 'linux', pathVa
   return `PATH='${pathValue}' `;
 }
 
+function expectPathPrefix(
+  written: string,
+  platform: 'win32' | 'darwin' | 'linux',
+  pathValue: string,
+  command: string
+): void {
+  const expectedPrefix = getPathPrefixExpectation(platform, pathValue, command);
+  if (expectedPrefix) {
+    expect(written).toContain(expectedPrefix);
+  } else {
+    expect(written).not.toContain('PATH=');
+  }
+}
+
 /**
  * Helper to get platform-specific expectations for command quoting
  */
@@ -241,7 +264,7 @@ describe('claude-integration-handler', () => {
 
       const written = mockWriteToPty.mock.calls[0][1] as string;
       expect(written).toContain(buildCdCommand('/tmp/project'));
-      expect(written).toContain(getPathPrefixExpectation(platform, '/opt/claude/bin:/usr/bin'));
+      expectPathPrefix(written, platform, '/opt/claude/bin:/usr/bin', "/opt/claude bin/claude's");
       expect(written).toContain(getQuotedCommand(platform, "/opt/claude bin/claude's"));
       expect(mockReleaseSessionId).toHaveBeenCalledWith('term-1');
       expect(mockPersistSession).toHaveBeenCalledWith(terminal);
@@ -402,7 +425,7 @@ describe('claude-integration-handler', () => {
 
       expect(written).toContain(histPrefix);
       expect(written).toContain(configDir);
-      expect(written).toContain(getPathPrefixExpectation(platform, '/opt/claude/bin:/usr/bin'));
+      expectPathPrefix(written, platform, '/opt/claude/bin:/usr/bin', command);
       expect(written).toContain(getQuotedCommand(platform, command));
       expect(written).toContain(clearCmd);
       expect(profileManager.getProfile).toHaveBeenCalledWith('prof-2');
@@ -436,7 +459,7 @@ describe('claude-integration-handler', () => {
 
       const written = mockWriteToPty.mock.calls[0][1] as string;
       expect(written).toContain(getQuotedCommand(platform, command));
-      expect(written).toContain(getPathPrefixExpectation(platform, '/opt/claude/bin:/usr/bin'));
+      expectPathPrefix(written, platform, '/opt/claude/bin:/usr/bin', command);
       expect(profileManager.getProfile).toHaveBeenCalledWith('prof-3');
       expect(profileManager.markProfileUsed).toHaveBeenCalledWith('prof-3');
       expect(mockPersistSession).toHaveBeenCalledWith(terminal);
@@ -460,7 +483,7 @@ describe('claude-integration-handler', () => {
       resumeClaude(terminal, 'abc123', () => null);
 
       const resumeCall = mockWriteToPty.mock.calls[0][1] as string;
-      expect(resumeCall).toContain(getPathPrefixExpectation(platform, '/opt/claude/bin:/usr/bin'));
+      expectPathPrefix(resumeCall, platform, '/opt/claude/bin:/usr/bin', '/opt/claude/bin/claude');
       expect(resumeCall).toContain(getQuotedCommand(platform, '/opt/claude/bin/claude') + ' --continue');
       expect(resumeCall).not.toContain('--resume');
       // sessionId is cleared because --continue doesn't track specific sessions
@@ -656,7 +679,7 @@ describe('invokeClaudeAsync', () => {
 
       const written = mockWriteToPty.mock.calls[0][1] as string;
       expect(written).toContain(buildCdCommand('/tmp/project'));
-      expect(written).toContain(getPathPrefixExpectation(platform, '/opt/claude/bin:/usr/bin'));
+      expectPathPrefix(written, platform, '/opt/claude/bin:/usr/bin', '/opt/claude/bin/claude');
       expect(mockReleaseSessionId).toHaveBeenCalledWith('term-1');
       expect(mockPersistSession).toHaveBeenCalledWith(terminal);
       expect(profileManager.markProfileUsed).toHaveBeenCalledWith('default');
@@ -914,7 +937,8 @@ describe('claude-integration-handler - Helper Functions', () => {
       // Use a default terminal name pattern so renaming logic kicks in
       const terminal = createMockTerminal({ title: 'Terminal 1' });
       const mockWindow = {
-        webContents: { send: vi.fn() }
+        isDestroyed: () => false,
+        webContents: { send: vi.fn(), isDestroyed: () => false }
       };
 
       finalizeClaudeInvoke(
@@ -934,7 +958,8 @@ describe('claude-integration-handler - Helper Functions', () => {
       // Use a default terminal name pattern so renaming logic kicks in
       const terminal = createMockTerminal({ title: 'Terminal 2' });
       const mockWindow = {
-        webContents: { send: vi.fn() }
+        isDestroyed: () => false,
+        webContents: { send: vi.fn(), isDestroyed: () => false }
       };
 
       finalizeClaudeInvoke(
@@ -955,7 +980,8 @@ describe('claude-integration-handler - Helper Functions', () => {
       const terminal = createMockTerminal({ title: 'Terminal 3' });
       const mockSend = vi.fn();
       const mockWindow = {
-        webContents: { send: mockSend }
+        isDestroyed: () => false,
+        webContents: { send: mockSend, isDestroyed: () => false }
       };
 
       finalizeClaudeInvoke(
@@ -980,7 +1006,8 @@ describe('claude-integration-handler - Helper Functions', () => {
       const terminal = createMockTerminal({ title: 'Claude' });
       const mockSend = vi.fn();
       const mockWindow = {
-        webContents: { send: mockSend }
+        isDestroyed: () => false,
+        webContents: { send: mockSend, isDestroyed: () => false }
       };
 
       finalizeClaudeInvoke(
@@ -1004,7 +1031,8 @@ describe('claude-integration-handler - Helper Functions', () => {
       const terminal = createMockTerminal({ title: 'My Custom Terminal' });
       const mockSend = vi.fn();
       const mockWindow = {
-        webContents: { send: mockSend }
+        isDestroyed: () => false,
+        webContents: { send: mockSend, isDestroyed: () => false }
       };
 
       finalizeClaudeInvoke(

apps/frontend/src/main/terminal/claude-integration-handler.ts

@@ -16,6 +16,7 @@ import { getEmailFromConfigDir } from '../claude-profile/profile-utils';
 import * as OutputParser from './output-parser';
 import * as SessionHandler from './session-handler';
 import * as PtyManager from './pty-manager';
+import { safeSendToRenderer } from '../ipc-handlers/utils';
 import { debugLog, debugError } from '../../shared/utils/debug-logger';
 import { escapeShellArg, escapeForWindowsDoubleQuote, buildCdCommand } from '../../shared/utils/shell-escape';
 import { getClaudeCliInvocation, getClaudeCliInvocationAsync } from '../claude-cli-utils';
@@ -116,6 +117,19 @@ function normalizePathForBash(envPath: string): string {
   return isWindows() ? envPath.replace(/;/g, ':') : envPath;
 }
 
+/**
+ * Determine whether a command already resolves via an absolute executable path.
+ *
+ * When true, we should avoid prefixing PATH=... into the typed shell command because:
+ * 1) PATH is not needed to locate the executable
+ * 2) very long PATH prefixes create huge echoed command lines that can stress terminal rendering
+ */
+function isAbsoluteExecutableCommand(command: string): boolean {
+  const trimmed = command.trim();
+  if (!trimmed) return false;
+  return path.isAbsolute(trimmed);
+}
+
 /**
  * Generate temp file content for OAuth token based on platform
  *
@@ -380,11 +394,8 @@ export function finalizeClaudeInvoke(
       : 'Claude';
     terminal.title = title;
 
-    // Notify renderer of title change
-    const win = getWindow();
-    if (win) {
-      win.webContents.send(IPC_CHANNELS.TERMINAL_TITLE_CHANGE, terminal.id, title);
-    }
+    // Notify renderer of title change (use safeSendToRenderer to prevent SIGABRT on disposed frame)
+    safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_TITLE_CHANGE, terminal.id, title);
   }
 
   // Persist session if project path is available
@@ -434,18 +445,15 @@ export function handleRateLimit(
   const autoSwitchSettings = profileManager.getAutoSwitchSettings();
   const bestProfile = profileManager.getBestAvailableProfile(currentProfileId);
 
-  const win = getWindow();
-  if (win) {
-    win.webContents.send(IPC_CHANNELS.TERMINAL_RATE_LIMIT, {
-      terminalId: terminal.id,
-      resetTime,
-      detectedAt: new Date().toISOString(),
-      profileId: currentProfileId,
-      suggestedProfileId: bestProfile?.id,
-      suggestedProfileName: bestProfile?.name,
-      autoSwitchEnabled: autoSwitchSettings.autoSwitchOnRateLimit
-    } as RateLimitEvent);
-  }
+  safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_RATE_LIMIT, {
+    terminalId: terminal.id,
+    resetTime,
+    detectedAt: new Date().toISOString(),
+    profileId: currentProfileId,
+    suggestedProfileId: bestProfile?.id,
+    suggestedProfileName: bestProfile?.name,
+    autoSwitchEnabled: autoSwitchSettings.autoSwitchOnRateLimit
+  } as RateLimitEvent);
 
   if (autoSwitchSettings.enabled && autoSwitchSettings.autoSwitchOnRateLimit && bestProfile) {
     console.warn('[ClaudeIntegration] Auto-switching to profile:', bestProfile.name);
@@ -535,19 +543,16 @@ export function handleOAuthToken(
       // Set flag to watch for Claude's ready state (onboarding complete)
       terminal.awaitingOnboardingComplete = true;
 
-      const win = getWindow();
-      if (win) {
-        // needsOnboarding: true tells the UI to show "complete setup" message
-        // instead of "success" - user should finish Claude's onboarding before closing
-        win.webContents.send(IPC_CHANNELS.TERMINAL_OAUTH_TOKEN, {
-          terminalId: terminal.id,
-          profileId,
-          email: emailFromOutput || keychainCreds.email || profile?.email,
-          success: true,
-          needsOnboarding: true,
-          detectedAt: new Date().toISOString()
-        } as OAuthTokenEvent);
-      }
+      // needsOnboarding: true tells the UI to show "complete setup" message
+      // instead of "success" - user should finish Claude's onboarding before closing
+      safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_OAUTH_TOKEN, {
+        terminalId: terminal.id,
+        profileId,
+        email: emailFromOutput || keychainCreds.email || profile?.email,
+        success: true,
+        needsOnboarding: true,
+        detectedAt: new Date().toISOString()
+      } as OAuthTokenEvent);
     } else {
       // Token not in Keychain yet, but profile may still be authenticated via configDir
       // Check if profile has valid auth (credentials exist in configDir)
@@ -559,19 +564,16 @@ export function handleOAuthToken(
         // Set flag to watch for Claude's ready state (onboarding complete)
         terminal.awaitingOnboardingComplete = true;
 
-        const win = getWindow();
-        if (win) {
-          // needsOnboarding: true tells the UI to show "complete setup" message
-          // instead of "success" - user should finish Claude's onboarding before closing
-          win.webContents.send(IPC_CHANNELS.TERMINAL_OAUTH_TOKEN, {
-            terminalId: terminal.id,
-            profileId,
-            email: emailFromOutput || profile?.email,
-            success: true,
-            needsOnboarding: true,
-            detectedAt: new Date().toISOString()
-          } as OAuthTokenEvent);
-        }
+        // needsOnboarding: true tells the UI to show "complete setup" message
+        // instead of "success" - user should finish Claude's onboarding before closing
+        safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_OAUTH_TOKEN, {
+          terminalId: terminal.id,
+          profileId,
+          email: emailFromOutput || profile?.email,
+          success: true,
+          needsOnboarding: true,
+          detectedAt: new Date().toISOString()
+        } as OAuthTokenEvent);
       } else {
         console.warn('[ClaudeIntegration] Login successful but Keychain token not found and no credentials in configDir - user may need to complete authentication manually');
       }
@@ -622,16 +624,13 @@ export function handleOAuthToken(
       clearKeychainCache(profile.configDir);
       console.warn('[ClaudeIntegration] Profile credentials verified (not caching token):', profileId);
 
-      const win = getWindow();
-      if (win) {
-        win.webContents.send(IPC_CHANNELS.TERMINAL_OAUTH_TOKEN, {
-          terminalId: terminal.id,
-          profileId,
-          email,
-          success: true,
-          detectedAt: new Date().toISOString()
-        } as OAuthTokenEvent);
-      }
+      safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_OAUTH_TOKEN, {
+        terminalId: terminal.id,
+        profileId,
+        email,
+        success: true,
+        detectedAt: new Date().toISOString()
+      } as OAuthTokenEvent);
     } else {
       console.error('[ClaudeIntegration] Profile not found for OAuth token:', profileId);
     }
@@ -645,17 +644,14 @@ export function handleOAuthToken(
     // Defensive null check for active profile
     if (!activeProfile) {
       console.error('[ClaudeIntegration] Failed to update profile: no active profile found');
-      const win = getWindow();
-      if (win) {
-        win.webContents.send(IPC_CHANNELS.TERMINAL_OAUTH_TOKEN, {
-          terminalId: terminal.id,
-          profileId: undefined,
-          email,
-          success: false,
-          message: 'No active profile found',
-          detectedAt: new Date().toISOString()
-        } as OAuthTokenEvent);
-      }
+      safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_OAUTH_TOKEN, {
+        terminalId: terminal.id,
+        profileId: undefined,
+        email,
+        success: false,
+        message: 'No active profile found',
+        detectedAt: new Date().toISOString()
+      } as OAuthTokenEvent);
       return;
     }
 
@@ -686,16 +682,13 @@ export function handleOAuthToken(
     clearKeychainCache(activeProfile.configDir);
     console.warn('[ClaudeIntegration] Active profile credentials verified (not caching token):', activeProfile.name);
 
-    const win = getWindow();
-    if (win) {
-      win.webContents.send(IPC_CHANNELS.TERMINAL_OAUTH_TOKEN, {
-        terminalId: terminal.id,
-        profileId: activeProfile.id,
-        email,
-        success: true,
-        detectedAt: new Date().toISOString()
-      } as OAuthTokenEvent);
-    }
+    safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_OAUTH_TOKEN, {
+      terminalId: terminal.id,
+      profileId: activeProfile.id,
+      email,
+      success: true,
+      detectedAt: new Date().toISOString()
+    } as OAuthTokenEvent);
   }
 }
 
@@ -785,14 +778,11 @@ export function handleOnboardingComplete(
     }
   }
 
-  const win = getWindow();
-  if (win) {
-    win.webContents.send(IPC_CHANNELS.TERMINAL_ONBOARDING_COMPLETE, {
-      terminalId: terminal.id,
-      profileId,
-      detectedAt: new Date().toISOString()
-    } as OnboardingCompleteEvent);
-  }
+  safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_ONBOARDING_COMPLETE, {
+    terminalId: terminal.id,
+    profileId,
+    detectedAt: new Date().toISOString()
+  } as OnboardingCompleteEvent);
 
   // Trigger immediate usage fetch after successful re-authentication
   // This gives the user immediate feedback that their account is working
@@ -845,10 +835,7 @@ export function handleClaudeSessionId(
     SessionHandler.updateClaudeSessionId(terminal.projectPath, terminal.id, sessionId);
   }
 
-  const win = getWindow();
-  if (win) {
-    win.webContents.send(IPC_CHANNELS.TERMINAL_CLAUDE_SESSION, terminal.id, sessionId);
-  }
+  safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_CLAUDE_SESSION, terminal.id, sessionId);
 }
 
 /**
@@ -879,10 +866,7 @@ export function handleClaudeExit(
   }
 
   // Notify renderer to update UI
-  const win = getWindow();
-  if (win) {
-    win.webContents.send(IPC_CHANNELS.TERMINAL_CLAUDE_EXIT, terminal.id);
-  }
+  safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_CLAUDE_EXIT, terminal.id);
 }
 
 /**
@@ -1109,7 +1093,9 @@ export function invokeClaude(
     const cwdCommand = buildCdCommand(cwd, terminal.shellType);
     const { command: claudeCmd, env: claudeEnv } = getClaudeCliInvocation();
     const escapedClaudeCmd = escapeShellCommand(claudeCmd);
-    const pathPrefix = buildPathPrefix(claudeEnv.PATH || '');
+    const pathPrefix = isAbsoluteExecutableCommand(claudeCmd)
+      ? ''
+      : buildPathPrefix(claudeEnv.PATH || '');
     const needsEnvOverride: boolean = !!(profileId && profileId !== previousProfileId);
 
     debugLog('[ClaudeIntegration:invokeClaude] Environment override check:', {
@@ -1196,7 +1182,9 @@ export function resumeClaude(
 
     const { command: claudeCmd, env: claudeEnv } = getClaudeCliInvocation();
     const escapedClaudeCmd = escapeShellCommand(claudeCmd);
-    const pathPrefix = buildPathPrefix(claudeEnv.PATH || '');
+    const pathPrefix = isAbsoluteExecutableCommand(claudeCmd)
+      ? ''
+      : buildPathPrefix(claudeEnv.PATH || '');
 
     // Always use --continue which resumes the most recent session in the current directory.
     // This is more reliable than --resume with session IDs since Auto Claude already restores
@@ -1211,7 +1199,10 @@ export function resumeClaude(
       console.warn('[ClaudeIntegration:resumeClaude] sessionId parameter is deprecated and ignored; using claude --continue instead');
     }
 
-    const command = `${pathPrefix}${escapedClaudeCmd} --continue`;
+    // Preserve YOLO mode flag from terminal's stored state
+    const extraFlags = terminal.dangerouslySkipPermissions ? YOLO_MODE_FLAG : '';
+
+    const command = `${pathPrefix}${escapedClaudeCmd} --continue${extraFlags}`;
 
     // Use PtyManager.writeToPty for safer write with error handling
     PtyManager.writeToPty(terminal, `${command}\r`);
@@ -1220,10 +1211,7 @@ export function resumeClaude(
     // This preserves user-customized names and prevents renaming on every resume
     if (shouldAutoRenameTerminal(terminal.title)) {
       terminal.title = 'Claude';
-      const win = getWindow();
-      if (win) {
-        win.webContents.send(IPC_CHANNELS.TERMINAL_TITLE_CHANGE, terminal.id, 'Claude');
-      }
+      safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_TITLE_CHANGE, terminal.id, 'Claude');
     }
 
     // Persist session
@@ -1313,7 +1301,9 @@ export async function invokeClaudeAsync(
       });
 
     const escapedClaudeCmd = escapeShellCommand(claudeCmd);
-    const pathPrefix = buildPathPrefix(claudeEnv.PATH || '');
+    const pathPrefix = isAbsoluteExecutableCommand(claudeCmd)
+      ? ''
+      : buildPathPrefix(claudeEnv.PATH || '');
     const needsEnvOverride: boolean = !!(profileId && profileId !== previousProfileId);
 
     debugLog('[ClaudeIntegration:invokeClaudeAsync] Environment override check:', {
@@ -1386,7 +1376,8 @@ export async function invokeClaudeAsync(
 export async function resumeClaudeAsync(
   terminal: TerminalProcess,
   sessionId: string | undefined,
-  getWindow: WindowGetter
+  getWindow: WindowGetter,
+  options?: { migratedSession?: boolean }
 ): Promise<void> {
   // Track terminal state for cleanup on error
   const wasClaudeMode = terminal.isClaudeMode;
@@ -1409,7 +1400,9 @@ export async function resumeClaudeAsync(
       });
 
     const escapedClaudeCmd = escapeShellCommand(claudeCmd);
-    const pathPrefix = buildPathPrefix(claudeEnv.PATH || '');
+    const pathPrefix = isAbsoluteExecutableCommand(claudeCmd)
+      ? ''
+      : buildPathPrefix(claudeEnv.PATH || '');
 
     // Always use --continue which resumes the most recent session in the current directory.
     // This is more reliable than --resume with session IDs since Auto Claude already restores
@@ -1419,12 +1412,19 @@ export async function resumeClaudeAsync(
     // and we don't want stale IDs persisting through SessionHandler.persistSessionAsync().
     terminal.claudeSessionId = undefined;
 
-    // Deprecation warning for callers still passing sessionId
-    if (sessionId) {
+    // Deprecation warning for callers still passing sessionId (skip for migrated sessions)
+    if (sessionId && !options?.migratedSession) {
       console.warn('[ClaudeIntegration:resumeClaudeAsync] sessionId parameter is deprecated and ignored; using claude --continue instead');
     }
 
-    const command = `${pathPrefix}${escapedClaudeCmd} --continue`;
+    if (options?.migratedSession) {
+      debugLog('[ClaudeIntegration:resumeClaudeAsync] Post-swap resume for terminal:', terminal.id);
+    }
+
+    // Preserve YOLO mode flag from terminal's stored state
+    const extraFlags = terminal.dangerouslySkipPermissions ? YOLO_MODE_FLAG : '';
+
+    const command = `${pathPrefix}${escapedClaudeCmd} --continue${extraFlags}`;
 
     // Use PtyManager.writeToPty for safer write with error handling
     PtyManager.writeToPty(terminal, `${command}\r`);
@@ -1433,10 +1433,7 @@ export async function resumeClaudeAsync(
     // This preserves user-customized names and prevents renaming on every resume
     if (shouldAutoRenameTerminal(terminal.title)) {
       terminal.title = 'Claude';
-      const win = getWindow();
-      if (win) {
-        win.webContents.send(IPC_CHANNELS.TERMINAL_TITLE_CHANGE, terminal.id, 'Claude');
-      }
+      safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_TITLE_CHANGE, terminal.id, 'Claude');
     }
 
     // Persist session (async, fire-and-forget to prevent main process blocking)

apps/frontend/src/main/terminal/pty-manager.ts

@@ -209,18 +209,25 @@ export function setupPtyHandlers(
   onExitCallback: (terminal: TerminalProcess) => void
 ): void {
   const { id, pty: ptyProcess } = terminal;
+  terminal.hasExited = false;
 
   // Handle data from terminal
   ptyProcess.onData((data) => {
     // Shutdown guard (GitHub #1469): skip processing to avoid accessing
     // destroyed BrowserWindow.webContents, which triggers pty.node SIGABRT
     if (isShuttingDown) return;
+    if (terminal.hasExited) return;
 
     // Append to output buffer (limit to 100KB)
     terminal.outputBuffer = (terminal.outputBuffer + data).slice(-100000);
 
-    // Call custom data handler
-    onDataCallback(terminal, data);
+    // Call custom data handler. This must never crash the main process:
+    // parser logic in higher layers can throw on unexpected output.
+    try {
+      onDataCallback(terminal, data);
+    } catch (error) {
+      debugError('[PtyManager] onData callback failed for terminal:', id, 'error:', error);
+    }
 
     // Send to renderer with isDestroyed() check to prevent crashes
     // when the window is closed during terminal activity
@@ -229,6 +236,9 @@ export function setupPtyHandlers(
 
   // Handle terminal exit
   ptyProcess.onExit(({ exitCode }) => {
+    terminal.hasExited = true;
+    // Drop any queued writes for this terminal to avoid writing to dead PTYs.
+    pendingWrites.delete(id);
     debugLog('[PtyManager] Terminal exited:', id, 'code:', exitCode);
 
     // Always resolve pending exit promises, even during shutdown
@@ -248,8 +258,13 @@ export function setupPtyHandlers(
     // when the window is closed during terminal exit
     safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_EXIT, id, exitCode);
 
-    // Call custom exit handler
-    onExitCallback(terminal);
+    // Call custom exit handler. Guard against unexpected exceptions so PTY exit
+    // handling remains robust and doesn't take down the main process.
+    try {
+      onExitCallback(terminal);
+    } catch (error) {
+      debugError('[PtyManager] onExit callback failed for terminal:', id, 'error:', error);
+    }
 
     // Only delete if this is the SAME terminal object (not a newly created one with same ID).
     // This prevents a race where destroyTerminal() awaits PTY exit, a new terminal is created
@@ -285,6 +300,11 @@ const pendingWrites = new Map<string, Promise<void>>();
  */
 function performWrite(terminal: TerminalProcess, data: string): Promise<void> {
   return new Promise((resolve) => {
+    if (terminal.hasExited) {
+      resolve();
+      return;
+    }
+
     // For large commands, write in chunks to prevent blocking
     if (data.length > CHUNKED_WRITE_THRESHOLD) {
       debugLog('[PtyManager:writeToPty] Large write detected, using chunked write');
@@ -293,7 +313,7 @@ function performWrite(terminal: TerminalProcess, data: string): Promise<void> {
 
       const writeChunk = () => {
         // Check if terminal is still valid before writing
-        if (!terminal.pty) {
+        if (!terminal.pty || terminal.hasExited) {
           debugError('[PtyManager:writeToPty] Terminal PTY no longer valid, aborting chunked write');
           resolve();
           return;
@@ -339,6 +359,10 @@ function performWrite(terminal: TerminalProcess, data: string): Promise<void> {
  */
 export function writeToPty(terminal: TerminalProcess, data: string): void {
   debugLog('[PtyManager:writeToPty] About to write to pty, data length:', data.length);
+  if (terminal.hasExited) {
+    debugError('[PtyManager:writeToPty] Skipping write to exited terminal:', terminal.id);
+    return;
+  }
 
   // Get the previous write Promise for this terminal (if any)
   const previousWrite = pendingWrites.get(terminal.id) || Promise.resolve();
@@ -366,6 +390,11 @@ export function writeToPty(terminal: TerminalProcess, data: string): void {
  * @returns true if resize was successful, false otherwise
  */
 export function resizePty(terminal: TerminalProcess, cols: number, rows: number): boolean {
+  if (terminal.hasExited) {
+    debugError('[PtyManager] Resize skipped for exited terminal:', terminal.id);
+    return false;
+  }
+
   // Validate dimensions
   if (cols <= 0 || rows <= 0 || !Number.isFinite(cols) || !Number.isFinite(rows)) {
     debugError('[PtyManager] Invalid resize dimensions - terminal:', terminal.id, 'cols:', cols, 'rows:', rows);
@@ -375,6 +404,17 @@ export function resizePty(terminal: TerminalProcess, cols: number, rows: number)
   try {
     const prevCols = terminal.pty.cols;
     const prevRows = terminal.pty.rows;
+
+    // If dimensions are unchanged, force SIGWINCH via a resize cycle.
+    // On macOS/Linux, ioctl(TIOCSWINSZ) only sends SIGWINCH when size actually
+    // changes. This matters after project switch: PTY persists with old dimensions,
+    // terminal remounts at same size, TUI apps (Claude Code) never get SIGWINCH
+    // and never redraw — leaving the terminal blank.
+    if (prevCols === cols && prevRows === rows) {
+      debugLog('[PtyManager] Same-dimension resize detected, forcing SIGWINCH cycle for terminal:', terminal.id);
+      terminal.pty.resize(Math.max(1, cols - 1), rows);
+    }
+
     debugLog('[PtyManager] Resizing PTY - terminal:', terminal.id, 'from:', prevCols, 'x', prevRows, 'to:', cols, 'x', rows);
     terminal.pty.resize(cols, rows);
     debugLog('[PtyManager] PTY resized - actual dimensions now:', terminal.pty.cols, 'x', terminal.pty.rows);
@@ -394,6 +434,10 @@ export function resizePty(terminal: TerminalProcess, cols: number, rows: number)
 export function killPty(terminal: TerminalProcess, waitForExit: true): Promise<void>;
 export function killPty(terminal: TerminalProcess, waitForExit?: false): void;
 export function killPty(terminal: TerminalProcess, waitForExit?: boolean): Promise<void> | void {
+  if (terminal.hasExited) {
+    return waitForExit ? Promise.resolve() : undefined;
+  }
+
   if (waitForExit) {
     const exitPromise = waitForPtyExit(terminal.id);
     try {

apps/frontend/src/main/terminal/session-handler.ts

@@ -225,6 +225,18 @@ export function persistAllSessions(terminals: Map<string, TerminalProcess>): voi
   });
 }
 
+/**
+ * Clear a terminal ID from pendingDelete, allowing session saves to proceed.
+ *
+ * Must be called when re-creating a terminal with a previously-used ID
+ * (e.g., worktree switching, terminal restart after shell exit). Without this,
+ * the pendingDelete guard blocks persistence for the new terminal.
+ */
+export function clearPendingDelete(terminalId: string): void {
+  const store = getTerminalSessionStore();
+  store.clearPendingDelete(terminalId);
+}
+
 /**
  * Remove a session from persistent storage
  */

apps/frontend/src/main/terminal/terminal-event-handler.ts

@@ -7,6 +7,7 @@ import * as OutputParser from './output-parser';
 import * as ClaudeIntegration from './claude-integration-handler';
 import type { TerminalProcess, WindowGetter } from './types';
 import { IPC_CHANNELS } from '../../shared/constants';
+import { safeSendToRenderer } from '../ipc-handlers/utils';
 
 /**
  * Event handler callbacks
@@ -109,10 +110,7 @@ export function createEventCallbacks(
       ClaudeIntegration.handleOnboardingComplete(terminal, data, getWindow);
     },
     onClaudeBusyChange: (terminal, isBusy) => {
-      const win = getWindow();
-      if (win) {
-        win.webContents.send(IPC_CHANNELS.TERMINAL_CLAUDE_BUSY, terminal.id, isBusy);
-      }
+      safeSendToRenderer(getWindow, IPC_CHANNELS.TERMINAL_CLAUDE_BUSY, terminal.id, isBusy);
     },
     onClaudeExit: (terminal) => {
       ClaudeIntegration.handleClaudeExit(terminal, getWindow);

apps/frontend/src/main/terminal/terminal-lifecycle.ts

@@ -54,6 +54,13 @@ export async function createTerminal(
     return { success: true };
   }
 
+  // Clear any pendingDelete for this terminal ID. This handles the case where
+  // a terminal is destroyed and immediately re-created with the same ID (e.g.,
+  // worktree switching, terminal restart after shell exit). Without this, the
+  // pendingDelete guard (5-second window) blocks session persistence for the
+  // new terminal, causing it to be invisible to the session store.
+  SessionHandler.clearPendingDelete(id);
+
   try {
     // For auth terminals, don't inject existing OAuth token - we want a fresh login
     const profileEnv = skipOAuthToken ? {} : PtyManager.getActiveProfileEnv();
@@ -101,6 +108,7 @@ export async function createTerminal(
       id,
       pty: ptyProcess,
       isClaudeMode: false,
+      hasExited: false,
       projectPath,
       cwd: terminalCwd,
       outputBuffer: '',

apps/frontend/src/main/terminal/terminal-manager.ts

@@ -11,7 +11,7 @@ import type {
   TerminalProcess,
   WindowGetter,
   TerminalOperationResult,
-  TerminalProfileChangeInfo
+  TerminalProfileChangeInfo,
 } from './types';
 import * as PtyManager from './pty-manager';
 import * as SessionHandler from './session-handler';
@@ -26,6 +26,8 @@ export class TerminalManager {
   private saveTimer: NodeJS.Timeout | null = null;
   private lastNotifiedRateLimitReset: Map<string, string> = new Map();
   private eventCallbacks: TerminalEventHandler.EventHandlerCallbacks;
+  /** Server-side storage for YOLO mode flags during profile migration (sessionId → flag) */
+  private migratedSessionFlags: Map<string, boolean> = new Map();
 
   constructor(getWindow: WindowGetter) {
     this.getWindow = getWindow;
@@ -114,6 +116,7 @@ export class TerminalManager {
    * Kill all terminal processes
    */
   async killAll(): Promise<void> {
+    this.migratedSessionFlags.clear();
     this.saveTimer = await TerminalLifecycle.destroyAllTerminals(
       this.terminals,
       this.saveTimer
@@ -223,13 +226,36 @@ export class TerminalManager {
   /**
    * Resume Claude in a terminal asynchronously (non-blocking)
    */
-  async resumeClaudeAsync(id: string, sessionId?: string): Promise<void> {
+  async resumeClaudeAsync(id: string, sessionId?: string, options?: { migratedSession?: boolean }): Promise<void> {
     const terminal = this.terminals.get(id);
     if (!terminal) {
+      // Clean up stale migratedSessionFlags if terminal no longer exists
+      if (options?.migratedSession && sessionId) {
+        this.migratedSessionFlags.delete(sessionId);
+      }
       return;
     }
 
-    await ClaudeIntegration.resumeClaudeAsync(terminal, sessionId, this.getWindow);
+    // For migrated sessions, restore YOLO mode from server-side storage
+    // (set during profile change in storeMigratedSessionFlag)
+    if (options?.migratedSession && sessionId) {
+      const storedFlag = this.migratedSessionFlags.get(sessionId);
+      if (storedFlag !== undefined) {
+        terminal.dangerouslySkipPermissions = storedFlag;
+        this.migratedSessionFlags.delete(sessionId);
+      }
+    }
+
+    await ClaudeIntegration.resumeClaudeAsync(terminal, sessionId, this.getWindow, options);
+  }
+
+  /**
+   * Store YOLO mode flag for a session being migrated during profile swap.
+   * Called from the profile change handler before the renderer recreates terminals.
+   * The flag is consumed by resumeClaudeAsync when the new terminal resumes.
+   */
+  storeMigratedSessionFlag(sessionId: string, dangerouslySkipPermissions: boolean): void {
+    this.migratedSessionFlags.set(sessionId, dangerouslySkipPermissions);
   }
 
   /**
@@ -387,7 +413,8 @@ export class TerminalManager {
         projectPath: terminal.projectPath,
         claudeSessionId: terminal.claudeSessionId,
         claudeProfileId: terminal.claudeProfileId,
-        isClaudeMode: terminal.isClaudeMode
+        isClaudeMode: terminal.isClaudeMode,
+        dangerouslySkipPermissions: terminal.dangerouslySkipPermissions
       });
     }
 

apps/frontend/src/main/terminal/types.ts

@@ -28,6 +28,8 @@ export interface TerminalProcess {
   shellType?: WindowsShellType;
   /** Whether this terminal is waiting for Claude onboarding to complete (login flow) */
   awaitingOnboardingComplete?: boolean;
+  /** Whether PTY has emitted exit; used to avoid writes/resizes on dead PTYs */
+  hasExited?: boolean;
 }
 
 /**
@@ -99,4 +101,5 @@ export interface TerminalProfileChangeInfo {
   claudeSessionId?: string;
   claudeProfileId?: string;
   isClaudeMode: boolean;
+  dangerouslySkipPermissions?: boolean;
 }

apps/frontend/src/preload/api/modules/github-api.ts

@@ -285,6 +285,9 @@ export interface GitHubAPI {
   getPRReview: (projectId: string, prNumber: number) => Promise<PRReviewResult | null>;
   getPRReviewsBatch: (projectId: string, prNumbers: number[]) => Promise<Record<number, PRReviewResult | null>>;
 
+  // External review notification (renderer tells main process about external review completion/timeout)
+  notifyExternalReviewComplete: (projectId: string, prNumber: number, result: PRReviewResult | null) => Promise<void>;
+
   // Follow-up review operations
   checkNewCommits: (projectId: string, prNumber: number) => Promise<NewCommitsCheck>;
   checkMergeReadiness: (projectId: string, prNumber: number) => Promise<MergeReadiness>;
@@ -308,6 +311,9 @@ export interface GitHubAPI {
   onPRReviewError: (
     callback: (projectId: string, error: { prNumber: number; error: string }) => void
   ) => IpcListenerCleanup;
+  onPRReviewStateChange: (
+    callback: (key: string, state: PRReviewStatePayload) => void
+  ) => IpcListenerCleanup;
   onPRLogsUpdated: (
     callback: (projectId: string, data: { prNumber: number; entryCount: number }) => void
   ) => IpcListenerCleanup;
@@ -456,6 +462,23 @@ export interface PRReviewProgress {
   message: string;
 }
 
+/**
+ * PR review state payload (emitted on state machine transitions)
+ */
+export interface PRReviewStatePayload {
+  state: string;
+  prNumber: number;
+  projectId: string;
+  isReviewing: boolean;
+  startedAt: string | null;
+  progress: PRReviewProgress | null;
+  result: PRReviewResult | null;
+  previousResult: PRReviewResult | null;
+  error: string | null;
+  isExternalReview: boolean;
+  isFollowup: boolean;
+}
+
 /**
  * PR review log entry type
  */
@@ -740,6 +763,10 @@ export const createGitHubAPI = (): GitHubAPI => ({
   getPRReviewsBatch: (projectId: string, prNumbers: number[]): Promise<Record<number, PRReviewResult | null>> =>
     invokeIpc(IPC_CHANNELS.GITHUB_PR_GET_REVIEWS_BATCH, projectId, prNumbers),
 
+  // External review notification
+  notifyExternalReviewComplete: (projectId: string, prNumber: number, result: PRReviewResult | null): Promise<void> =>
+    invokeIpc(IPC_CHANNELS.GITHUB_PR_NOTIFY_EXTERNAL_REVIEW_COMPLETE, projectId, prNumber, result),
+
   // Follow-up review operations
   checkNewCommits: (projectId: string, prNumber: number): Promise<NewCommitsCheck> =>
     invokeIpc(IPC_CHANNELS.GITHUB_PR_CHECK_NEW_COMMITS, projectId, prNumber),
@@ -780,6 +807,11 @@ export const createGitHubAPI = (): GitHubAPI => ({
   ): IpcListenerCleanup =>
     createIpcListener(IPC_CHANNELS.GITHUB_PR_REVIEW_ERROR, callback),
 
+  onPRReviewStateChange: (
+    callback: (key: string, state: PRReviewStatePayload) => void
+  ): IpcListenerCleanup =>
+    createIpcListener(IPC_CHANNELS.GITHUB_PR_REVIEW_STATE_CHANGE, callback),
+
   onPRLogsUpdated: (
     callback: (projectId: string, data: { prNumber: number; entryCount: number }) => void
   ): IpcListenerCleanup =>

apps/frontend/src/preload/api/modules/insights-api.ts

@@ -5,6 +5,7 @@ import type {
   InsightsChatStatus,
   InsightsStreamChunk,
   InsightsModelConfig,
+  ImageAttachment,
   Task,
   TaskMetadata,
   IPCResult
@@ -17,7 +18,7 @@ import { createIpcListener, invokeIpc, sendIpc, IpcListenerCleanup } from './ipc
 export interface InsightsAPI {
   // Operations
   getInsightsSession: (projectId: string) => Promise<IPCResult<InsightsSession | null>>;
-  sendInsightsMessage: (projectId: string, message: string, modelConfig?: InsightsModelConfig) => void;
+  sendInsightsMessage: (projectId: string, message: string, modelConfig?: InsightsModelConfig, images?: ImageAttachment[]) => void;
   clearInsightsSession: (projectId: string) => Promise<IPCResult>;
   createTaskFromInsights: (
     projectId: string,
@@ -25,10 +26,14 @@ export interface InsightsAPI {
     description: string,
     metadata?: TaskMetadata
   ) => Promise<IPCResult<Task>>;
-  listInsightsSessions: (projectId: string) => Promise<IPCResult<InsightsSessionSummary[]>>;
+  listInsightsSessions: (projectId: string, includeArchived?: boolean) => Promise<IPCResult<InsightsSessionSummary[]>>;
   newInsightsSession: (projectId: string) => Promise<IPCResult<InsightsSession>>;
   switchInsightsSession: (projectId: string, sessionId: string) => Promise<IPCResult<InsightsSession | null>>;
   deleteInsightsSession: (projectId: string, sessionId: string) => Promise<IPCResult>;
+  deleteInsightsSessions: (projectId: string, sessionIds: string[]) => Promise<IPCResult<{ deletedIds: string[]; failedIds: string[] }>>;
+  archiveInsightsSession: (projectId: string, sessionId: string) => Promise<IPCResult>;
+  archiveInsightsSessions: (projectId: string, sessionIds: string[]) => Promise<IPCResult<{ archivedIds: string[]; failedIds: string[] }>>;
+  unarchiveInsightsSession: (projectId: string, sessionId: string) => Promise<IPCResult>;
   renameInsightsSession: (projectId: string, sessionId: string, newTitle: string) => Promise<IPCResult>;
   updateInsightsModelConfig: (projectId: string, sessionId: string, modelConfig: InsightsModelConfig) => Promise<IPCResult>;
 
@@ -55,8 +60,8 @@ export const createInsightsAPI = (): InsightsAPI => ({
   getInsightsSession: (projectId: string): Promise<IPCResult<InsightsSession | null>> =>
     invokeIpc(IPC_CHANNELS.INSIGHTS_GET_SESSION, projectId),
 
-  sendInsightsMessage: (projectId: string, message: string, modelConfig?: InsightsModelConfig): void =>
-    sendIpc(IPC_CHANNELS.INSIGHTS_SEND_MESSAGE, projectId, message, modelConfig),
+  sendInsightsMessage: (projectId: string, message: string, modelConfig?: InsightsModelConfig, images?: ImageAttachment[]): void =>
+    sendIpc(IPC_CHANNELS.INSIGHTS_SEND_MESSAGE, projectId, message, modelConfig, images),
 
   clearInsightsSession: (projectId: string): Promise<IPCResult> =>
     invokeIpc(IPC_CHANNELS.INSIGHTS_CLEAR_SESSION, projectId),
@@ -69,8 +74,8 @@ export const createInsightsAPI = (): InsightsAPI => ({
   ): Promise<IPCResult<Task>> =>
     invokeIpc(IPC_CHANNELS.INSIGHTS_CREATE_TASK, projectId, title, description, metadata),
 
-  listInsightsSessions: (projectId: string): Promise<IPCResult<InsightsSessionSummary[]>> =>
-    invokeIpc(IPC_CHANNELS.INSIGHTS_LIST_SESSIONS, projectId),
+  listInsightsSessions: (projectId: string, includeArchived?: boolean): Promise<IPCResult<InsightsSessionSummary[]>> =>
+    invokeIpc(IPC_CHANNELS.INSIGHTS_LIST_SESSIONS, projectId, includeArchived),
 
   newInsightsSession: (projectId: string): Promise<IPCResult<InsightsSession>> =>
     invokeIpc(IPC_CHANNELS.INSIGHTS_NEW_SESSION, projectId),
@@ -81,6 +86,18 @@ export const createInsightsAPI = (): InsightsAPI => ({
   deleteInsightsSession: (projectId: string, sessionId: string): Promise<IPCResult> =>
     invokeIpc(IPC_CHANNELS.INSIGHTS_DELETE_SESSION, projectId, sessionId),
 
+  deleteInsightsSessions: (projectId: string, sessionIds: string[]): Promise<IPCResult<{ deletedIds: string[]; failedIds: string[] }>> =>
+    invokeIpc(IPC_CHANNELS.INSIGHTS_DELETE_SESSIONS, projectId, sessionIds),
+
+  archiveInsightsSession: (projectId: string, sessionId: string): Promise<IPCResult> =>
+    invokeIpc(IPC_CHANNELS.INSIGHTS_ARCHIVE_SESSION, projectId, sessionId),
+
+  archiveInsightsSessions: (projectId: string, sessionIds: string[]): Promise<IPCResult<{ archivedIds: string[]; failedIds: string[] }>> =>
+    invokeIpc(IPC_CHANNELS.INSIGHTS_ARCHIVE_SESSIONS, projectId, sessionIds),
+
+  unarchiveInsightsSession: (projectId: string, sessionId: string): Promise<IPCResult> =>
+    invokeIpc(IPC_CHANNELS.INSIGHTS_UNARCHIVE_SESSION, projectId, sessionId),
+
   renameInsightsSession: (projectId: string, sessionId: string, newTitle: string): Promise<IPCResult> =>
     invokeIpc(IPC_CHANNELS.INSIGHTS_RENAME_SESSION, projectId, sessionId, newTitle),
 

apps/frontend/src/preload/api/modules/roadmap-api.ts

@@ -4,6 +4,7 @@ import type {
   RoadmapFeatureStatus,
   RoadmapGenerationStatus,
   PersistedRoadmapProgress,
+  CompetitorAnalysis,
   Task,
   IPCResult
 } from '../../../shared/types';
@@ -30,6 +31,9 @@ export interface RoadmapAPI {
     featureId: string
   ) => Promise<IPCResult<Task>>;
 
+  // Competitor analysis
+  saveCompetitorAnalysis: (projectId: string, competitorAnalysis: CompetitorAnalysis) => Promise<IPCResult>;
+
   // Progress persistence
   saveRoadmapProgress: (projectId: string, progress: PersistedRoadmapProgress) => Promise<IPCResult>;
   loadRoadmapProgress: (projectId: string) => Promise<IPCResult<PersistedRoadmapProgress | null>>;
@@ -86,6 +90,10 @@ export const createRoadmapAPI = (): RoadmapAPI => ({
   ): Promise<IPCResult<Task>> =>
     invokeIpc(IPC_CHANNELS.ROADMAP_CONVERT_TO_SPEC, projectId, featureId),
 
+  // Competitor analysis
+  saveCompetitorAnalysis: (projectId: string, competitorAnalysis: CompetitorAnalysis): Promise<IPCResult> =>
+    invokeIpc(IPC_CHANNELS.COMPETITOR_ANALYSIS_SAVE, projectId, competitorAnalysis),
+
   // Progress persistence
   saveRoadmapProgress: (projectId: string, progress: PersistedRoadmapProgress): Promise<IPCResult> =>
     invokeIpc(IPC_CHANNELS.ROADMAP_PROGRESS_SAVE, projectId, progress),

apps/frontend/src/preload/api/task-api.ts

@@ -44,7 +44,7 @@ export interface TaskAPI {
   updateTaskStatus: (
     taskId: string,
     status: TaskStatus,
-    options?: { forceCleanup?: boolean }
+    options?: { forceCleanup?: boolean; keepWorktree?: boolean }
   ) => Promise<IPCResult & { worktreeExists?: boolean; worktreePath?: string }>;
   recoverStuckTask: (
     taskId: string,
@@ -135,7 +135,7 @@ export const createTaskAPI = (): TaskAPI => ({
   updateTaskStatus: (
     taskId: string,
     status: TaskStatus,
-    options?: { forceCleanup?: boolean }
+    options?: { forceCleanup?: boolean; keepWorktree?: boolean }
   ): Promise<IPCResult & { worktreeExists?: boolean; worktreePath?: string }> =>
     ipcRenderer.invoke(IPC_CHANNELS.TASK_UPDATE_STATUS, taskId, status, options),
 

apps/frontend/src/preload/api/terminal-api.ts

@@ -47,7 +47,7 @@ export interface TerminalAPI {
     rows?: number
   ) => Promise<IPCResult<import('../../shared/types').TerminalRestoreResult>>;
   clearTerminalSessions: (projectPath: string) => Promise<IPCResult>;
-  resumeClaudeInTerminal: (id: string, sessionId?: string) => void;
+  resumeClaudeInTerminal: (id: string, sessionId?: string, options?: { migratedSession?: boolean }) => void;
   activateDeferredClaudeResume: (id: string) => void;
   getTerminalSessionDates: (projectPath?: string) => Promise<IPCResult<import('../../shared/types').SessionDateInfo[]>>;
   getTerminalSessionsForDate: (
@@ -166,8 +166,8 @@ export const createTerminalAPI = (): TerminalAPI => ({
   clearTerminalSessions: (projectPath: string): Promise<IPCResult> =>
     ipcRenderer.invoke(IPC_CHANNELS.TERMINAL_CLEAR_SESSIONS, projectPath),
 
-  resumeClaudeInTerminal: (id: string, sessionId?: string): void =>
-    ipcRenderer.send(IPC_CHANNELS.TERMINAL_RESUME_CLAUDE, id, sessionId),
+  resumeClaudeInTerminal: (id: string, sessionId?: string, options?: { migratedSession?: boolean }): void =>
+    ipcRenderer.send(IPC_CHANNELS.TERMINAL_RESUME_CLAUDE, id, sessionId, options),
 
   activateDeferredClaudeResume: (id: string): void =>
     ipcRenderer.send(IPC_CHANNELS.TERMINAL_ACTIVATE_DEFERRED_RESUME, id),

apps/frontend/src/renderer/__tests__/roadmap-store.test.ts

@@ -3,7 +3,7 @@
  * Tests Zustand store for roadmap state management including drag-and-drop actions
  */
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { useRoadmapStore, getFeaturesByPhase, getFeaturesByPriority, getFeatureStats } from '../stores/roadmap-store';
+import { useRoadmapStore, getFeaturesByPhase, getFeaturesByPriority, getFeatureStats, resetActors } from '../stores/roadmap-store';
 import type {
   Roadmap,
   RoadmapFeature,
@@ -86,6 +86,8 @@ describe('Roadmap Store', () => {
 
   afterEach(() => {
     vi.clearAllMocks();
+    // Reset XState actors to prevent test pollution
+    resetActors();
   });
 
   describe('setRoadmap', () => {
@@ -623,6 +625,165 @@ describe('Roadmap Store', () => {
     });
   });
 
+  describe('setGenerationStatus catch-up logic', () => {
+    it('should advance from idle to analyzing', () => {
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'analyzing',
+        progress: 10,
+        message: 'Analyzing...'
+      });
+
+      const status = useRoadmapStore.getState().generationStatus;
+      expect(status.phase).toBe('analyzing');
+      expect(status.progress).toBe(10);
+      expect(status.message).toBe('Analyzing...');
+    });
+
+    it('should advance from idle to discovering via catch-up', () => {
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'discovering',
+        progress: 30,
+        message: 'Discovering...'
+      });
+
+      const status = useRoadmapStore.getState().generationStatus;
+      expect(status.phase).toBe('discovering');
+      expect(status.progress).toBe(30);
+      expect(status.message).toBe('Discovering...');
+    });
+
+    it('should advance from idle to generating via catch-up', () => {
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'generating',
+        progress: 60,
+        message: 'Generating...'
+      });
+
+      const status = useRoadmapStore.getState().generationStatus;
+      expect(status.phase).toBe('generating');
+      expect(status.progress).toBe(60);
+      expect(status.message).toBe('Generating...');
+    });
+
+    it('should advance from idle to complete via catch-up', () => {
+      // First go through active states to build up context, then complete
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'analyzing',
+        progress: 10,
+        message: 'Analyzing...'
+      });
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'complete',
+        progress: 100,
+        message: 'Done'
+      });
+
+      const status = useRoadmapStore.getState().generationStatus;
+      expect(status.phase).toBe('complete');
+      expect(status.progress).toBe(100);
+    });
+
+    it('should advance from idle to error via catch-up', () => {
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'error',
+        progress: 0,
+        message: '',
+        error: 'Something failed'
+      });
+
+      const status = useRoadmapStore.getState().generationStatus;
+      expect(status.phase).toBe('error');
+      expect(status.error).toBe('Something failed');
+    });
+
+    it('should reset from error and start new generation', () => {
+      // First put into error state
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'error',
+        progress: 0,
+        message: '',
+        error: 'Failed'
+      });
+      expect(useRoadmapStore.getState().generationStatus.phase).toBe('error');
+
+      // Now start a new generation from error state
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'analyzing',
+        progress: 5,
+        message: 'Restarting...'
+      });
+
+      const status = useRoadmapStore.getState().generationStatus;
+      expect(status.phase).toBe('analyzing');
+      expect(status.progress).toBe(5);
+    });
+
+    it('should send progress updates for active states', () => {
+      // Move to analyzing
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'analyzing',
+        progress: 0,
+        message: 'Starting...'
+      });
+
+      // Update progress in analyzing
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'analyzing',
+        progress: 50,
+        message: 'Halfway...'
+      });
+
+      const status = useRoadmapStore.getState().generationStatus;
+      expect(status.phase).toBe('analyzing');
+      expect(status.progress).toBe(50);
+      expect(status.message).toBe('Halfway...');
+    });
+
+    it('should be idempotent for idle-to-idle transitions', () => {
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'idle',
+        progress: 0,
+        message: ''
+      });
+
+      const status = useRoadmapStore.getState().generationStatus;
+      expect(status.phase).toBe('idle');
+      expect(status.progress).toBe(0);
+    });
+
+    it('should handle complete-to-idle reset', () => {
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'complete',
+        progress: 100,
+        message: 'Done'
+      });
+      expect(useRoadmapStore.getState().generationStatus.phase).toBe('complete');
+
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'idle',
+        progress: 0,
+        message: ''
+      });
+      expect(useRoadmapStore.getState().generationStatus.phase).toBe('idle');
+    });
+
+    it('should preserve startedAt from persisted status on reload', () => {
+      const persistedStartedAt = new Date('2025-06-01T12:00:00Z');
+      useRoadmapStore.getState().setGenerationStatus({
+        phase: 'generating',
+        progress: 70,
+        message: 'Generating...',
+        startedAt: persistedStartedAt,
+        lastActivityAt: new Date()
+      });
+
+      const status = useRoadmapStore.getState().generationStatus;
+      expect(status.phase).toBe('generating');
+      expect(status.startedAt).toBeDefined();
+      expect(status.startedAt!.getTime()).toBe(persistedStartedAt.getTime());
+    });
+  });
+
   describe('clearRoadmap', () => {
     it('should clear roadmap and reset status', () => {
       useRoadmapStore.setState({

apps/frontend/src/renderer/components/AddCompetitorDialog.tsx

@@ -0,0 +1,295 @@
+/**
+ * AddCompetitorDialog - Dialog for adding manual competitors to the roadmap analysis
+ *
+ * Allows users to add known competitors with name, URL, description, and relevance.
+ * Follows the same dialog pattern as AddFeatureDialog for consistency.
+ *
+ * Features:
+ * - Form validation (name and URL required, URL format check)
+ * - Auto-prepends https:// if protocol is missing
+ * - Adds competitor to roadmap store and persists via IPC
+ *
+ * @example
+ * ```tsx
+ * <AddCompetitorDialog
+ *   open={isAddDialogOpen}
+ *   onOpenChange={setIsAddDialogOpen}
+ *   onCompetitorAdded={(id) => console.log('Competitor added:', id)}
+ *   projectId={projectId}
+ * />
+ * ```
+ */
+import { useState, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Loader2, AlertCircle } from 'lucide-react';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle
+} from './ui/dialog';
+import { Button } from './ui/button';
+import { Input } from './ui/input';
+import { Textarea } from './ui/textarea';
+import { Label } from './ui/label';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue
+} from './ui/select';
+import { useRoadmapStore } from '../stores/roadmap-store';
+import type { CompetitorRelevance } from '../../shared/types';
+
+/**
+ * Props for the AddCompetitorDialog component
+ */
+interface AddCompetitorDialogProps {
+  /** Whether the dialog is open */
+  open: boolean;
+  /** Callback when the dialog open state changes */
+  onOpenChange: (open: boolean) => void;
+  /** Optional callback when competitor is successfully added, receives the new competitor ID */
+  onCompetitorAdded?: (competitorId: string) => void;
+  /** Project ID for IPC save */
+  projectId: string;
+}
+
+// Relevance options (keys for translation)
+const RELEVANCE_OPTIONS = [
+  { value: 'high', labelKey: 'addCompetitor.highRelevance' },
+  { value: 'medium', labelKey: 'addCompetitor.mediumRelevance' },
+  { value: 'low', labelKey: 'addCompetitor.lowRelevance' }
+] as const;
+
+/**
+ * Basic URL validation - checks for a reasonable URL format
+ */
+function isValidUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Normalizes a URL by prepending https:// if no protocol is present
+ */
+function normalizeUrl(url: string): string {
+  const trimmed = url.trim();
+  if (!trimmed) return trimmed;
+  if (!/^https?:\/\//i.test(trimmed)) {
+    return `https://${trimmed}`;
+  }
+  return trimmed;
+}
+
+export function AddCompetitorDialog({
+  open,
+  onOpenChange,
+  onCompetitorAdded,
+  projectId
+}: AddCompetitorDialogProps) {
+  const { t } = useTranslation('dialogs');
+
+  // Form state
+  const [name, setName] = useState('');
+  const [url, setUrl] = useState('');
+  const [description, setDescription] = useState('');
+  const [relevance, setRelevance] = useState<CompetitorRelevance>('medium');
+
+  // UI state
+  const [isSaving, setIsSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Store actions
+  const addCompetitor = useRoadmapStore((state) => state.addCompetitor);
+
+  // Reset form when dialog opens/closes
+  useEffect(() => {
+    if (open) {
+      setName('');
+      setUrl('');
+      setDescription('');
+      setRelevance('medium');
+      setError(null);
+    }
+  }, [open]);
+
+  const handleSave = async () => {
+    // Validate required fields
+    if (!name.trim()) {
+      setError(t('addCompetitor.nameRequired'));
+      return;
+    }
+    if (!url.trim()) {
+      setError(t('addCompetitor.urlRequired'));
+      return;
+    }
+
+    const normalizedUrl = normalizeUrl(url);
+    if (!isValidUrl(normalizedUrl)) {
+      setError(t('addCompetitor.invalidUrl'));
+      return;
+    }
+
+    setIsSaving(true);
+    setError(null);
+
+    try {
+      // Capture pre-add state for complete rollback
+      const previousAnalysis = useRoadmapStore.getState().competitorAnalysis;
+
+      // Add competitor to store
+      const newCompetitorId = addCompetitor({
+        name: name.trim(),
+        url: normalizedUrl,
+        description: description.trim(),
+        relevance
+      });
+
+      // Persist to file via IPC
+      const competitorAnalysis = useRoadmapStore.getState().competitorAnalysis;
+      if (competitorAnalysis) {
+        const result = await window.electronAPI.saveCompetitorAnalysis(projectId, competitorAnalysis);
+        if (!result.success) {
+          // Rollback store state since save failed
+          useRoadmapStore.getState().setCompetitorAnalysis(previousAnalysis);
+          throw new Error(result.error || t('addCompetitor.failedToAdd'));
+        }
+      }
+
+      // Success - close dialog and notify parent
+      onOpenChange(false);
+      onCompetitorAdded?.(newCompetitorId);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : t('addCompetitor.failedToAdd'));
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  const handleClose = () => {
+    if (!isSaving) {
+      onOpenChange(false);
+    }
+  };
+
+  // Form validation
+  const isValid = name.trim().length > 0 && url.trim().length > 0;
+
+  return (
+    <Dialog open={open} onOpenChange={handleClose}>
+      <DialogContent className="sm:max-w-[550px] max-h-[90vh] overflow-y-auto">
+        <DialogHeader>
+          <DialogTitle className="text-foreground">{t('addCompetitor.title')}</DialogTitle>
+          <DialogDescription>
+            {t('addCompetitor.description')}
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-5 py-4">
+          {/* Name (Required) */}
+          <div className="space-y-2">
+            <Label htmlFor="add-competitor-name" className="text-sm font-medium text-foreground">
+              {t('addCompetitor.competitorName')} <span className="text-destructive">*</span>
+            </Label>
+            <Input
+              id="add-competitor-name"
+              placeholder={t('addCompetitor.competitorNamePlaceholder')}
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              disabled={isSaving}
+              aria-required="true"
+            />
+          </div>
+
+          {/* URL (Required) */}
+          <div className="space-y-2">
+            <Label htmlFor="add-competitor-url" className="text-sm font-medium text-foreground">
+              {t('addCompetitor.competitorUrl')} <span className="text-destructive">*</span>
+            </Label>
+            <Input
+              id="add-competitor-url"
+              placeholder={t('addCompetitor.competitorUrlPlaceholder')}
+              value={url}
+              onChange={(e) => setUrl(e.target.value)}
+              disabled={isSaving}
+              aria-required="true"
+            />
+          </div>
+
+          {/* Description (Optional) */}
+          <div className="space-y-2">
+            <Label htmlFor="add-competitor-description" className="text-sm font-medium text-foreground">
+              {t('addCompetitor.competitorDescription')} <span className="text-muted-foreground font-normal">({t('addCompetitor.optional')})</span>
+            </Label>
+            <Textarea
+              id="add-competitor-description"
+              placeholder={t('addCompetitor.competitorDescriptionPlaceholder')}
+              value={description}
+              onChange={(e) => setDescription(e.target.value)}
+              rows={3}
+              disabled={isSaving}
+            />
+          </div>
+
+          {/* Relevance (Optional) */}
+          <div className="space-y-2">
+            <Label htmlFor="add-competitor-relevance" className="text-sm font-medium text-foreground">
+              {t('addCompetitor.relevance')}
+            </Label>
+            <Select
+              value={relevance}
+              onValueChange={(value) => setRelevance(value as CompetitorRelevance)}
+              disabled={isSaving}
+            >
+              <SelectTrigger id="add-competitor-relevance">
+                <SelectValue placeholder={t('addCompetitor.selectRelevance')} />
+              </SelectTrigger>
+              <SelectContent>
+                {RELEVANCE_OPTIONS.map(({ value, labelKey }) => (
+                  <SelectItem key={value} value={value}>
+                    {t(labelKey)}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
+          {/* Error */}
+          {error && (
+            <div className="flex items-start gap-2 rounded-lg bg-destructive/10 border border-destructive/30 p-3 text-sm text-destructive" role="alert">
+              <AlertCircle className="h-4 w-4 mt-0.5 shrink-0" />
+              <span>{error}</span>
+            </div>
+          )}
+        </div>
+
+        <DialogFooter>
+          <Button variant="outline" onClick={handleClose} disabled={isSaving}>
+            {t('addCompetitor.cancel')}
+          </Button>
+          <Button
+            onClick={handleSave}
+            disabled={isSaving || !isValid}
+          >
+            {isSaving ? (
+              <>
+                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+                {t('addCompetitor.adding')}
+              </>
+            ) : (
+              t('addCompetitor.addCompetitor')
+            )}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

apps/frontend/src/renderer/components/ChatHistorySidebar.tsx

@@ -1,4 +1,4 @@
-import { useState } from 'react';
+import { useState, useCallback, useEffect } from 'react';
 import { useTranslation } from 'react-i18next';
 import {
   Plus,
@@ -8,11 +8,15 @@ import {
   Check,
   X,
   MoreVertical,
-  Loader2
+  Loader2,
+  CheckSquare,
+  Archive,
+  ArchiveRestore
 } from 'lucide-react';
 import { Button } from './ui/button';
 import { Input } from './ui/input';
 import { ScrollArea } from './ui/scroll-area';
+import { Checkbox } from './ui/checkbox';
 import { Tooltip, TooltipContent, TooltipTrigger } from './ui/tooltip';
 import {
   DropdownMenu,
@@ -41,6 +45,12 @@ interface ChatHistorySidebarProps {
   onSelectSession: (sessionId: string) => void;
   onDeleteSession: (sessionId: string) => Promise<boolean>;
   onRenameSession: (sessionId: string, newTitle: string) => Promise<boolean>;
+  onArchiveSession?: (sessionId: string) => Promise<void>;
+  onUnarchiveSession?: (sessionId: string) => Promise<void>;
+  onDeleteSessions?: (sessionIds: string[]) => Promise<void>;
+  onArchiveSessions?: (sessionIds: string[]) => Promise<void>;
+  showArchived?: boolean;
+  onToggleShowArchived?: () => void;
 }
 
 export function ChatHistorySidebar({
@@ -50,12 +60,64 @@ export function ChatHistorySidebar({
   onNewSession,
   onSelectSession,
   onDeleteSession,
-  onRenameSession
+  onRenameSession,
+  onArchiveSession,
+  onUnarchiveSession,
+  onDeleteSessions,
+  onArchiveSessions,
+  showArchived = false,
+  onToggleShowArchived
 }: ChatHistorySidebarProps) {
   const { t } = useTranslation('common');
   const [editingId, setEditingId] = useState<string | null>(null);
   const [editTitle, setEditTitle] = useState('');
   const [deleteSessionId, setDeleteSessionId] = useState<string | null>(null);
+  const [isSelectionMode, setIsSelectionMode] = useState(false);
+  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set());
+  const [bulkDeleteOpen, setBulkDeleteOpen] = useState(false);
+  const [bulkArchiveOpen, setBulkArchiveOpen] = useState(false);
+
+  // Clear selection when exiting selection mode
+  const handleToggleSelectionMode = useCallback(() => {
+    setIsSelectionMode((prev) => {
+      if (prev) {
+        setSelectedIds(new Set());
+      }
+      return !prev;
+    });
+  }, []);
+
+  // Prune selectedIds when sessions change - removes IDs for sessions no longer displayed
+  // Also resets when showArchived toggles
+  // biome-ignore lint/correctness/useExhaustiveDependencies: showArchived is intentionally a dependency to reset selection on filter change
+  useEffect(() => {
+    setSelectedIds((prev) => {
+      if (prev.size === 0) return prev;
+      const validIds = new Set(sessions.map((s) => s.id));
+      const pruned = new Set([...prev].filter((id) => validIds.has(id)));
+      return pruned.size === prev.size ? prev : pruned;
+    });
+  }, [sessions, showArchived]);
+
+  const handleToggleSelect = useCallback((sessionId: string) => {
+    setSelectedIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(sessionId)) {
+        next.delete(sessionId);
+      } else {
+        next.add(sessionId);
+      }
+      return next;
+    });
+  }, []);
+
+  const handleSelectAll = useCallback(() => {
+    setSelectedIds(new Set(sessions.map((s) => s.id)));
+  }, [sessions]);
+
+  const handleClearSelection = useCallback(() => {
+    setSelectedIds(new Set());
+  }, []);
 
   const handleStartEdit = (session: InsightsSessionSummary) => {
     setEditingId(session.id);
@@ -82,6 +144,38 @@ export function ChatHistorySidebar({
     }
   };
 
+  const handleBulkDelete = async () => {
+    if (selectedIds.size > 0 && onDeleteSessions) {
+      try {
+        await onDeleteSessions(Array.from(selectedIds));
+        setSelectedIds(new Set());
+      } catch (error) {
+        console.error('Failed to delete sessions:', error);
+      } finally {
+        setBulkDeleteOpen(false);
+      }
+    }
+  };
+
+  const handleBulkArchive = () => {
+    if (selectedIds.size > 0 && onArchiveSessions) {
+      setBulkArchiveOpen(true);
+    }
+  };
+
+  const handleBulkArchiveConfirmed = async () => {
+    if (selectedIds.size > 0 && onArchiveSessions) {
+      try {
+        await onArchiveSessions(Array.from(selectedIds));
+        setSelectedIds(new Set());
+      } catch (error) {
+        console.error('Failed to archive sessions:', error);
+      } finally {
+        setBulkArchiveOpen(false);
+      }
+    }
+  };
+
   const formatDate = (date: Date) => {
     const now = new Date();
     const d = new Date(date);
@@ -89,11 +183,11 @@ export function ChatHistorySidebar({
     const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
 
     if (diffDays === 0) {
-      return 'Today';
+      return t('insights.today');
     } else if (diffDays === 1) {
-      return 'Yesterday';
+      return t('insights.yesterday');
     } else if (diffDays < 7) {
-      return `${diffDays} days ago`;
+      return t('insights.daysAgo', { count: diffDays });
     } else {
       return d.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
     }
@@ -109,27 +203,90 @@ export function ChatHistorySidebar({
     return groups;
   }, {} as Record<string, InsightsSessionSummary[]>);
 
+  // Sessions selected for bulk delete preview
+  const sessionsToDelete = sessions.filter((s) => selectedIds.has(s.id));
+
   return (
     <div className="flex h-full w-64 flex-col border-r border-border bg-muted/30">
       {/* Header */}
       <div className="flex items-center justify-between border-b border-border px-3 py-3">
-        <h3 className="text-sm font-medium text-foreground">Chat History</h3>
-        <Tooltip>
-          <TooltipTrigger asChild>
-            <Button
-              variant="ghost"
-              size="icon"
-              className="h-7 w-7"
-              onClick={onNewSession}
-              aria-label={t('accessibility.newConversationAriaLabel')}
-            >
-              <Plus className="h-4 w-4" />
-            </Button>
-          </TooltipTrigger>
-          <TooltipContent>{t('accessibility.newConversationAriaLabel')}</TooltipContent>
-        </Tooltip>
+        <h3 className="text-sm font-medium text-foreground">{t('insights.chatHistory')}</h3>
+        <div className="flex items-center gap-1">
+          {/* Selection mode toggle */}
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant={isSelectionMode ? 'secondary' : 'ghost'}
+                size="icon"
+                className="h-7 w-7"
+                onClick={handleToggleSelectionMode}
+                aria-label={isSelectionMode ? t('insights.exitSelectMode') : t('insights.selectMode')}
+              >
+                <CheckSquare className="h-4 w-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>
+              {isSelectionMode ? t('insights.exitSelectMode') : t('insights.selectMode')}
+            </TooltipContent>
+          </Tooltip>
+
+          {/* Show archived toggle */}
+          {onToggleShowArchived && (
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button
+                  variant={showArchived ? 'secondary' : 'ghost'}
+                  size="icon"
+                  className="h-7 w-7"
+                  onClick={onToggleShowArchived}
+                  aria-label={showArchived ? t('insights.hideArchived') : t('insights.showArchived')}
+                >
+                  <Archive className={cn('h-4 w-4', showArchived && 'text-primary')} />
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent>
+                {showArchived ? t('insights.hideArchived') : t('insights.showArchived')}
+              </TooltipContent>
+            </Tooltip>
+          )}
+
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant="ghost"
+                size="icon"
+                className="h-7 w-7"
+                onClick={onNewSession}
+                aria-label={t('accessibility.newConversationAriaLabel')}
+              >
+                <Plus className="h-4 w-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>{t('accessibility.newConversationAriaLabel')}</TooltipContent>
+          </Tooltip>
+        </div>
       </div>
 
+      {/* Select All / Clear links */}
+      {isSelectionMode && sessions.length > 0 && (
+        <div className="flex items-center justify-between border-b border-border px-3 py-1.5">
+          <button
+            type="button"
+            className="text-xs text-primary hover:underline"
+            onClick={handleSelectAll}
+          >
+            {t('accessibility.selectAllAriaLabel')}
+          </button>
+          <button
+            type="button"
+            className="text-xs text-muted-foreground hover:underline"
+            onClick={handleClearSelection}
+          >
+            {t('accessibility.clearSelectionAriaLabel')}
+          </button>
+        </div>
+      )}
+
       {/* Session list */}
       <ScrollArea className="flex-1">
         {isLoading ? (
@@ -138,7 +295,7 @@ export function ChatHistorySidebar({
           </div>
         ) : sessions.length === 0 ? (
           <div className="px-3 py-8 text-center text-sm text-muted-foreground">
-            No conversations yet
+            {t('insights.noConversations')}
           </div>
         ) : (
           <div className="py-2">
@@ -160,6 +317,14 @@ export function ChatHistorySidebar({
                     onCancelEdit={handleCancelEdit}
                     onEditTitleChange={setEditTitle}
                     onDelete={() => setDeleteSessionId(session.id)}
+                    onArchive={onArchiveSession ? () => onArchiveSession(session.id) : undefined}
+                    onUnarchive={
+                      onUnarchiveSession ? () => onUnarchiveSession(session.id) : undefined
+                    }
+                    isArchived={!!session.archivedAt}
+                    isSelectionMode={isSelectionMode}
+                    isSelected={selectedIds.has(session.id)}
+                    onToggleSelect={() => handleToggleSelect(session.id)}
                   />
                 ))}
               </div>
@@ -168,19 +333,94 @@ export function ChatHistorySidebar({
         )}
       </ScrollArea>
 
-      {/* Delete confirmation dialog */}
+      {/* Bulk action toolbar */}
+      {isSelectionMode && selectedIds.size > 0 && (
+        <div className="flex items-center gap-2 border-t border-border px-3 py-2">
+          <Button
+            variant="destructive"
+            size="sm"
+            className="flex-1 text-xs"
+            onClick={() => setBulkDeleteOpen(true)}
+          >
+            <Trash2 className="mr-1.5 h-3.5 w-3.5" />
+            {t('selection.deleteSelected')} ({selectedIds.size})
+          </Button>
+          {onArchiveSessions && (
+            <Button
+              variant="secondary"
+              size="sm"
+              className="flex-1 text-xs"
+              onClick={handleBulkArchive}
+            >
+              <Archive className="mr-1.5 h-3.5 w-3.5" />
+              {t('insights.archiveSelected')} ({selectedIds.size})
+            </Button>
+          )}
+        </div>
+      )}
+
+      {/* Single delete confirmation dialog */}
       <AlertDialog open={!!deleteSessionId} onOpenChange={() => setDeleteSessionId(null)}>
         <AlertDialogContent>
           <AlertDialogHeader>
-            <AlertDialogTitle>Delete conversation?</AlertDialogTitle>
+            <AlertDialogTitle>{t('insights.deleteTitle')}</AlertDialogTitle>
             <AlertDialogDescription>
-              This will permanently delete this conversation and all its messages.
-              This action cannot be undone.
+              {t('insights.deleteDescription')}
             </AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>
-            <AlertDialogCancel>Cancel</AlertDialogCancel>
-            <AlertDialogAction onClick={handleDelete}>Delete</AlertDialogAction>
+            <AlertDialogCancel>{t('buttons.cancel')}</AlertDialogCancel>
+            <AlertDialogAction onClick={handleDelete}>{t('actions.delete')}</AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+
+      {/* Bulk delete confirmation dialog */}
+      <AlertDialog open={bulkDeleteOpen} onOpenChange={setBulkDeleteOpen}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>{t('insights.bulkDeleteTitle')}</AlertDialogTitle>
+            <AlertDialogDescription>
+              {t('insights.bulkDeleteDescription', { count: selectedIds.size })}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          {sessionsToDelete.length > 0 && (
+            <div className="max-h-32 overflow-y-auto rounded border border-border p-2">
+              <p className="mb-1 text-xs font-medium text-muted-foreground">
+                {t('insights.conversationsToDelete')}:
+              </p>
+              <ul className="space-y-0.5">
+                {sessionsToDelete.map((s) => (
+                  <li key={s.id} className="truncate text-xs text-foreground/80">
+                    {s.title}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+          <AlertDialogFooter>
+            <AlertDialogCancel>{t('buttons.cancel')}</AlertDialogCancel>
+            <AlertDialogAction onClick={handleBulkDelete}>
+              {t('insights.bulkDeleteConfirm', { count: selectedIds.size })}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+
+      {/* Bulk archive confirmation dialog */}
+      <AlertDialog open={bulkArchiveOpen} onOpenChange={setBulkArchiveOpen}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>{t('insights.archiveConfirmTitle')}</AlertDialogTitle>
+            <AlertDialogDescription>
+              {t('insights.archiveConfirmDescription')}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>{t('buttons.cancel')}</AlertDialogCancel>
+            <AlertDialogAction onClick={handleBulkArchiveConfirmed}>
+              {t('insights.archiveConfirmButton', { count: selectedIds.size })}
+            </AlertDialogAction>
           </AlertDialogFooter>
         </AlertDialogContent>
       </AlertDialog>
@@ -199,6 +439,12 @@ interface SessionItemProps {
   onCancelEdit: () => void;
   onEditTitleChange: (title: string) => void;
   onDelete: () => void;
+  onArchive?: () => Promise<void>;
+  onUnarchive?: () => Promise<void>;
+  isArchived: boolean;
+  isSelectionMode: boolean;
+  isSelected: boolean;
+  onToggleSelect: () => void;
 }
 
 function SessionItem({
@@ -211,7 +457,13 @@ function SessionItem({
   onSaveEdit,
   onCancelEdit,
   onEditTitleChange,
-  onDelete
+  onDelete,
+  onArchive,
+  onUnarchive,
+  isArchived,
+  isSelectionMode,
+  isSelected,
+  onToggleSelect
 }: SessionItemProps) {
   const { t } = useTranslation('common');
   const handleKeyDown = (e: React.KeyboardEvent) => {
@@ -257,61 +509,107 @@ function SessionItem({
 
   return (
     <div
+      role={isSelectionMode ? 'checkbox' : 'button'}
+      aria-checked={isSelectionMode ? isSelected : undefined}
+      tabIndex={0}
       className={cn(
         'group relative cursor-pointer px-2 py-2 transition-colors hover:bg-muted',
-        isActive && 'bg-primary/10 hover:bg-primary/15'
+        isActive && 'bg-primary/10 hover:bg-primary/15',
+        isArchived && 'opacity-50'
       )}
-      onClick={onSelect}
+      onClick={isSelectionMode ? onToggleSelect : onSelect}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          isSelectionMode ? onToggleSelect() : onSelect();
+        }
+      }}
     >
       {/* Content with reserved space for the menu button */}
       <div className="flex items-center gap-1.5 pr-7">
-        <MessageSquare
-          className={cn(
-            'h-4 w-4 shrink-0',
-            isActive ? 'text-primary' : 'text-muted-foreground'
-          )}
-        />
-        <div className="min-w-0 flex-1">
-          <p
+        {isSelectionMode ? (
+          <div className="shrink-0">
+            <Checkbox
+              checked={isSelected}
+              className="h-4 w-4"
+              aria-hidden
+              tabIndex={-1}
+            />
+          </div>
+        ) : (
+          <MessageSquare
             className={cn(
-              'line-clamp-2 text-sm leading-tight break-words',
-              isActive ? 'font-medium text-foreground' : 'text-foreground/80'
+              'h-4 w-4 shrink-0',
+              isActive ? 'text-primary' : 'text-muted-foreground'
             )}
-          >
-            {session.title}
-          </p>
+          />
+        )}
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-1">
+            <p
+              className={cn(
+                'line-clamp-2 text-sm leading-tight break-words',
+                isActive ? 'font-medium text-foreground' : 'text-foreground/80'
+              )}
+            >
+              {session.title}
+            </p>
+            {isArchived && (
+              <span className="inline-flex items-center gap-0.5 rounded bg-muted px-1 py-0.5 text-[9px] font-medium text-muted-foreground">
+                <Archive className="h-2.5 w-2.5" />
+                {t('insights.archived')}
+              </span>
+            )}
+          </div>
           <p className="text-[11px] text-muted-foreground mt-0.5">
-            {session.messageCount} message{session.messageCount !== 1 ? 's' : ''}
+            {t('insights.messageCount', { count: session.messageCount })}
           </p>
         </div>
       </div>
 
-      {/* Absolutely positioned menu button - always visible */}
-      <DropdownMenu modal={false}>
-        <DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
-          <Button
-            variant="ghost"
-            size="icon"
-            className="absolute right-1 top-1/2 -translate-y-1/2 h-6 w-6 opacity-0 group-hover:opacity-100 data-[state=open]:opacity-100 hover:bg-muted-foreground/20 transition-opacity"
-            aria-label={t('accessibility.moreOptionsAriaLabel')}
-          >
-            <MoreVertical className="h-3.5 w-3.5" />
-          </Button>
-        </DropdownMenuTrigger>
-        <DropdownMenuContent align="end" sideOffset={5} className="w-36 z-[100]">
-          <DropdownMenuItem onSelect={onStartEdit}>
-            <Pencil className="mr-2 h-3.5 w-3.5" />
-            Rename
-          </DropdownMenuItem>
-          <DropdownMenuItem
-            onSelect={onDelete}
-            className="text-destructive focus:text-destructive"
-          >
-            <Trash2 className="mr-2 h-3.5 w-3.5" />
-            Delete
-          </DropdownMenuItem>
-        </DropdownMenuContent>
-      </DropdownMenu>
+      {/* Absolutely positioned menu button - hidden in selection mode */}
+      {!isSelectionMode && (
+        <DropdownMenu modal={false}>
+          <DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
+            <Button
+              variant="ghost"
+              size="icon"
+              className="absolute right-1 top-1/2 -translate-y-1/2 h-6 w-6 opacity-0 group-hover:opacity-100 data-[state=open]:opacity-100 hover:bg-muted-foreground/20 transition-opacity"
+              aria-label={t('accessibility.moreOptionsAriaLabel')}
+            >
+              <MoreVertical className="h-3.5 w-3.5" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" sideOffset={5} className="w-36 z-[100]">
+            <DropdownMenuItem onSelect={onStartEdit}>
+              <Pencil className="mr-2 h-3.5 w-3.5" />
+              {t('accessibility.renameAriaLabel')}
+            </DropdownMenuItem>
+            {isArchived ? (
+              onUnarchive && (
+                <DropdownMenuItem onSelect={onUnarchive}>
+                  <ArchiveRestore className="mr-2 h-3.5 w-3.5" />
+                  {t('insights.unarchive')}
+                </DropdownMenuItem>
+              )
+            ) : (
+              onArchive && (
+                <DropdownMenuItem onSelect={onArchive}>
+                  <Archive className="mr-2 h-3.5 w-3.5" />
+                  {t('insights.archive')}
+                </DropdownMenuItem>
+              )
+            )}
+            <DropdownMenuItem
+              onSelect={onDelete}
+              className="text-destructive focus:text-destructive"
+            >
+              <Trash2 className="mr-2 h-3.5 w-3.5" />
+              {t('accessibility.deleteAriaLabel')}
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      )}
     </div>
   );
 }

apps/frontend/src/renderer/components/CompetitorAnalysisDialog.tsx

@@ -1,4 +1,6 @@
-import { Search, Globe, AlertTriangle, TrendingUp } from 'lucide-react';
+import { useState, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Search, Globe, AlertTriangle, TrendingUp, UserPlus } from 'lucide-react';
 import {
   AlertDialog,
   AlertDialogContent,
@@ -9,12 +11,15 @@ import {
   AlertDialogAction,
   AlertDialogCancel,
 } from './ui/alert-dialog';
+import { Button } from './ui/button';
+import { AddCompetitorDialog } from './AddCompetitorDialog';
 
 interface CompetitorAnalysisDialogProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   onAccept: () => void;
   onDecline: () => void;
+  projectId: string;
 }
 
 export function CompetitorAnalysisDialog({
@@ -22,7 +27,19 @@ export function CompetitorAnalysisDialog({
   onOpenChange,
   onAccept,
   onDecline,
+  projectId,
 }: CompetitorAnalysisDialogProps) {
+  const { t } = useTranslation(['dialogs']);
+  const [showAddDialog, setShowAddDialog] = useState(false);
+  const [addedCount, setAddedCount] = useState(0);
+
+  // Reset addedCount when dialog reopens
+  useEffect(() => {
+    if (open) {
+      setAddedCount(0);
+    }
+  }, [open]);
+
   const handleAccept = () => {
     onAccept();
     onOpenChange(false);
@@ -33,78 +50,116 @@ export function CompetitorAnalysisDialog({
     onOpenChange(false);
   };
 
-  return (
-    <AlertDialog open={open} onOpenChange={onOpenChange}>
-      <AlertDialogContent className="sm:max-w-[500px]">
-        <AlertDialogHeader>
-          <AlertDialogTitle className="flex items-center gap-2 text-foreground">
-            <TrendingUp className="h-5 w-5 text-primary" />
-            Enable Competitor Analysis?
-          </AlertDialogTitle>
-          <AlertDialogDescription className="text-muted-foreground">
-            Enhance your roadmap with insights from competitor products
-          </AlertDialogDescription>
-        </AlertDialogHeader>
+  const handleCompetitorAdded = (_competitorId: string) => {
+    setAddedCount((prev) => prev + 1);
+  };
 
-        <div className="py-4 space-y-4">
-          {/* What it does */}
-          <div className="rounded-lg bg-primary/5 border border-primary/20 p-4">
-            <h4 className="text-sm font-medium text-foreground mb-2">
-              What competitor analysis does:
-            </h4>
-            <ul className="text-sm text-muted-foreground space-y-2">
-              <li className="flex items-start gap-2">
-                <Search className="h-4 w-4 mt-0.5 text-primary flex-shrink-0" />
-                <span>Identifies 3-5 main competitors based on your project type</span>
-              </li>
-              <li className="flex items-start gap-2">
-                <Globe className="h-4 w-4 mt-0.5 text-primary flex-shrink-0" />
-                <span>
-                  Searches app stores, forums, and social media for user feedback and pain points
-                </span>
-              </li>
-              <li className="flex items-start gap-2">
-                <TrendingUp className="h-4 w-4 mt-0.5 text-primary flex-shrink-0" />
-                <span>
-                  Suggests features that address gaps in competitor products
-                </span>
-              </li>
-            </ul>
+  return (
+    <>
+      <AlertDialog open={open} onOpenChange={onOpenChange}>
+        <AlertDialogContent className="sm:max-w-[500px]">
+          <AlertDialogHeader>
+            <AlertDialogTitle className="flex items-center gap-2 text-foreground">
+              <TrendingUp className="h-5 w-5 text-primary" />
+              {t('dialogs:competitorAnalysis.title', 'Enable Competitor Analysis?')}
+            </AlertDialogTitle>
+            <AlertDialogDescription className="text-muted-foreground">
+              {t('dialogs:competitorAnalysis.description', 'Enhance your roadmap with insights from competitor products')}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+
+          <div className="py-4 space-y-4">
+            {/* What it does */}
+            <div className="rounded-lg bg-primary/5 border border-primary/20 p-4">
+              <h4 className="text-sm font-medium text-foreground mb-2">
+                {t('dialogs:competitorAnalysis.whatItDoes', 'What competitor analysis does:')}
+              </h4>
+              <ul className="text-sm text-muted-foreground space-y-2">
+                <li className="flex items-start gap-2">
+                  <Search className="h-4 w-4 mt-0.5 text-primary flex-shrink-0" />
+                  <span>{t('dialogs:competitorAnalysis.identifiesCompetitors', 'Identifies 3-5 main competitors based on your project type')}</span>
+                </li>
+                <li className="flex items-start gap-2">
+                  <Globe className="h-4 w-4 mt-0.5 text-primary flex-shrink-0" />
+                  <span>
+                    {t('dialogs:competitorAnalysis.searchesAppStores', 'Searches app stores, forums, and social media for user feedback and pain points')}
+                  </span>
+                </li>
+                <li className="flex items-start gap-2">
+                  <TrendingUp className="h-4 w-4 mt-0.5 text-primary flex-shrink-0" />
+                  <span>
+                    {t('dialogs:competitorAnalysis.suggestsFeatures', 'Suggests features that address gaps in competitor products')}
+                  </span>
+                </li>
+              </ul>
+            </div>
+
+            {/* Privacy notice */}
+            <div className="rounded-lg bg-warning/10 border border-warning/30 p-4">
+              <div className="flex items-start gap-3">
+                <AlertTriangle className="h-5 w-5 text-warning flex-shrink-0 mt-0.5" />
+                <div className="flex-1">
+                  <h4 className="text-sm font-medium text-foreground">
+                    {t('dialogs:competitorAnalysis.webSearchesTitle', 'Web searches will be performed')}
+                  </h4>
+                  <p className="text-xs text-muted-foreground mt-1">
+                    {t('dialogs:competitorAnalysis.webSearchesDescription', 'This feature will perform web searches to gather competitor information. Your project name and type will be used in search queries. No code or sensitive data is shared.')}
+                  </p>
+                </div>
+              </div>
+            </div>
+
+            {/* Optional info */}
+            <p className="text-xs text-muted-foreground">
+              {t('dialogs:competitorAnalysis.optionalInfo', 'You can generate a roadmap without competitor analysis if you prefer. The roadmap will still be based on your project structure and best practices.')}
+            </p>
           </div>
 
-          {/* Privacy notice */}
-          <div className="rounded-lg bg-warning/10 border border-warning/30 p-4">
-            <div className="flex items-start gap-3">
-              <AlertTriangle className="h-5 w-5 text-warning flex-shrink-0 mt-0.5" />
+          {/* Add Known Competitors section */}
+          <div className="border-t border-border pt-4">
+            <div className="flex items-center justify-between">
               <div className="flex-1">
-                <h4 className="text-sm font-medium text-foreground">
-                  Web searches will be performed
-                </h4>
-                <p className="text-xs text-muted-foreground mt-1">
-                  This feature will perform web searches to gather competitor information.
-                  Your project name and type will be used in search queries.
-                  No code or sensitive data is shared.
+                <p className="text-sm text-muted-foreground">
+                  {t('dialogs:competitorAnalysis.knowYourCompetitors', 'Already know your competitors?')}
+                </p>
+                <p className="text-xs text-muted-foreground/70 mt-0.5">
+                  {t('dialogs:competitorAnalysis.addThemDirectly', 'Add them directly to improve analysis accuracy')}
                 </p>
               </div>
+              <Button
+                variant="outline"
+                size="sm"
+                className="flex items-center gap-1.5"
+                onClick={() => setShowAddDialog(true)}
+              >
+                <UserPlus className="h-3.5 w-3.5" />
+                {t('dialogs:competitorAnalysis.addKnownCompetitors', 'Add Known Competitors')}
+                {addedCount > 0 && (
+                  <span className="ml-1 rounded-full bg-primary px-1.5 py-0.5 text-[10px] font-medium text-primary-foreground">
+                    {t('dialogs:competitorAnalysis.competitorsAdded', '{{count}} added', { count: addedCount })}
+                  </span>
+                )}
+              </Button>
             </div>
           </div>
 
-          {/* Optional info */}
-          <p className="text-xs text-muted-foreground">
-            You can generate a roadmap without competitor analysis if you prefer.
-            The roadmap will still be based on your project structure and best practices.
-          </p>
-        </div>
+          <AlertDialogFooter>
+            <AlertDialogCancel onClick={handleDecline}>
+              {t('dialogs:competitorAnalysis.skipAnalysis', 'No, Skip Analysis')}
+            </AlertDialogCancel>
+            <AlertDialogAction onClick={handleAccept}>
+              {t('dialogs:competitorAnalysis.enableAnalysis', 'Yes, Enable Analysis')}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
 
-        <AlertDialogFooter>
-          <AlertDialogCancel onClick={handleDecline}>
-            No, Skip Analysis
-          </AlertDialogCancel>
-          <AlertDialogAction onClick={handleAccept}>
-            Yes, Enable Analysis
-          </AlertDialogAction>
-        </AlertDialogFooter>
-      </AlertDialogContent>
-    </AlertDialog>
+      <AddCompetitorDialog
+        open={showAddDialog}
+        onOpenChange={setShowAddDialog}
+        onCompetitorAdded={handleCompetitorAdded}
+        projectId={projectId}
+      />
+    </>
   );
 }

apps/frontend/src/renderer/components/CompetitorAnalysisViewer.tsx

@@ -1,5 +1,6 @@
+import { useState } from 'react';
 import { useTranslation } from 'react-i18next';
-import { TrendingUp, ExternalLink, AlertCircle } from 'lucide-react';
+import { TrendingUp, ExternalLink, AlertCircle, Plus } from 'lucide-react';
 import {
   Dialog,
   DialogContent,
@@ -8,35 +9,50 @@ import {
   DialogDescription,
 } from './ui/dialog';
 import { Badge } from './ui/badge';
+import { Button } from './ui/button';
 import { ScrollArea } from './ui/scroll-area';
+import { AddCompetitorDialog } from './AddCompetitorDialog';
 import type { CompetitorAnalysis } from '../../shared/types';
 
 interface CompetitorAnalysisViewerProps {
   analysis: CompetitorAnalysis | null;
   open: boolean;
   onOpenChange: (open: boolean) => void;
+  projectId: string;
 }
 
 export function CompetitorAnalysisViewer({
   analysis,
   open,
   onOpenChange,
+  projectId,
 }: CompetitorAnalysisViewerProps) {
   const { t } = useTranslation('common');
+  const [showAddDialog, setShowAddDialog] = useState(false);
 
   if (!analysis) return null;
 
   return (
+    <>
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent className="max-w-4xl max-h-[85vh] flex flex-col">
         <DialogHeader>
           <DialogTitle className="flex items-center gap-2">
             <TrendingUp className="h-5 w-5 text-primary" />
-            Competitor Analysis Results
+            {t('competitorAnalysis.analysisResults')}
           </DialogTitle>
           <DialogDescription>
-            Analyzed {analysis.competitors.length} competitors to identify market gaps and opportunities
+            {t('competitorAnalysis.analysisDescription', { count: analysis.competitors.length })}
           </DialogDescription>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => setShowAddDialog(true)}
+            className="mt-2 self-start"
+          >
+            <Plus className="h-4 w-4 mr-1" />
+            {t('competitorAnalysis.addCompetitor')}
+          </Button>
         </DialogHeader>
 
         <ScrollArea className="flex-1 overflow-auto pr-4" style={{ maxHeight: 'calc(85vh - 120px)' }}>
@@ -51,6 +67,11 @@ export function CompetitorAnalysisViewer({
                   <div className="flex-1">
                     <div className="flex items-center gap-2 mb-1">
                       <h3 className="text-lg font-semibold">{competitor.name}</h3>
+                      {competitor.source === 'manual' && (
+                        <Badge variant="outline" className="text-xs">
+                          {t('competitorAnalysis.manualBadge')}
+                        </Badge>
+                      )}
                       {competitor.marketPosition && (
                         <Badge variant="secondary" className="text-xs">
                           {competitor.marketPosition}
@@ -72,7 +93,7 @@ export function CompetitorAnalysisViewer({
                       aria-label={t('accessibility.visitExternalLink', { name: competitor.name })}
                     >
                       <ExternalLink className="h-3 w-3" aria-hidden="true" />
-                      Visit
+                      {t('competitorAnalysis.visit')}
                       <span className="sr-only">({t('accessibility.opensInNewWindow')})</span>
                     </a>
                   )}
@@ -82,12 +103,12 @@ export function CompetitorAnalysisViewer({
                 <div>
                   <h4 className="text-sm font-medium mb-2 flex items-center gap-2">
                     <AlertCircle className="h-4 w-4 text-warning" />
-                    Identified Pain Points ({competitor.painPoints.length})
+                    {t('competitorAnalysis.identifiedPainPoints', { count: competitor.painPoints.length })}
                   </h4>
                   <div className="space-y-2">
                     {competitor.painPoints.length === 0 ? (
                       <p className="text-sm text-muted-foreground italic">
-                        No pain points identified
+                        {t('competitorAnalysis.noPainPointsIdentified')}
                       </p>
                     ) : (
                       competitor.painPoints.map((painPoint) => (
@@ -115,21 +136,21 @@ export function CompetitorAnalysisViewer({
                               {painPoint.source && (
                                 <div className="mt-2">
                                   <span className="text-xs text-muted-foreground">
-                                    Source: <span className="italic">{painPoint.source}</span>
+                                    {t('competitorAnalysis.source')} <span className="italic">{painPoint.source}</span>
                                   </span>
                                 </div>
                               )}
                               {painPoint.frequency && (
                                 <div className="mt-1">
                                   <span className="text-xs text-muted-foreground">
-                                    Frequency: {painPoint.frequency}
+                                    {t('competitorAnalysis.frequency')} {painPoint.frequency}
                                   </span>
                                 </div>
                               )}
                               {painPoint.opportunity && (
                                 <div className="mt-1">
                                   <span className="text-xs text-muted-foreground">
-                                    Opportunity:{' '}
+                                    {t('competitorAnalysis.opportunity')}{' '}
                                     <span className="font-medium text-foreground">
                                       {painPoint.opportunity}
                                     </span>
@@ -149,11 +170,11 @@ export function CompetitorAnalysisViewer({
             {/* Insights Summary */}
             {analysis.insightsSummary && (
               <div className="rounded-lg bg-primary/5 border border-primary/20 p-4 space-y-3">
-                <h4 className="text-sm font-semibold">Market Insights Summary</h4>
+                <h4 className="text-sm font-semibold">{t('competitorAnalysis.marketInsightsSummary')}</h4>
 
                 {analysis.insightsSummary.topPainPoints.length > 0 && (
                   <div>
-                    <p className="text-xs font-medium text-muted-foreground mb-1">Top Pain Points:</p>
+                    <p className="text-xs font-medium text-muted-foreground mb-1">{t('competitorAnalysis.topPainPoints')}</p>
                     <ul className="text-sm space-y-1">
                       {analysis.insightsSummary.topPainPoints.map((point, idx) => (
                         <li key={idx} className="text-muted-foreground">• {point}</li>
@@ -164,7 +185,7 @@ export function CompetitorAnalysisViewer({
 
                 {analysis.insightsSummary.differentiatorOpportunities.length > 0 && (
                   <div>
-                    <p className="text-xs font-medium text-muted-foreground mb-1">Differentiator Opportunities:</p>
+                    <p className="text-xs font-medium text-muted-foreground mb-1">{t('competitorAnalysis.differentiatorOpportunities')}</p>
                     <ul className="text-sm space-y-1">
                       {analysis.insightsSummary.differentiatorOpportunities.map((opp, idx) => (
                         <li key={idx} className="text-muted-foreground">• {opp}</li>
@@ -175,7 +196,7 @@ export function CompetitorAnalysisViewer({
 
                 {analysis.insightsSummary.marketTrends.length > 0 && (
                   <div>
-                    <p className="text-xs font-medium text-muted-foreground mb-1">Market Trends:</p>
+                    <p className="text-xs font-medium text-muted-foreground mb-1">{t('competitorAnalysis.marketTrends')}</p>
                     <ul className="text-sm space-y-1">
                       {analysis.insightsSummary.marketTrends.map((trend, idx) => (
                         <li key={idx} className="text-muted-foreground">• {trend}</li>
@@ -189,5 +210,12 @@ export function CompetitorAnalysisViewer({
         </ScrollArea>
       </DialogContent>
     </Dialog>
+
+    <AddCompetitorDialog
+      open={showAddDialog}
+      onOpenChange={setShowAddDialog}
+      projectId={projectId}
+    />
+    </>
   );
 }

apps/frontend/src/renderer/components/ExistingCompetitorAnalysisDialog.tsx

@@ -1,4 +1,6 @@
-import { Globe, RefreshCw, TrendingUp, CheckCircle } from 'lucide-react';
+import { useState, useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Globe, RefreshCw, TrendingUp, CheckCircle, UserPlus } from 'lucide-react';
 import {
   AlertDialog,
   AlertDialogContent,
@@ -8,6 +10,7 @@ import {
   AlertDialogTitle,
 } from './ui/alert-dialog';
 import { Button } from './ui/button';
+import { AddCompetitorDialog } from './AddCompetitorDialog';
 
 interface ExistingCompetitorAnalysisDialogProps {
   open: boolean;
@@ -15,7 +18,9 @@ interface ExistingCompetitorAnalysisDialogProps {
   onUseExisting: () => void;
   onRunNew: () => void;
   onSkip: () => void;
+  onCompetitorAdded?: (competitorId: string) => void;
   analysisDate?: Date;
+  projectId: string;
 }
 
 export function ExistingCompetitorAnalysisDialog({
@@ -24,8 +29,20 @@ export function ExistingCompetitorAnalysisDialog({
   onUseExisting,
   onRunNew,
   onSkip,
+  onCompetitorAdded,
   analysisDate,
+  projectId,
 }: ExistingCompetitorAnalysisDialogProps) {
+  const { t, i18n } = useTranslation(['dialogs']);
+  const [showAddDialog, setShowAddDialog] = useState(false);
+
+  // Reset child dialog state when this dialog reopens
+  useEffect(() => {
+    if (open) {
+      setShowAddDialog(false);
+    }
+  }, [open]);
+
   const handleUseExisting = () => {
     onUseExisting();
     onOpenChange(false);
@@ -42,8 +59,8 @@ export function ExistingCompetitorAnalysisDialog({
   };
 
   const formatDate = (date?: Date) => {
-    if (!date) return 'recently';
-    return new Intl.DateTimeFormat('en-US', {
+    if (!date) return t('dialogs:existingCompetitorAnalysis.recently');
+    return new Intl.DateTimeFormat(i18n.language, {
       month: 'short',
       day: 'numeric',
       year: 'numeric',
@@ -51,81 +68,112 @@ export function ExistingCompetitorAnalysisDialog({
   };
 
   return (
-    <AlertDialog open={open} onOpenChange={onOpenChange}>
-      <AlertDialogContent className="sm:max-w-[500px]">
-        <AlertDialogHeader>
-          <AlertDialogTitle className="flex items-center gap-2 text-foreground">
-            <TrendingUp className="h-5 w-5 text-primary" />
-            Competitor Analysis Options
-          </AlertDialogTitle>
-          <AlertDialogDescription className="text-muted-foreground">
-            This project has an existing competitor analysis from {formatDate(analysisDate)}
-          </AlertDialogDescription>
-        </AlertDialogHeader>
+    <>
+      <AlertDialog open={open} onOpenChange={onOpenChange}>
+        <AlertDialogContent className="sm:max-w-[500px]">
+          <AlertDialogHeader>
+            <AlertDialogTitle className="flex items-center gap-2 text-foreground">
+              <TrendingUp className="h-5 w-5 text-primary" />
+              {t('dialogs:existingCompetitorAnalysis.title')}
+            </AlertDialogTitle>
+            <AlertDialogDescription className="text-muted-foreground">
+              {t('dialogs:existingCompetitorAnalysis.description', { date: formatDate(analysisDate) })}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
 
-        <div className="py-4 space-y-3">
-          {/* Option 1: Use existing (recommended) */}
-          <button
-            onClick={handleUseExisting}
-            className="w-full rounded-lg bg-primary/10 border border-primary/30 p-4 text-left hover:bg-primary/20 transition-colors"
-          >
-            <div className="flex items-start gap-3">
-              <CheckCircle className="h-5 w-5 text-primary flex-shrink-0 mt-0.5" />
-              <div className="flex-1">
-                <h4 className="text-sm font-medium text-foreground flex items-center gap-2">
-                  Use existing analysis
-                  <span className="text-xs text-primary font-normal">(Recommended)</span>
-                </h4>
-                <p className="text-xs text-muted-foreground mt-1">
-                  Reuse the competitor insights you already have. Faster and no additional web searches.
-                </p>
+          <div className="py-4 space-y-3">
+            {/* Option 1: Use existing (recommended) */}
+            <button
+              type="button"
+              onClick={handleUseExisting}
+              className="w-full rounded-lg bg-primary/10 border border-primary/30 p-4 text-left hover:bg-primary/20 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+            >
+              <div className="flex items-start gap-3">
+                <CheckCircle className="h-5 w-5 text-primary flex-shrink-0 mt-0.5" />
+                <div className="flex-1">
+                  <h4 className="text-sm font-medium text-foreground flex items-center gap-2">
+                    {t('dialogs:existingCompetitorAnalysis.useExistingTitle')}
+                    <span className="text-xs text-primary font-normal">{t('dialogs:existingCompetitorAnalysis.recommended')}</span>
+                  </h4>
+                  <p className="text-xs text-muted-foreground mt-1">
+                    {t('dialogs:existingCompetitorAnalysis.useExistingDescription')}
+                  </p>
+                </div>
               </div>
-            </div>
-          </button>
+            </button>
 
-          {/* Option 2: Run new analysis */}
-          <button
-            onClick={handleRunNew}
-            className="w-full rounded-lg bg-muted/50 border border-border p-4 text-left hover:bg-muted transition-colors"
-          >
-            <div className="flex items-start gap-3">
-              <RefreshCw className="h-5 w-5 text-muted-foreground flex-shrink-0 mt-0.5" />
-              <div className="flex-1">
-                <h4 className="text-sm font-medium text-foreground">
-                  Run new analysis
-                </h4>
-                <p className="text-xs text-muted-foreground mt-1">
-                  Perform fresh web searches to get updated competitor information. Takes longer.
-                </p>
+            {/* Option 2: Run new analysis */}
+            <button
+              type="button"
+              onClick={handleRunNew}
+              className="w-full rounded-lg bg-muted/50 border border-border p-4 text-left hover:bg-muted transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+            >
+              <div className="flex items-start gap-3">
+                <RefreshCw className="h-5 w-5 text-muted-foreground flex-shrink-0 mt-0.5" />
+                <div className="flex-1">
+                  <h4 className="text-sm font-medium text-foreground">
+                    {t('dialogs:existingCompetitorAnalysis.runNewTitle')}
+                  </h4>
+                  <p className="text-xs text-muted-foreground mt-1">
+                    {t('dialogs:existingCompetitorAnalysis.runNewDescription')}
+                  </p>
+                </div>
               </div>
-            </div>
-          </button>
+            </button>
 
-          {/* Option 3: Skip */}
-          <button
-            onClick={handleSkip}
-            className="w-full rounded-lg bg-muted/30 border border-border/50 p-4 text-left hover:bg-muted/50 transition-colors"
-          >
-            <div className="flex items-start gap-3">
-              <Globe className="h-5 w-5 text-muted-foreground/60 flex-shrink-0 mt-0.5" />
-              <div className="flex-1">
-                <h4 className="text-sm font-medium text-muted-foreground">
-                  Skip competitor analysis
-                </h4>
-                <p className="text-xs text-muted-foreground/80 mt-1">
-                  Generate roadmap without any competitor insights.
-                </p>
+            {/* Option 3: Add known competitors */}
+            <button
+              type="button"
+              onClick={() => setShowAddDialog(true)}
+              className="w-full rounded-lg bg-muted/50 border border-border p-4 text-left hover:bg-muted transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+            >
+              <div className="flex items-start gap-3">
+                <UserPlus className="h-5 w-5 text-muted-foreground flex-shrink-0 mt-0.5" />
+                <div className="flex-1">
+                  <h4 className="text-sm font-medium text-foreground">
+                    {t('dialogs:competitorAnalysis.addKnownCompetitors')}
+                  </h4>
+                  <p className="text-xs text-muted-foreground mt-1">
+                    {t('dialogs:competitorAnalysis.addKnownCompetitorsDescription')}
+                  </p>
+                </div>
               </div>
-            </div>
-          </button>
-        </div>
+            </button>
 
-        <AlertDialogFooter className="sm:justify-start">
-          <Button variant="ghost" onClick={() => onOpenChange(false)}>
-            Cancel
-          </Button>
-        </AlertDialogFooter>
-      </AlertDialogContent>
-    </AlertDialog>
+            {/* Option 4: Skip */}
+            <button
+              type="button"
+              onClick={handleSkip}
+              className="w-full rounded-lg bg-muted/30 border border-border/50 p-4 text-left hover:bg-muted/50 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2"
+            >
+              <div className="flex items-start gap-3">
+                <Globe className="h-5 w-5 text-muted-foreground/60 flex-shrink-0 mt-0.5" />
+                <div className="flex-1">
+                  <h4 className="text-sm font-medium text-muted-foreground">
+                    {t('dialogs:existingCompetitorAnalysis.skipTitle')}
+                  </h4>
+                  <p className="text-xs text-muted-foreground/80 mt-1">
+                    {t('dialogs:existingCompetitorAnalysis.skipDescription')}
+                  </p>
+                </div>
+              </div>
+            </button>
+          </div>
+
+          <AlertDialogFooter className="sm:justify-start">
+            <Button variant="ghost" onClick={() => onOpenChange(false)}>
+              {t('dialogs:existingCompetitorAnalysis.cancel')}
+            </Button>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+
+      <AddCompetitorDialog
+        open={showAddDialog}
+        onOpenChange={setShowAddDialog}
+        onCompetitorAdded={onCompetitorAdded}
+        projectId={projectId}
+      />
+    </>
   );
 }

apps/frontend/src/renderer/components/Insights.tsx

@@ -14,7 +14,9 @@ import {
   FileText,
   FolderSearch,
   PanelLeftClose,
-  PanelLeft
+  PanelLeft,
+  Camera,
+  X
 } from 'lucide-react';
 import ReactMarkdown, { type Components } from 'react-markdown';
 import remarkGfm from 'remark-gfm';
@@ -23,6 +25,7 @@ import { Textarea } from './ui/textarea';
 import { ScrollArea } from './ui/scroll-area';
 import { Card, CardContent } from './ui/card';
 import { Badge } from './ui/badge';
+import { ScreenshotCapture } from './ScreenshotCapture';
 import { cn } from '../lib/utils';
 import {
   useInsightsStore,
@@ -31,20 +34,29 @@ import {
   newSession,
   switchSession,
   deleteSession,
+  deleteSessions,
   renameSession,
+  archiveSession,
+  archiveSessions,
+  unarchiveSession,
   updateModelConfig,
   createTaskFromSuggestion,
-  setupInsightsListeners
+  setupInsightsListeners,
+  loadInsightsSessions
 } from '../stores/insights-store';
+import { useImageUpload } from './task-form/useImageUpload';
+import { createThumbnail, generateImageId } from './ImageUpload';
 import { loadTasks } from '../stores/task-store';
 import { ChatHistorySidebar } from './ChatHistorySidebar';
 import { InsightsModelSelector } from './InsightsModelSelector';
-import type { InsightsChatMessage, InsightsModelConfig, TaskMetadata } from '../../shared/types';
+import type { InsightsChatMessage, InsightsModelConfig, TaskMetadata, ImageAttachment } from '../../shared/types';
 import {
   TASK_CATEGORY_LABELS,
   TASK_CATEGORY_COLORS,
   TASK_COMPLEXITY_LABELS,
-  TASK_COMPLEXITY_COLORS
+  TASK_COMPLEXITY_COLORS,
+  MAX_IMAGE_SIZE,
+  MAX_IMAGES_PER_TASK
 } from '../../shared/constants';
 
 // createSafeLink - factory function that creates a SafeLink component with i18n support
@@ -105,11 +117,41 @@ export function Insights({ projectId }: InsightsProps) {
   const [creatingTask, setCreatingTask] = useState<Set<string>>(new Set());
   const [taskCreated, setTaskCreated] = useState<Set<string>>(new Set());
   const [showSidebar, setShowSidebar] = useState(true);
+  const showArchived = useInsightsStore((state) => state.showArchived);
   const [isUserAtBottom, setIsUserAtBottom] = useState(true);
   const [viewportEl, setViewportEl] = useState<HTMLElement | null>(null);
+  const [screenshotOpen, setScreenshotOpen] = useState(false);
+  const [imageError, setImageError] = useState<string | null>(null);
+
+  const pendingImages = useInsightsStore((state) => state.pendingImages);
+  const setPendingImages = useInsightsStore((state) => state.setPendingImages);
 
   const textareaRef = useRef<HTMLTextAreaElement | null>(null);
 
+  const isLoading = status.phase === 'thinking' || status.phase === 'streaming';
+
+  // Image upload hook
+  const {
+    isDragOver,
+    handlePaste,
+    handleDragOver,
+    handleDragLeave,
+    handleDrop,
+    removeImage,
+    canAddMore
+  } = useImageUpload({
+    images: pendingImages,
+    onImagesChange: setPendingImages,
+    disabled: isLoading,
+    onError: setImageError,
+    errorMessages: {
+      maxImagesReached: t('insights.images.maxImagesReached'),
+      invalidImageType: t('insights.images.invalidType'),
+      processPasteFailed: t('insights.images.processFailed'),
+      processDropFailed: t('insights.images.processFailed')
+    }
+  });
+
   // Scroll threshold in pixels - user is considered "at bottom" if within this distance
   const SCROLL_BOTTOM_THRESHOLD = 100;
 
@@ -138,11 +180,23 @@ export function Insights({ projectId }: InsightsProps) {
 
   // Load session and set up listeners on mount
   useEffect(() => {
-    loadInsightsSession(projectId);
+    loadInsightsSession(projectId, showArchived);
     const cleanup = setupInsightsListeners();
     return cleanup;
+  // biome-ignore lint/correctness/useExhaustiveDependencies: showArchived is handled by the dedicated effect below; including it here would cause duplicate loads
   }, [projectId]);
 
+  // Reload sessions when showArchived changes (skip first run to avoid duplicate load with mount effect)
+  const isFirstRun = useRef(true);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: projectId changes are handled by the mount effect above; this effect only reacts to showArchived toggles
+  useEffect(() => {
+    if (isFirstRun.current) {
+      isFirstRun.current = false;
+      return;
+    }
+    loadInsightsSessions(projectId, showArchived);
+  }, [showArchived]);
+
   // Smart auto-scroll: only scroll if user is already at bottom
   // This allows users to scroll up to read previous messages without being
   // yanked back down during streaming responses
@@ -158,6 +212,7 @@ export function Insights({ projectId }: InsightsProps) {
   }, []);
 
   // Reset task creation state when switching sessions
+  // biome-ignore lint/correctness/useExhaustiveDependencies: session?.id is intentionally used as a trigger
   useEffect(() => {
     setTaskCreated(new Set());
     setCreatingTask(new Set());
@@ -165,13 +220,46 @@ export function Insights({ projectId }: InsightsProps) {
 
   const handleSend = () => {
     const message = inputValue.trim();
-    if (!message || status.phase === 'thinking' || status.phase === 'streaming') return;
+    const hasImages = pendingImages.length > 0;
+    if ((!message && !hasImages) || isLoading) return;
 
     setInputValue('');
-    sendMessage(projectId, message);
+    sendMessage(projectId, message, session?.modelConfig, hasImages ? pendingImages : undefined);
+    setPendingImages([]);
+    setImageError(null);
     setIsUserAtBottom(true); // Resume auto-scroll when user sends a message
   };
 
+  const handleScreenshotCapture = useCallback(async (imageData: string) => {
+    // Check image count limit before processing
+    if (pendingImages.length >= MAX_IMAGES_PER_TASK) {
+      setImageError(t('insights.images.maxImagesReached'));
+      return;
+    }
+
+    // imageData is base64 PNG from ScreenshotCapture
+    const approximateSize = Math.ceil(imageData.length * 0.75); // approximate base64 size
+
+    // Validate size - match the validation used for regular image uploads
+    if (approximateSize > MAX_IMAGE_SIZE) {
+      setImageError(t('insights.images.screenshotTooLarge', { size: Math.round(approximateSize / 1024 / 1024), max: Math.round(MAX_IMAGE_SIZE / 1024 / 1024) }));
+      return;
+    }
+
+    const dataUrl = `data:image/png;base64,${imageData}`;
+    const thumbnail = await createThumbnail(dataUrl);
+    const newImage: ImageAttachment = {
+      id: generateImageId(),
+      filename: `screenshot-${Date.now()}.png`,
+      mimeType: 'image/png',
+      size: approximateSize,
+      data: imageData,
+      thumbnail
+    };
+    setPendingImages([...pendingImages, newImage]);
+    setImageError(null);
+  }, [pendingImages, setPendingImages, setImageError, t]);
+
   const handleKeyDown = (e: React.KeyboardEvent) => {
     if (e.key === 'Enter' && !e.shiftKey) {
       e.preventDefault();
@@ -192,13 +280,71 @@ export function Insights({ projectId }: InsightsProps) {
   };
 
   const handleDeleteSession = async (sessionId: string): Promise<boolean> => {
-    return await deleteSession(projectId, sessionId);
+    return await deleteSession(projectId, sessionId, showArchived);
   };
 
   const handleRenameSession = async (sessionId: string, newTitle: string): Promise<boolean> => {
     return await renameSession(projectId, sessionId, newTitle);
   };
 
+  const handleArchiveSession = async (sessionId: string) => {
+    try {
+      await archiveSession(projectId, sessionId);
+      await loadInsightsSessions(projectId, showArchived);
+      // Reload current session in case backend switched to a different one
+      await loadInsightsSession(projectId, showArchived);
+    } catch (error) {
+      console.error(`Failed to archive session ${sessionId}:`, error);
+    }
+  };
+
+  const handleUnarchiveSession = async (sessionId: string) => {
+    try {
+      await unarchiveSession(projectId, sessionId);
+      await loadInsightsSessions(projectId, showArchived);
+      // Reload current session in case backend switched to a different one
+      await loadInsightsSession(projectId, showArchived);
+    } catch (error) {
+      console.error(`Failed to unarchive session ${sessionId}:`, error);
+    }
+  };
+
+  const handleDeleteSessions = async (sessionIds: string[]) => {
+    try {
+      const result = await deleteSessions(projectId, sessionIds);
+      await loadInsightsSessions(projectId, showArchived);
+      // Reload current session in case backend switched to a different one
+      await loadInsightsSession(projectId, showArchived);
+
+      // Log partial failures for debugging
+      if (result.failedIds && result.failedIds.length > 0) {
+        console.warn(`Failed to delete ${result.failedIds.length} session(s):`, result.failedIds);
+      }
+    } catch (error) {
+      console.error(`Failed to delete sessions ${sessionIds.join(', ')}:`, error);
+    }
+  };
+
+  const handleArchiveSessions = async (sessionIds: string[]) => {
+    try {
+      const result = await archiveSessions(projectId, sessionIds);
+      await loadInsightsSessions(projectId, showArchived);
+      // Reload current session in case backend switched to a different one
+      await loadInsightsSession(projectId, showArchived);
+
+      // Log partial failures for debugging
+      if (result.failedIds && result.failedIds.length > 0) {
+        console.warn(`Failed to archive ${result.failedIds.length} session(s):`, result.failedIds);
+      }
+    } catch (error) {
+      console.error(`Failed to archive sessions ${sessionIds.join(', ')}:`, error);
+    }
+  };
+
+  const handleToggleShowArchived = () => {
+    useInsightsStore.getState().setShowArchived(!showArchived);
+  };
+
   const handleCreateTask = async (
     messageId: string,
     taskIndex: number,
@@ -235,7 +381,6 @@ export function Insights({ projectId }: InsightsProps) {
     }
   };
 
-  const isLoading = status.phase === 'thinking' || status.phase === 'streaming';
   const messages = session?.messages || [];
 
   return (
@@ -250,6 +395,12 @@ export function Insights({ projectId }: InsightsProps) {
           onSelectSession={handleSelectSession}
           onDeleteSession={handleDeleteSession}
           onRenameSession={handleRenameSession}
+          onArchiveSession={handleArchiveSession}
+          onUnarchiveSession={handleUnarchiveSession}
+          onDeleteSessions={handleDeleteSessions}
+          onArchiveSessions={handleArchiveSessions}
+          showArchived={showArchived}
+          onToggleShowArchived={handleToggleShowArchived}
         />
       )}
 
@@ -402,32 +553,112 @@ export function Insights({ projectId }: InsightsProps) {
 
       {/* Input */}
       <div className="flex-shrink-0 border-t border-border p-4">
-        <div className="flex gap-2">
-          <Textarea
-            ref={textareaRef}
-            value={inputValue}
-            onChange={(e) => setInputValue(e.target.value)}
-            onKeyDown={handleKeyDown}
-            placeholder="Ask about your codebase..."
-            className="min-h-[80px] resize-none"
-            disabled={isLoading}
-          />
-          <Button
-            onClick={handleSend}
-            disabled={!inputValue.trim() || isLoading}
-            className="self-end"
-          >
-            {isLoading ? (
-              <Loader2 className="h-4 w-4 animate-spin" />
-            ) : (
-              <Send className="h-4 w-4" />
+        <div className="relative flex gap-2">
+          <div className="relative flex-1">
+            <Textarea
+              ref={textareaRef}
+              value={inputValue}
+              onChange={(e) => setInputValue(e.target.value)}
+              onKeyDown={handleKeyDown}
+              onPaste={handlePaste}
+              onDragOver={handleDragOver}
+              onDragLeave={handleDragLeave}
+              onDrop={handleDrop}
+              placeholder="Ask about your codebase..."
+              className={cn(
+                'min-h-[80px] resize-none',
+                isDragOver && 'border-primary ring-2 ring-primary/20'
+              )}
+              disabled={isLoading}
+            />
+            {/* Drag-over overlay */}
+            {isDragOver && (
+              <div className="absolute inset-0 flex items-center justify-center rounded-md bg-primary/5 border-2 border-dashed border-primary pointer-events-none">
+                <span className="text-sm font-medium text-primary">
+                  {t('insights.images.dragOver')}
+                </span>
+              </div>
             )}
-          </Button>
+          </div>
+          <div className="flex flex-col gap-1 self-end">
+            <Button
+              variant="outline"
+              size="icon"
+              className="h-9 w-9"
+              onClick={() => setScreenshotOpen(true)}
+              disabled={isLoading || !canAddMore}
+              title={t('insights.images.screenshotButton')}
+            >
+              <Camera className="h-4 w-4" />
+            </Button>
+            <Button
+              onClick={handleSend}
+              disabled={(!inputValue.trim() && pendingImages.length === 0) || isLoading}
+              className="h-9 w-9"
+              size="icon"
+            >
+              {isLoading ? (
+                <Loader2 className="h-4 w-4 animate-spin" />
+              ) : (
+                <Send className="h-4 w-4" />
+              )}
+            </Button>
+          </div>
         </div>
+
+        {/* Image analysis warning */}
+        {pendingImages.length > 0 && (
+          <div className="mt-1 flex items-center gap-1.5 rounded-md bg-amber-500/10 px-2 py-1 text-xs text-amber-500">
+            <AlertCircle className="h-3 w-3 shrink-0" />
+            <span>{t('insights.images.analysisUnsupported')}</span>
+          </div>
+        )}
+
+        {/* Image error */}
+        {imageError && (
+          <p className="mt-1 text-xs text-destructive">{imageError}</p>
+        )}
+
+        {/* Image preview strip */}
+        {pendingImages.length > 0 && (
+          <div className="mt-2 flex flex-wrap items-center gap-2">
+            {pendingImages.map((image) => (
+              <div
+                key={image.id}
+                className="group relative h-16 w-16 rounded-md border border-border overflow-hidden"
+              >
+                <img
+                  src={image.thumbnail || `data:${image.mimeType};base64,${image.data}`}
+                  alt={image.filename}
+                  className="h-full w-full object-cover"
+                />
+                <button
+                  type="button"
+                  onClick={() => removeImage(image.id)}
+                  className="absolute -right-1 -top-1 flex h-5 w-5 items-center justify-center rounded-full bg-destructive text-destructive-foreground opacity-0 transition-opacity group-hover:opacity-100"
+                  title={t('insights.images.removeImage')}
+                >
+                  <X className="h-3 w-3" />
+                </button>
+              </div>
+            ))}
+            <span className="text-xs text-muted-foreground">
+              {t('insights.images.imageCount', { count: pendingImages.length })}
+            </span>
+          </div>
+        )}
+
         <p className="mt-2 text-xs text-muted-foreground">
-          Press Enter to send, Shift+Enter for new line
+          {t('insights.images.pasteHint')} · Press Enter to send, Shift+Enter for new line
         </p>
       </div>
+
+      {/* Screenshot capture dialog */}
+      <ScreenshotCapture
+        open={screenshotOpen}
+        onOpenChange={setScreenshotOpen}
+        onCapture={handleScreenshotCapture}
+      />
       </div>
     </div>
   );
@@ -469,11 +700,32 @@ function MessageBubble({
         <div className="text-sm font-medium text-foreground">
           {isUser ? 'You' : 'Assistant'}
         </div>
-        <div className="prose prose-sm dark:prose-invert max-w-none">
-          <ReactMarkdown remarkPlugins={[remarkGfm]} components={markdownComponents}>
-            {message.content}
-          </ReactMarkdown>
-        </div>
+        {message.content && (
+          <div className="prose prose-sm dark:prose-invert max-w-none">
+            <ReactMarkdown remarkPlugins={[remarkGfm]} components={markdownComponents}>
+              {message.content}
+            </ReactMarkdown>
+          </div>
+        )}
+
+        {/* Image attachments for user messages */}
+        {isUser && message.images && message.images.length > 0 && (
+          <div className="space-y-1.5">
+            <div className="flex flex-wrap gap-2">
+              {message.images
+                .filter(img => img.thumbnail || img.data)
+                .map((image) => (
+                  <img
+                    key={image.id}
+                    src={image.thumbnail || `data:${image.mimeType};base64,${image.data}`}
+                    alt={image.filename}
+                    className="max-w-[200px] max-h-[200px] rounded-md border border-border object-contain"
+                  />
+                ))}
+            </div>
+            <p className="text-xs text-muted-foreground italic">{t('insights.images.notAnalyzed')}</p>
+          </div>
+        )}
 
         {/* Tool usage history for assistant messages */}
         {!isUser && message.toolsUsed && message.toolsUsed.length > 0 && (
@@ -613,6 +865,7 @@ function ToolUsageHistory({ tools }: ToolUsageHistoryProps) {
   return (
     <div className="mt-2">
       <button
+        type="button"
         onClick={() => setExpanded(!expanded)}
         className="flex items-center gap-2 text-xs text-muted-foreground hover:text-foreground transition-colors"
       >

apps/frontend/src/renderer/components/Roadmap.tsx

@@ -1,4 +1,6 @@
 import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Archive } from 'lucide-react';
 import { RoadmapGenerationProgress } from './RoadmapGenerationProgress';
 import { CompetitorAnalysisDialog } from './CompetitorAnalysisDialog';
 import { ExistingCompetitorAnalysisDialog } from './ExistingCompetitorAnalysisDialog';
@@ -8,17 +10,30 @@ import { RoadmapHeader } from './roadmap/RoadmapHeader';
 import { RoadmapEmptyState } from './roadmap/RoadmapEmptyState';
 import { RoadmapTabs } from './roadmap/RoadmapTabs';
 import { FeatureDetailPanel } from './roadmap/FeatureDetailPanel';
+import {
+  AlertDialog,
+  AlertDialogContent,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogCancel,
+  AlertDialogAction,
+} from './ui/alert-dialog';
 import { useRoadmapData, useFeatureActions, useRoadmapGeneration, useRoadmapSave, useFeatureDelete } from './roadmap/hooks';
 import { getCompetitorInsightsForFeature } from './roadmap/utils';
 import type { RoadmapFeature } from '../../shared/types';
 import type { RoadmapProps } from './roadmap/types';
 
 export function Roadmap({ projectId, onGoToTask }: RoadmapProps) {
+  const { t } = useTranslation('common');
+
   // State management
   const [selectedFeature, setSelectedFeature] = useState<RoadmapFeature | null>(null);
   const [activeTab, setActiveTab] = useState('kanban');
   const [showAddFeatureDialog, setShowAddFeatureDialog] = useState(false);
   const [showCompetitorViewer, setShowCompetitorViewer] = useState(false);
+  const [pendingArchiveFeatureId, setPendingArchiveFeatureId] = useState<string | null>(null);
 
   // Custom hooks
   const { roadmap, competitorAnalysis, generationStatus } = useRoadmapData(projectId);
@@ -54,6 +69,22 @@ export function Roadmap({ projectId, onGoToTask }: RoadmapProps) {
     }
   };
 
+  const handleArchiveFeature = (featureId: string) => {
+    setPendingArchiveFeatureId(featureId);
+  };
+
+  const confirmArchiveFeature = async () => {
+    if (!pendingArchiveFeatureId) return;
+    try {
+      await deleteFeature(pendingArchiveFeatureId);
+      if (selectedFeature?.id === pendingArchiveFeatureId) {
+        setSelectedFeature(null);
+      }
+    } finally {
+      setPendingArchiveFeatureId(null);
+    }
+  };
+
   // Show generation progress
   if (generationStatus.phase !== 'idle' && generationStatus.phase !== 'complete') {
     return (
@@ -78,6 +109,7 @@ export function Roadmap({ projectId, onGoToTask }: RoadmapProps) {
           onOpenChange={setShowCompetitorDialog}
           onAccept={handleCompetitorDialogAccept}
           onDecline={handleCompetitorDialogDecline}
+          projectId={projectId}
         />
         {/* Dialog for projects WITH existing competitor analysis */}
         <ExistingCompetitorAnalysisDialog
@@ -87,6 +119,7 @@ export function Roadmap({ projectId, onGoToTask }: RoadmapProps) {
           onRunNew={handleRunNewAnalysis}
           onSkip={handleSkipAnalysis}
           analysisDate={competitorAnalysisDate}
+          projectId={projectId}
         />
       </>
     );
@@ -114,6 +147,7 @@ export function Roadmap({ projectId, onGoToTask }: RoadmapProps) {
           onConvertToSpec={handleConvertToSpec}
           onGoToTask={handleGoToTask}
           onSave={saveRoadmap}
+          onArchive={handleArchiveFeature}
         />
       </div>
 
@@ -125,6 +159,7 @@ export function Roadmap({ projectId, onGoToTask }: RoadmapProps) {
           onConvertToSpec={handleConvertToSpec}
           onGoToTask={handleGoToTask}
           onDelete={deleteFeature}
+          onArchive={handleArchiveFeature}
           competitorInsights={getCompetitorInsightsForFeature(selectedFeature, competitorAnalysis)}
         />
       )}
@@ -135,6 +170,7 @@ export function Roadmap({ projectId, onGoToTask }: RoadmapProps) {
         onOpenChange={setShowCompetitorDialog}
         onAccept={handleCompetitorDialogAccept}
         onDecline={handleCompetitorDialogDecline}
+        projectId={projectId}
       />
 
       {/* Competitor Analysis Options Dialog (existing analysis) */}
@@ -145,6 +181,7 @@ export function Roadmap({ projectId, onGoToTask }: RoadmapProps) {
         onRunNew={handleRunNewAnalysis}
         onSkip={handleSkipAnalysis}
         analysisDate={competitorAnalysisDate}
+        projectId={projectId}
       />
 
       {/* Competitor Analysis Viewer */}
@@ -152,6 +189,7 @@ export function Roadmap({ projectId, onGoToTask }: RoadmapProps) {
         analysis={competitorAnalysis}
         open={showCompetitorViewer}
         onOpenChange={setShowCompetitorViewer}
+        projectId={projectId}
       />
 
       {/* Add Feature Dialog */}
@@ -160,6 +198,34 @@ export function Roadmap({ projectId, onGoToTask }: RoadmapProps) {
         open={showAddFeatureDialog}
         onOpenChange={setShowAddFeatureDialog}
       />
+
+      {/* Archive Confirmation Dialog */}
+      <AlertDialog
+        open={!!pendingArchiveFeatureId}
+        onOpenChange={(open) => { if (!open) setPendingArchiveFeatureId(null); }}
+      >
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <div className="flex items-center gap-2">
+              <Archive className="h-5 w-5 text-muted-foreground" />
+              <AlertDialogTitle>{t('roadmap.archiveFeatureConfirmTitle')}</AlertDialogTitle>
+            </div>
+            <AlertDialogDescription>
+              {t('roadmap.archiveFeatureConfirmDescription', {
+                title: pendingArchiveFeatureId
+                  ? roadmap.features.find((f) => f.id === pendingArchiveFeatureId)?.title ?? ''
+                  : '',
+              })}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>{t('buttons.cancel')}</AlertDialogCancel>
+            <AlertDialogAction onClick={confirmArchiveFeature}>
+              {t('roadmap.archiveFeature')}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
     </div>
   );
 }

apps/frontend/src/renderer/components/RoadmapKanbanView.tsx

@@ -36,6 +36,7 @@ interface RoadmapKanbanViewProps {
   onConvertToSpec?: (feature: RoadmapFeature) => void;
   onGoToTask?: (specId: string) => void;
   onSave?: () => void;
+  onArchive?: (featureId: string) => void;
 }
 
 interface DroppableStatusColumnProps {
@@ -45,6 +46,7 @@ interface DroppableStatusColumnProps {
   onFeatureClick: (feature: RoadmapFeature) => void;
   onConvertToSpec?: (feature: RoadmapFeature) => void;
   onGoToTask?: (specId: string) => void;
+  onArchive?: (featureId: string) => void;
   isOver: boolean;
 }
 
@@ -71,6 +73,7 @@ function DroppableStatusColumn({
   onFeatureClick,
   onConvertToSpec,
   onGoToTask,
+  onArchive,
   isOver
 }: DroppableStatusColumnProps) {
   const { setNodeRef } = useDroppable({
@@ -158,6 +161,7 @@ function DroppableStatusColumn({
                     onClick={() => onFeatureClick(feature)}
                     onConvertToSpec={onConvertToSpec}
                     onGoToTask={onGoToTask}
+                    onArchive={onArchive}
                   />
                 ))
               )}
@@ -174,7 +178,8 @@ export function RoadmapKanbanView({
   onFeatureClick,
   onConvertToSpec,
   onGoToTask,
-  onSave
+  onSave,
+  onArchive
 }: RoadmapKanbanViewProps) {
   const [activeFeature, setActiveFeature] = useState<RoadmapFeature | null>(null);
   const [overColumnId, setOverColumnId] = useState<string | null>(null);
@@ -300,6 +305,7 @@ export function RoadmapKanbanView({
               onFeatureClick={onFeatureClick}
               onConvertToSpec={onConvertToSpec}
               onGoToTask={onGoToTask}
+              onArchive={onArchive}
               isOver={overColumnId === column.id}
             />
           ))}

apps/frontend/src/renderer/components/SortableFeatureCard.tsx

@@ -9,7 +9,8 @@ import {
   TooltipContent,
   TooltipTrigger
 } from './ui/tooltip';
-import { Play, ExternalLink, TrendingUp, Layers, ThumbsUp } from 'lucide-react';
+import { Play, ExternalLink, TrendingUp, Layers, ThumbsUp, Archive } from 'lucide-react';
+import { useTranslation } from 'react-i18next';
 import { TaskOutcomeBadge, getTaskOutcomeColorClass } from './roadmap/TaskOutcomeBadge';
 import {
   ROADMAP_PRIORITY_COLORS,
@@ -25,6 +26,7 @@ interface SortableFeatureCardProps {
   onClick: () => void;
   onConvertToSpec?: (feature: RoadmapFeature) => void;
   onGoToTask?: (specId: string) => void;
+  onArchive?: (featureId: string) => void;
 }
 
 export function SortableFeatureCard({
@@ -32,8 +34,10 @@ export function SortableFeatureCard({
   roadmap,
   onClick,
   onConvertToSpec,
-  onGoToTask
+  onGoToTask,
+  onArchive
 }: SortableFeatureCardProps) {
+  const { t } = useTranslation('common');
   const {
     attributes,
     listeners,
@@ -120,7 +124,7 @@ export function SortableFeatureCard({
             </div>
             <h3 className="font-medium text-sm leading-snug line-clamp-2">{feature.title}</h3>
           </div>
-          <div className="shrink-0">
+          <div className="shrink-0 flex items-center gap-1">
             {feature.taskOutcome ? (
               <Badge
                 variant="outline"
@@ -139,7 +143,7 @@ export function SortableFeatureCard({
                 }}
               >
                 <ExternalLink className="h-3 w-3 mr-1" />
-                Task
+                {t('roadmap.task')}
               </Button>
             ) : (
               feature.status !== 'done' &&
@@ -154,10 +158,25 @@ export function SortableFeatureCard({
                   }}
                 >
                   <Play className="h-3 w-3 mr-1" />
-                  Build
+                  {t('roadmap.build')}
                 </Button>
               )
             )}
+            {feature.status === 'done' && onArchive && (
+              <Button
+                variant="ghost"
+                size="sm"
+                className="h-7 px-2"
+                title={t('roadmap.archiveFeature')}
+                aria-label={t('accessibility.archiveFeatureAriaLabel')}
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onArchive(feature.id);
+                }}
+              >
+                <Archive className="h-3 w-3" />
+              </Button>
+            )}
           </div>
         </div>
 

apps/frontend/src/renderer/components/SortableTaskCard.tsx

@@ -41,7 +41,10 @@ export const SortableTaskCard = memo(function SortableTaskCard({ task, onClick,
     transition,
     isDragging,
     isOver
-  } = useSortable({ id: task.id });
+  } = useSortable({
+    id: task.id,
+    disabled: task.status === 'in_progress' // Prevent dragging tasks that are currently running or stuck
+  });
 
   const style = {
     transform: CSS.Transform.toString(transform),