# Status widget

[Documentation index](../README.md)

The TUI status widget is a local, display-only projection of exact managed
workers.

It does not replace mailbox assignment/result authority.

## Availability

The widget is installed only when the current session has a valid supported
Herdr/Pi identity and Pi is in TUI mode.

A root supervisor gets the root view.

A valid managed leaf can receive an identity-only header.

A delegation-enabled parent can receive child counts and rows.

Unmanaged or invalid worker environments do not receive the managed widget.

## Refresh

The widget refreshes managed Herdr data plus mailbox state every two seconds.

Refresh performs a bounded Herdr pane-list lookup to validate the supervisor
boundary. It does not add a socket transport or another worker-control protocol.

A refresh failure never mutates mailbox/control eligibility.

## Breadcrumb

Example:

```text
● root → implementer → scout
```

The breadcrumb uses validated definition/worker ancestry.

If an ancestor cannot be proved, it is shown explicitly as `?` rather than
guessed:

```text
● ? → scout
```

## Header counts

Example:

```text
● root → implementer  2 active · 1 settling · 3 ready · 1 unknown
```

`active` counts `working` and `blocked`.

`settling` is separate.

`unknown` appears only when present.

Before the first successful refresh, the header says `unavailable`.

After a later refresh failure, the widget retains the last valid snapshot and
marks the header `stale`.

Header refresh staleness is not worker inactivity.

## Worker rows

Selection priority:

1. `working`
2. `blocked`
3. `settling`

A ready parent may appear as static context for an active child.

The widget shows bounded direct-child structure and has a four-agent-node
visibility budget. Hidden active workers are counted rather than overflowing the
layout.

Ready rows use a static marker.

Working, blocked, and settling may animate.

Unknown does not animate.

## Optional metadata

Rows can include best-effort:

- task;
- elapsed time;
- model;
- thinking;
- context percentage;
- worker type/display metadata.

These fields are not control authority.

The renderer preserves identity/state information before truncating task text
and bounds every output line by visible Unicode width.

The current widget does **not** claim to display the full effective tool list.
That remains separate from the definition overview.

## Worker inactivity

A `working` worker can expose an advisory inactivity marker based on durable
Pi-observed activity.

This is distinct from header `stale`, which means the widget failed to refresh
its latest snapshot.

Neither changes worker control state.

## See also

- [Worker states](worker-states.md)
- [`/subagents agents`](commands.md#subagents-agents)
- [Recovery](../guides/recovery.md)