Status and health

What healthy, attention, and limited mean, how workspace and project status differ, and the narrow cases where Bowline notifies you.

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

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

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.

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.

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

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

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

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.

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.

Next steps

Resolve a sync conflict: detect, inspect, and repair a conflict from status.
Conflicts: how Bowline preserves both sides when work diverges.
Device trust: how a Device Approval Request grants workspace decryption access.
Agent leases: when a Review-Ready Agent Lease notifies you.
macOS and Linux: how ambient surfaces behave per platform.
CLI overview and CLI commands: full reference for status, actions, and events.