← Documentation

Delegates

Part of the team file — Panes outside the team's session that may run some operational commands, and the allowlist guard on a delegated approval.

Names panes outside the team's session that may run some operational commands as a delegate of this team file. It is an owner section: only the owner writes it. Omitted, it reads as null and nothing is delegated.

team.yaml
delegates:
  - pane: main/w1:p1        # <herdr session>/<pane id>, outside the team's session
    commands: [up, down]    # of up, down, add, remove, approve, swap: non-empty, distinct, order kept
  - pane: main/w2:p1
    commands: [add, remove]
  • One to eight entries, each a map with exactly pane and commands; two entries naming one pane are refused.
  • A pane is herdr's pane ID — <session>/<pane id>, such as main/w1:p1 — one slash, no whitespace, matched on the whole string and case-sensitively. A pane closed and made again has a new ID, so delegation is off until the owner writes that new ID into the file.
  • commands names at most one each of the six up, down, add, remove, approve and swap. swap admits team remove <lead> --keep and team add <lead> on the orchestrator's or the operator's seat — the swap of that seat's agent — and nothing else; remove never reaches a lead. Entry order and command order are part of the value the owner writes: a reorder is a change like any other.
  • approve is accepted in commands and acts on nothing: team approve was removed, the word stays so a file that already names it loads unchanged, and team check prints a note above its findings asking for it to be dropped. Every other act reads the live file. A delegate's commands write the file's roster alone: the owner's sections — delegates, budgets, limits, identity, trust, the workspace, the operator and orchestrator — stay the owner's, and so does any section added later. A delegated act records one audit line naming the pane and what it did.
  • A pane several teams' live files name is a delegate of each — the files do not see or limit one another — and in every one of them the owner-only sections stay the owner's, never a delegate's.
  • A pane's own shell reaches that pane's grant when the pane's root process is among the caller's ancestors. HERDR_PANE_ID only names which pane to read; the pid is what places the caller. No such variable, a root that is not an ancestor, or a pane-root read that fails places nobody, as before. A command the grant does not list is still refused, and a pane no grant lists is refused by name: it runs in pane <session>/<pane id>, which no grant lists.
  • Delegate placement is an accident guard, not a security boundary. The pane ancestry and herdr's pid vouch are forgeable by a hostile process of the same user, which this tool does not resist: it guards a mistaken agent, not a hostile one. Nothing in the grants or in trust: is changed by that.