# panto-herdr

`panto-herdr` reports panto lifecycle state to [Herdr](https://herdr.dev/) when
panto is running in a Herdr pane. It reports `panto` as the agent label and
uses `thinking`, `responding`, `compacting`, and `tool:<name>` as short report
messages.

Install it through panto's rock loader:

```toml
[extensions]
rocks = ["panto-herdr"]
```

Then run `panto update`. Start panto in Herdr, for example:

```sh
herdr agent start panto --cwd "$PWD" -- panto
```

The extension is inert outside Herdr: it only activates when `HERDR_PANE_ID`
is set. It invokes the local `herdr` executable asynchronously and discards
its JSON output, so reporting does not affect the panto terminal UI.

## State mapping

| panto event | Herdr state |
| --- | --- |
| `session_start`, `session_ready` | `idle` when no work is active |
| `turn_start`, `agent_submission`, `user_message`, `thinking`, `compaction`, `tool_details`, `assistant_text` | `working` |
| `turn_end` | `idle` when no background work is active |
| `background_work_start` / `background_work_end` | increments / decrements active background work |
| `session_end` | agent released |

Extensions with work that survives a turn emit balanced `background_work_start`
and `background_work_end` events. Herdr remains `working` until both the primary
turn and all such work finish. `session_end` removes panto's agent report when
the process shuts down.

## Check

Run the module-level check with panto's Lua runtime:

```sh
panto lua _selfcheck.lua
```