> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fermata.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications

> One sentence for what happened, one more for what to do, and lanes that know when to stay quiet.

Fermata's notifications are written for someone who has not looked at the app in an hour. Each banner says in one plain sentence what happened; when the run has genuinely stopped for you, a second sentence says what to do about it. Nothing in a banner uses internal vocabulary, and nothing arrives that the run could have handled itself.

This page lists every sentence a banner can say, when each [lane](/control/lanes) says it, and which of them reach a paired phone. The banner is also how a parked [gate](/control/gates) reaches you when no Fermata window is in front of you.

## The shape of a banner

The title is the piece name, a separator, and a short phase tail: "Spec", "Strategy", "Agents", "Review", "Complete", or "Done". While agents run, the tail carries progress ("Agents 3/7"); mid-review it reads "Review 2/5". A long piece name is what gets cut, never the tail, because the tail is what tells two banners from the same run apart.

The body is the sentence for what happened, followed by a call to action when the run is parked on a decision. Clicking the banner opens the piece it names.

## What each moment says

Every sentence a phase banner can carry, grouped by where the run is. Counts agree with the run ("1 agent", "4 agents"); the examples below use a four-agent run.

| Phase | Moment | The sentence |
| - | - | - |
| Spec | The spec lands | "The spec is ready to read." |
| Spec | The spec run stalls and restarts | "The spec stalled, so Fermata is trying again." |
| Strategy | Writing begins | "Fermata is writing the strategy." |
| Strategy | The strategy lands | "The strategy is ready." |
| Strategy | The run stops early | "The strategy run stopped before it finished." |
| Strategy | A second pass starts | "Fermata is writing the strategy again." |
| Agents | Planning begins | "Fermata is working out which agents to run." |
| Agents | The plan lands | "The plan is ready: 4 agents to run." |
| Agents | The build starts | "4 agents started work." |
| Agents | The run cannot start | "The run cannot start until the plan is fixed." |
| Agents | You pause the run | "The agents are paused." |
| Agents | A paused run picks back up | "The agents are working again." |
| Agents | The run halts | "The run stopped and can be picked up again." |
| Agents | Unfinished agents are re-armed | "2 agents went back to work." |
| Agents | Every agent finishes cleanly | "4 agents finished the work." |
| Agents | Agents finish with casualties | "4 agents finished: 2 done, 1 failed, 1 skipped." |
| Agents | The cost ceiling stops the run | "The run hit its cost limit and stopped." |
| Agents | The work review sends agents back | "2 agents went back to fix the work." |
| Finish | The branch lands on its base | "The work is merged into 'main'." |
| Finish | The piece finishes without a merge | "The piece is complete without a merge." |
| Finish | You close the piece | "The piece is done." |
| Loop | You release the piece | "Fermata is running this piece on its own now." |
| Loop | The Loop halts this run | "The Loop stopped this run." |
| Loop | The Loop re-queues this run | "The Loop put this run back in the queue." |
| Housekeeping | The worktree went missing and was rebuilt | "The work folder went missing, so Fermata rebuilt it." |

A clean finish is one breath; a finish with casualties itemizes them, and a count of zero is dropped rather than written. The merged sentence quotes the branch and shortens a long one with an ellipsis, so the name never crowds out the rest of the banner.

## The call to action

When the banner announces a stop you have to clear, the sentence for the pending decision is appended after the sentence for what happened: "The strategy is ready. Approve the strategy or ask for changes."

| The decision waiting | The sentence appended |
| - | - |
| "Approve strategy" | "Approve the strategy or ask for changes." |
| "Approve agents" | "Check the agents, then start the run." |
| "Clear review" | "Finish the review to open a PR." |
| "Create PR" | "Open the pull request." |
| "Resume agents" | "Resume the run when you are ready." |
| "Retry failed" | "Retry 2 agents or move on to review." |
| "Continue to review" | "Move on to review." |
| "Mark done" | "Confirm the piece is done." |

The appended sentence comes only when the run is genuinely parked. The answer to "is this run waiting on me" is read from the same place the [Loop board](/loop/board)'s chips read it, so a banner never claims the run needs you while the card says "Advancing". A run that stopped with failed agents recommends the retry and names the count; a clean stop says nothing about retrying, because there is nothing to retry.

## What each lane says out loud

On the Manual lane, every row in the table above arrives. Manual means you drive each phase, so the banners narrate each phase.

A hands-off run, a released Auto piece or a playing Loop, stays quiet while the machine is working: a working machine is exactly what you asked for when you released the lane, and narrating it is noise. It speaks in exactly two situations:

* **At a gate the runner will not clear itself.** The banner carries the call to action, whatever the moment.
* **At five bookends.** The lane opening ("Fermata is running this piece on its own now."), the run halting ("The run stopped and can be picked up again."), the run hitting its [cost ceiling](/loop/limits) ("The run hit its cost limit and stopped."), the agents finishing ("4 agents finished the work."), and the piece closing ("The piece is done.").

The merge and the no-merge finish are steps on the way to done, not the end of the story, so a hands-off run does not announce them separately.

## When conflict resolution finishes

**Solve Conflicts** on a pull request is a walk-away action: you press the button, an agent works through the tree, and Fermata pushes the branch when it is clean. The ending is what you need to hear, and there are three of them, each with its own title tail in place of the phase.

| Title tail | The sentence |
| - | - |
| "Conflicts resolved" | "The conflicts are resolved and the branch is pushed." |
| "Push failed" | "The conflicts are resolved, but the push failed. Open the piece to see why." |
| "Conflicts remain" | "The run stopped with conflicts still to fix. Resume it when you are ready." |

These never name the branch; a branch name is unbounded and would spend the space the second sentence needs. The concrete reason a push failed waits in the piece's Activity feed, where there is room for it and where it stays on your Mac. "Conflicts remain" is said once per run, however many turns the run takes, and none of the three reach a phone. The flow itself is covered in [review and pull request](/piece/review-and-pull-request).

## Quiet successes, surfaced failures

Successes are quiet and failures are loud, and the two are on separate switches so muting one never mutes the other. Sessions that finish cleanly ride the **Session Completed** toggle; everything that breaks rides **Failures**.

A failure banner's title names what broke: "Spec failed", "Strategy failed", "Decomposition failed", "PR creation failed", "PR merge failed", or "Merge failed". Its body opens with a plain sentence and appends the concrete reason, the git output or `gh` error that actually came back. That reason never leaves your Mac. A failed agent inside a running piece has its own recovery story, with retries, skips, and a failure policy: see [when an agent fails](/piece/when-an-agent-fails).

## Turning them off

Settings → Notifications carries one toggle per notification type, each with a subtitle saying what it covers:

| Toggle | Covers |
| - | - |
| **Required Input** | "Approvals and agent questions" |
| **Session Completed** | "Sessions that finish successfully" |
| **Failures** | "Failed sessions, pull requests, and planning steps" |
| **SDD Phases** | "Piece phase transitions" |

The phase banners and the conflict-resolution endings on this page ride **SDD Phases**. An external MCP client parked on a confirmation shares **Required Input**, because it is input the app requires from you. **Play sound with notifications** sits below the four and controls the sound for all of them.

## The same words on your phone

A paired phone hears about the same moments in the same words. The strategy landing pushes "The strategy is ready. Approve the strategy or ask for changes."; the plan landing pushes "The plan is ready. Check the agents, then start the run."; completion pushes the title tail "Complete" with "Confirm the piece is done." Failures push with the same title tails as the Mac, and a run that halts with failed agents pushes once, titled "Agents halted".

Two things the phone deliberately says differently, because it knows less than the Mac that wrote the sync record: the plan-ready push drops the agent count, and the completion push carries only the call to action. And one thing it never says: per-agent progress. Every agent is its own session, and a twenty-agent run would be twenty near-identical pushes; progress rides the phase boundaries instead. The concrete reason behind a failure never crosses the wire; the phone gets the kind, the Mac keeps the details.

The phone has its own per-type switches, covered in [the mobile companion](/mobile/companion).