# Status and health (/docs/concepts/status-and-health)



Bowline reports one honest signal: whether your workspace is working, needs you, or is partly constrained. That signal is a Status Level (`healthy`, `attention`, or `limited`), computed from the same event-backed state across every surface. This page explains the three levels, how Workspace Status differs from Project Status, what counts as Active Work At Risk, and the narrow set of states that ever turn into a native notification.

## The three status levels [#the-three-status-levels]

Every Workspace Status and Project Status carries exactly one Status Level. The level is the top-level state; it never claims more than Bowline can prove from real sync state.

| Status Level | What it means                                                                                                                                                     | What to do                                                                              |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `healthy`    | Everything in scope is syncing and available. Nothing needs you.                                                                                                  | Keep working.                                                                           |
| `attention`  | Something needs you, but nothing is blocked. For example, a Sync Conflict to resolve, a Review-Ready Agent Lease to review, or a pending Device Approval Request. | Run `bowline actions` for safe next steps.                                              |
| `limited`    | A specific Capability Limitation can't proceed while other work continues.                                                                                        | Run `bowline status` to see what's limited, what still works, and the next safe action. |

Bowline deliberately avoids "blocked," "failed," and "broken" at the top level. Work rarely stops in totality, so the top-level word is `limited` and blocking language is reserved for the specific Capability Limitation underneath it.

### What `limited` means [#what-limited-means]

A `limited` Status Level names a Capability Limitation: a specific path, action, or capability that cannot proceed while other work can continue. It is never a claim that the whole workspace is down.

A `limited` status must always say two things: what's constrained, and what still works. If sync is degraded for one project, status explains what's unavailable there, confirms that the rest of your tree keeps syncing and hydrating, and gives the next safe action. You stay productive everywhere the limitation doesn't reach.

<Callout type="info">
  `limited` is scoped, not catastrophic. A single project waiting on hydration, or one path under a Capability Limitation, leaves the rest of `~/Code` `healthy` and fully usable.
</Callout>

## Workspace Status and Project Status [#workspace-status-and-project-status]

Bowline computes health at two scopes from the same event stream. Workspace Status covers a workspace root such as `~/Code`. Project Status covers the project implied by your current directory or an explicit path. Each has its own Status Level.

The default scope depends on the surface, because each surface answers a different question.

| Surface                                      | Default scope    | Why                                                                    |
| -------------------------------------------- | ---------------- | ---------------------------------------------------------------------- |
| `bowline status`, `bowline actions`, the TUI | Project Status   | You're working inside one project and want its state and next actions. |
| macOS menu bar                               | Workspace Status | The ambient icon answers "is my whole workspace fine?" at a glance.    |

Project Status doesn't hide the rest of your tree. When you're inside a project, the CLI and TUI include a compact Workspace Status summary whenever other projects need attention, so a conflict or limitation elsewhere stays visible without leaving your current project. Pass `--workspace` to `bowline status`, `bowline actions`, or `bowline events` to switch the primary view to the workspace scope.

## Active work and degraded state [#active-work-and-degraded-state]

A degraded sync state is not automatically urgent. What makes it urgent is Active Work At Risk: user-started or user-followed work that can't complete safely without Bowline recovering by syncing local edits out of the machine, hydrating or materializing content you need now, completing a `bowline` operation you invoked, or continuing an agent lease.

A Blocking Degraded State is a Capability Limitation that leaves Active Work At Risk unable to sync, hydrate, materialize, or safely continue for 60 continuous seconds. That 60-second floor exists so a brief network blip or a normal hydration pause never escalates into noise. A Blocking Degraded State is the only degraded status that can create a native notification.

Degraded state with no Active Work At Risk stays passive. If nothing you started is waiting on recovery, Bowline records the state in status and the event log but doesn't interrupt you. You'll still see it in `bowline status` and the TUI whenever you look.

## Where status surfaces [#where-status-surfaces]

Status is event-backed and consistent everywhere. The CLI and TUI are the primary, complete surfaces on every platform, including headless hosts. Ambient surfaces mirror the same data where the OS supports them; they never own correctness or repair.

| Surface                                               | Platform      | Role                                                                  |
| ----------------------------------------------------- | ------------- | --------------------------------------------------------------------- |
| `bowline status [--watch] [--workspace] [--json]`     | All           | Durable status, Capability Limitations, and safe next actions.        |
| `bowline actions [--workspace] [--json]`              | All           | Safe next actions for the current status.                             |
| `bowline events [--limit <n>] [--workspace] [--json]` | All           | Recent workspace events behind the current state.                     |
| `bowline tui`                                         | All           | Keyboard-first decision surface for status, conflicts, and approvals. |
| Menu Bar Status App                                   | macOS         | Ambient read-only mirror of Workspace Status.                         |
| Desktop notifications                                 | Linux desktop | Native mirror of action-relevant states when available.               |

For scripts and agents, every command takes `--json`, and `bowline status --watch` streams updates so you can react to changes without polling.

## When Bowline notifies you [#when-bowline-notifies-you]

Most state stays passive. Normal sync, hydration, indexing, healthy agent progress, and Sync Conflicts never fire a native notification. They're durable in status, but they don't interrupt you. Only three action-relevant states can create a notification.

| Trigger                  | Notification fires when                                                                      | Stays passive when                                            |
| ------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Blocking Degraded State  | Active Work At Risk can't sync, hydrate, materialize, or continue for 60 continuous seconds. | The degraded state has no Active Work At Risk.                |
| Review-Ready Agent Lease | The lease was user-started, user-followed, or already in your active review context.         | Background automation you didn't start or follow.             |
| Device Approval Request  | A signed-in device or agent host requests workspace decryption access.                       | Never silent: it's durable status first, notification second. |

<Callout type="warn" title="Important">
  A Sync Conflict never steals focus or fires a notification. Bowline keeps each machine's Local Active View stable and surfaces the conflict passively in `bowline status` and the TUI. You decide when to repair it.
</Callout>

## Next steps [#next-steps]

* [Resolve a sync conflict](/docs/guides/resolving-conflicts): detect, inspect, and repair a conflict from status.
* [Conflicts](/docs/concepts/conflicts): how Bowline preserves both sides when work diverges.
* [Device trust](/docs/concepts/device-trust): how a Device Approval Request grants workspace decryption access.
* [Agent leases](/docs/concepts/agent-leases): when a Review-Ready Agent Lease notifies you.
* [macOS](/docs/platforms/macos) and [Linux](/docs/platforms/linux): how ambient surfaces behave per platform.
* [CLI overview](/docs/cli/overview) and [CLI commands](/docs/cli/commands): full reference for `status`, `actions`, and `events`.