---
status: resolved
claimed-by: "019fba91-eabf-76ae-b086-a37ac061d6e8"
claimed-at: "2026-07-31T20:37:00-04:00"
parent: "[[012-pi-subagents-herdr-extension-boundary-research]]"
blocked-by: []
tags:
  - ticket/prototype/afk
---

# Herdr status projection spike

## Question

Safely test whether a Herdr plugin or API-side adapter can make a non-interactive spawned Pi child appear, or at least project useful status, in Herdr's agents section without requiring the child itself to run as an interactive Herdr-pane Pi session.

## Resolution

A non-interactive child cannot be made into its own independent Herdr agents-section entry through the pane reporting APIs unless there is a Herdr pane to attach it to.
Herdr's agent reporting model is pane-bound: `herdr pane report-agent` requires a real `pane_id`, and reporting to a nonexistent pane fails with `pane_not_found`.
Reporting a second agent label to the current pane replaces that pane's single agent row rather than creating a second child row.
After releasing the prototype source, the pane had to be re-reported as the current Pi session, which confirms the API is assigning authority for one pane record, not adding logical children.

Useful status projection is possible on the parent pane.
`herdr pane report-metadata` with a distinct source can set `display_agent`, `state_labels`, and bounded `tokens` on the existing Pi row.
In the prototype, setting `display_agent = "pi child: scout"`, a `working` state label, and a child token appeared in both `herdr agent list` and `herdr api snapshot` for the current pane.
A 5-second TTL removed that projected metadata automatically, returning the row to the ordinary Pi display.

A Herdr plugin could therefore show spawned-child status only by either receiving child lifecycle events and projecting summary metadata onto an existing pane, or by creating/using real Herdr panes for children and reporting those panes as agents.
A Pi-side extension or host-neutral subagent core with a Herdr adapter is the more natural owner of the lifecycle events, because Herdr cannot infer invisible Pi subprocess state on its own.

Verdict: independent agents-section entries require Herdr panes.
Parent-pane status projection without child panes is feasible and safe enough for optional summary status, but it is not a substitute for true per-child Herdr visibility.

## Evidence

Current environment contained `HERDR_ENV=1`, `HERDR_PANE_ID=w6:p1`, and `HERDR_SOCKET_PATH=/home/alexion/.config/herdr/herdr.sock`, so the prototype could safely target the current pane.

Before projection, `herdr agent list` showed one row for the current pane with `agent = "pi"` and `agent_status = "working"`.
Running `herdr pane report-metadata "$HERDR_PANE_ID" --source pi-subagent-prototype --display-agent 'pi child: scout' --state-label working='child working' --token child='scout-1' --ttl-ms 5000` added `display_agent`, `state_labels`, and `tokens` to the same row.
After six seconds, `herdr api snapshot` showed those fields had returned to `null` while the pane remained the ordinary Pi agent row.

Running `herdr pane report-agent "$HERDR_PANE_ID" --source pi-subagent-prototype --agent pi-subagent-child --state blocked --message 'prototype child blocked'` changed the current pane's single agent row to `agent = "pi-subagent-child"` and `agent_status = "blocked"`.
It did not create a second agent row.
Running `herdr pane release-agent "$HERDR_PANE_ID" --source pi-subagent-prototype --agent pi-subagent-child` removed that source's authority and left the pane as `agent = null`, `agent_status = "unknown"` until the current Pi session was re-reported.
The current pane was restored with `herdr pane report-agent "$HERDR_PANE_ID" --source herdr:pi --agent pi --state working --agent-session-id "$PI_SESSION_ID"`.

Running `herdr pane report-agent w999:p999 --source pi-subagent-prototype --agent pi-subagent-child --state working` failed with `pane_not_found`, confirming there is no report-only path for a logical agent without a real pane id.