managed vs unmanaged agents
what orcr creates and fully manages, what it merely tracks from your own herdr sessions, and the exact behavior contract that separates the two.
orcr tracks all agents herdr can see, including ones you started by hand in your own sessions. it only manages the ones it created. the distinction decides which verbs work, whether GC touches the pane, and how identity is assigned.
the two kinds
- managed: created by
agent runin the owned session. full lifecycle: queue, concurrency caps, custom naming, parent lineage, verified-idle completion, GC. - unmanaged (detected): agents herdr detects in your own sessions. the server discovers them into the store and keeps them current while it runs (state changes and closure, polled or streamed from herdr every few seconds).
discovery is for supported providers only
unmanaged discovery tracks supported providers only: providers with both integration layers present (see providers and integrations). agents of any other provider are ignored entirely: not stored, not shown. server status reports per-provider integration state so the gap is visible.
each unmanaged row is keyed internally by (herdr session, terminal_id). herdr's terminal_id is globally unique and never reused, so no wider tuple is needed: a new terminal in the same pane slot is a new row with a new uuid, and rows whose terminal disappears are marked ended (still queryable under ls --all).
identity is auto-assigned
an unmanaged agent gets a uuid like any other row, and a path under unmanaged/<session_slug> with the leaf derived from the pane, for example unmanaged/main/w6_p1. slug collisions after normalization get a deterministic _<short hash> suffix inside the insertion transaction. the tree groups unmanaged agents by session. you cannot choose an unmanaged agent's name or path: that is what managed means.
status set
unmanaged agents are tracked from herdr's reporting only: working, idle, blocked, unknown, ended. there is no queue, no parking, no start tracking. unknown is herdr's catch-all. compare the full managed lifecycle in status model and completion.
the behavior contract
| feature | managed | unmanaged |
|---|---|---|
run (create) | yes | no; by definition, orcr did not create them |
| queue + concurrency caps | yes | no |
| GC (park / reap / gc modes) | yes | no; orcr never touches their panes |
custom --name / --path | yes | no; identity is auto-assigned |
parent lineage (top tree edges) | yes | no; ORCR_PARENT_* is unknowable |
| status tracking | full lifecycle | herdr-reported only: working/idle/blocked/unknown/ended |
| turn completion (verified idle) | yes | approximate; herdr state only, no input epochs for turns orcr did not deliver |
send | yes | yes (delivery works; the turn it starts is tracked as external) |
wait | yes, full semantics | yes, on herdr-reported status |
attach | yes | yes |
logs / --last-response | yes | yes (both integrations are guaranteed for tracked agents; transcript_unavailable if the transcript cannot be located or settled) |
kill | yes | requires --force (closes a pane orcr does not own) |
ls / top | yes | yes (grouped under unmanaged/<session>) |
the --force requirement on unmanaged kill is the guardrail: closing a pane you opened by hand is possible but never accidental. kill on an unmanaged target without --force returns state_conflict with reason: "force_required".
reconciliation
discovery is part of the server's broader reconciliation: on start and periodically, it repairs drift between the store and herdr reality. unmanaged rows are discovered and kept current; rows whose terminal vanished are ended. panes in the owned session with no matching store row are reported in server status and left alone, never adopted as unmanaged.
queue and concurrency
how admission control protects the machine, with one FIFO queue, a global cap plus per-provider caps, and the stuck-start guard.
providers and integrations
why a provider needs both a herdr integration and an orcr integration, what each layer does, and how the driver contract is pinned to herdr's socket methods.