Fleet says gh or claude is missing, but my terminal finds them
PATH. A GUI-launched app on macOS inherits a minimal PATH that contains neither, so Fleet resolves your login shell's PATH once at startup.
If a packaged build disagrees with your terminal, check that the tool is on the PATH your login shell exports, not one exported by an interactive-only branch of your shell config. The same mechanism hides your editors from the Open in editor menu, so if that list is short too, this is almost certainly the cause.
The New project pane says every toolchain is missing
Same cause. Every probe answering "missing" is a legal state, so it sends every template to agent mode and looks like a product decision rather than a bug.
A session shows as detached
Its worktree is gone from disk. Usually that means it was deleted in Finder.
Fleet does not silently recreate it, because a recreated checkout would be an empty directory wearing the name of work you thought you still had. Restore the session to rebuild the worktree at the same branch.
A session whose worktree was reclaimed on purpose, by a merged pull request or by archiving, is not marked detached. It ended deliberately, and detached is a failure state.
A merge refuses
Merges run from your main worktree, and Fleet refuses rather than stashing anything on your behalf. Commit or stash what you have in progress yourself, then merge again.
If two sessions in the same repository try to merge at once, they queue: one repository merges one thing at a time.
A worktree will not go away
Removal is never forced. Uncommitted work in a worktree is no evidence that the work landed, so Fleet leaves it and tells you. Delete it yourself once you have checked, and Fleet's next prune will catch up.
The port is still in use after I stopped a script
It should not be. Run children are spawned into their own process group and the whole group is
signalled, precisely because signalling npm alone leaves the vite it forked holding the port.
If it happens anyway, the process is one Fleet did not start: something you launched from the
terminal, or a leftover from before the app was running. Each session's ports are deterministic, so
lsof -i :3140 and its nine neighbours will name it.
The setup script failed and the session started anyway
That is intended. A worktree whose install failed is still a worktree an agent can read code in, and failing the session there would discard the prompt already waiting to be delivered. You get a banner and the retained log. Fix it and rerun setup.
A missing included file, such as an absent .env.local, is softer still: it ends its own step with
an error and provisioning carries on.
The orchestrator refuses to spawn or merge
The round is sealed, because its pull request has been opened. That is the design: anything spawned or merged now would land on a branch you have already been asked to review.
Ask for something new and the orchestrator should start a new round. Ask it to amend the delivery and it should continue the current one. See rounds and pull requests.
An agent is idle and nothing is happening
It requested review and stopped, and it will not resume until its orchestrator answers. An unanswered agent is a stalled agent. Tell the orchestrator to review its pending agents.
An agent will not take my instructions
Agents have no composer, on purpose. Prompting one directly would put two bosses on one branch. Type to the orchestrator. You can still stop an agent, and you still answer its permission requests and questions yourself.
A tool card is spinning forever
It should not be able to. If a query dies mid-tool, Fleet marks in-flight tools as interrupted on reload, because a spinner that never stops is worse than an error.
If you see one, reloading the window will settle it.
The network dropped mid-stream
You should get an error card, not a hang. The session stays, the transcript stays, and you can send the next prompt when you are back.
Quitting
Closing the window does not quit and does not stop your sessions. Quitting drains properly: pending permissions are denied, sessions are interrupted and closed with a short deadline each, and transcripts are flushed. A multi-file edit killed halfway is the worst failure this app has, and the drain exists to avoid it.