the owned herdr session
how orcr maps its path tree onto herdr workspaces, tabs, and panes inside one dedicated session that never touches your daily work.
all orcr-managed agents live in one dedicated herdr session (default name orcr, config herdr.session). your daily herdr session never sees a subagent pane. this is the boundary that keeps a 200-agent workflow from polluting the workspace you actually work in.
one owned session
first use auto-starts the session's herdr server headless. from then on:
herdr --session orcropens the native herdr UI over that session: the same tree you see inorcr top, but interactive.orcr agent attachwrapsherdr agent attach, which streams a pane's terminal into your current terminal from anywhere, with no session switching. see attach and steer.
the mapping
herdr's hierarchy is session then workspace then tab then pane. workspaces are per-session, purely visual containers with a label and no cwd; only panes have a cwd and a process. orcr uses the levels like this:
| herdr level | orcr's use |
|---|---|
| workspace | the path's level-1 segment when the path has one. everything under refactor/** maps to workspace refactor; each loop gets its own workspace. a scope-less single-segment path like worker maps to workspace default, so stray one-offs do not each spawn a workspace. GC-parked agents move to workspace idle. |
| tab | one per agent; the label is the agent's full path. path refactor/phase_1/review/worker maps to workspace refactor, tab refactor/phase_1/review/worker. |
| pane | the agent's TUI. its cwd is the caller's cwd, or --cwd. |
herdr requires each agent's name (which is also its tab label) to be unique across the whole session. a label built from the path-after-the-first-segment would collide across distinct level-1 scopes: review_a/fanout/file_0 and review_b/fanout/file_0 would both reduce to fanout/file_0. so orcr uses the full effective path as the label, which is unique among active agents by construction (see identity).
a pane's location ids are not agent identifiers. GC moves agents across panes and workspaces over their lifetime; the store tracks the agent's current pane as a location column, nothing more. see durability and recovery for how a pane is re-matched to its row by label after a herdr restart.
ownership marker
every pane orcr creates carries ORCR_ID in its environment, plus an internal launch token, and has a matching store row. that marker is how reconciliation decides what it may touch:
- a live pane it can positively tie to its store row (by herdr label) is orcr's to move, park, or close.
- a herdr-reported agent pane with no matching row (the store was moved or reset under a live session) is reported in
server statusas an orphan agent pane and left alone: clean it up through herdr directly. - an unmarked pane in the owned session (a shell you opened while debugging) is reported and never touched either.
herdr's socket cannot read ORCR_ID back off a live pane, so the label is the practical re-matching key; the launch token stays injected and persisted as the correctness anchor for a future herdr that exposes pane env.
orcr always closes its panes
herdr removes a workspace automatically once it has no panes. so orcr always closes panes it is done with: on kill, on reap, on gc immediate. closing the last pane closes the tab, and emptying the workspace removes it. leaving a stray pane behind would pin the workspace forever, which is why the lifecycle is careful to close panes rather than just abandon them. see agent lifecycle and GC.
identity: paths and uuids
the two identifiers every agent carries, the path and glob model that addresses them, and the rules for naming, resolution, and reservation.
agents and subagents (lineage)
how an orcr agent spawns subagents, how the server derives scope and records lineage from the environment, and how orcr top renders the tree.