Bash tool can't find user-installed CLI tools (Flutter, Puro, FVM, asdf, etc.) — non-login shell + missing PATH augmentation

[codewithmustafa]

Checklist

• I searched existing issues and this hasn't been reported

Area

Fullstack

Operating System

macOS

Version

2.8.0-beta.6

What happened?

Summary

Tasks launched from the Kanban board fail to invoke flutter, dart, puro, fvm and other user-installed
CLI tools, even when those binaries are correctly configured in the user's shell rc files (~/.zshrc,
~/.bash_profile). A simple "create a Flutter sample app and run it on the iOS simulator" task never reaches
the implementation phase because the agent's Bash tool returns command not found.

The root cause is in two places, both in apps/desktop/src/main/.

Reproduction

1. Install Flutter via Puro (the recommended manager on https://puro.dev), so the binary lives at
   ~/.puro/envs/default/flutter/bin/flutter and puro itself at ~/.puro/bin/puro. Make sure flutter --version works in your terminal (PATH set up via ~/.zshrc).
2. Launch Aperant from Finder/Dock (production app) on macOS.
3. Open any project on the Kanban board and create a task: "Create a Flutter sample project and run it on the
   iOS simulator."
4. Observe the Planning phase: the agent never gets to a usable plan; subtasks fail or the spec pipeline burns
   iterations investigating the existing TS codebase. Even when it does try flutter create, it would fail with
   flutter: command not found.

Expected: the agent finds and runs flutter/puro exactly the way the user does in a normal terminal.
Actual: the agent's Bash tool runs in an environment where these binaries are not on PATH.

Root Cause

Two cooperating issues:

1. Bash tool runs a non-login shell

apps/desktop/src/main/ai/tools/builtin/bash.ts invokes /bin/bash -c <command>:

• It hardcodes /bin/bash instead of honoring the user's login shell ($SHELL, typically /bin/zsh on modern
  macOS).
• It uses -c only, so no rc file is sourced. Any PATH entries the user adds in ~/.zshrc, ~/.bash_profile,
  ~/.profile (Puro/FVM init lines, asdf shims, mise activate, conda init, etc.) are invisible to the agent.

2. PATH augmentation list omits Flutter/Dart toolchains

apps/desktop/src/main/env-utils.ts maintains COMMON_BIN_PATHS for darwin and linux to compensate for
Electron's reduced PATH on GUI launch. The list includes Homebrew, .NET, and ~/.local/bin, but none of the
standard Flutter/Dart locations:

• ~/.puro/bin, ~/.puro/envs/default/flutter/bin (Puro)
• ~/development/flutter/bin, ~/flutter/bin (manual install — official guide)
• ~/fvm/default/bin (FVM)
• ~/.pub-cache/bin (Dart pub global)
• ~/snap/flutter/common/flutter/bin (Linux/snap)

So even when the augmented env does kick in, no Flutter binary is discoverable.

Verification of the diagnosis

Reproduced on:

• macOS 24.6.0 (Darwin), Apple Silicon
• Aperant 2.8.0-beta.6 from develop
• Flutter 3.x via Puro (default env), which flutter resolves in interactive zsh; not resolvable from bash -c 'which flutter' launched as a child of GUI-spawned Electron.

The exact same task succeeds end-to-end after applying the fix below in dev mode.

Proposed Fix (dual-layer)

Both layers should be applied so the Bash tool works regardless of how the user has installed their tools.

A. apps/desktop/src/main/ai/tools/builtin/bash.ts

• On Unix, prefer the user's login shell (process.env.SHELL) when it ends in /zsh or /bash, else fall
  back to /bin/bash.
• Pass -l -c <command> on Unix so the user's rc files are sourced. (Windows behaviour unchanged.)

B. apps/desktop/src/main/env-utils.ts

Extend COMMON_BIN_PATHS.darwin and COMMON_BIN_PATHS.linux with the standard Flutter/Dart install locations:
~/.puro/bin
~/.puro/envs/default/flutter/bin
~/development/flutter/bin
~/flutter/bin
~/fvm/default/bin
~/.pub-cache/bin
~/snap/flutter/common/flutter/bin # linux only

Layer A handles arbitrary user setups (mise, asdf, conda, custom locations). Layer B is the safety net when no
shell rc loads or when the chosen shell isn't recognized. Together they make user-installed CLI tools — not
just Flutter — reliably discoverable from autonomous tasks.

Out of Scope (Follow-up)

These are real but separate issues worth tracking:

1. Spec pipeline doesn't model "scaffold a brand-new project" tasks. prompts/planner.md Phase 0
   mandates "DEEP CODEBASE INVESTIGATION" and reading at least 3 pattern files. For a "create new Flutter app"
   task in an existing TS repo, the planner spends the budget mining irrelevant TS patterns. A new workflow_type: "scaffold" that skips Phase 0 would help.
2. No mobile / iOS simulator guidance in any prompt — coder.md/planner.md examples are all
   Python/Node/React. Adding a Flutter + iOS Simulator playbook (where to scaffold inside the worktree, xcrun simctl boot, flutter run -d <id>) would round out the experience.
3. Worktree mode + scaffolding conflict. git worktree add clones the existing project; flutter create .
   then refuses to run in a non-empty directory. The agent needs explicit guidance to scaffold into a
   subdirectory in scaffold-type tasks.

Environment

• OS: macOS 14 (Darwin 24.6.0), Apple Silicon
• Aperant: 2.8.0-beta.6 (develop @ commit cba7a027)
• Shell: zsh (default macOS); Flutter via Puro
• Auth: Claude Code subscription (OAuth)

Steps to reproduce

Open any project on the Kanban board and create a task: "Create a Flutter sample project and run it on the
iOS simulator."

Expected behavior

...

Logs / Screenshots

=== QUICK SPEC COMPLETE ===

Task: Create Flutter "start" sample project and run on iOS Simulator
Files: ~20+ files to CREATE (full Flutter scaffold via `flutter create start`)
Complexity: SIMPLE
Subtasks: 2
  1. Environment setup — verify/install Flutter SDK, run `flutter doctor`
  2. Create & launch — `flutter create start`, boot simulator, `flutter run`

⚠️  Discovery: Flutter SDK is NOT currently on PATH. The implementation 
   agent will need to install it (e.g. `brew install --cask flutter`) or 
   locate an existing installation first.

⚠️  Discovery: `xcrun` and `flutter` are not in the project's allowed 
   command list — permissions will need to be granted during execution.

Ready for implementation.

[github-actions]

👋 Thanks for opening your first issue!

A maintainer will triage this soon. In the meantime:

• Make sure you've provided all the requested info
• Join our Discord for faster help