docs(approvals): update helper-events routing to reflect shipped behavior

notify_manager (always-root) has been replaced by notify_submitter
(routes to the approval submitter, with root fallback for legacy rows).
Update three locations:

- Step 6 of end-to-end flow: "root agent's inbox" →
  "submitting agent's inbox"; explain notify_submitter + submitter column.
- InitConfig paragraph: remove limitation note; "to the root agent's inbox
  (current limitation...)" → "to the submitting agent's inbox via notify_submitter".
- Section header + prose: "Helper events to the root agent" →
  "Helper events to the submitting agent"; rewrite lead paragraph around
  notify_submitter semantics (approvals.submitter column, legacy fallback).
This commit is contained in:
iris 2026-06-23 22:13:28 +02:00 committed by mara
commit fae2025247

View file

@ -66,11 +66,11 @@ informed about what happens after a decision lands.
failure, main stays put and the working tree resets back to
the previous deployed commit.
6. `HelperEvent::ApprovalResolved` (and `Rebuilt` for the
ApplyCommit kind) land in the root agent's inbox, carrying both
the canonical sha and the terminal tag. (Helper events currently route
to the root agent via `notify_manager` regardless of which agent
submitted the approval; routing them to the submitting agent is a
known limitation under active development.)
ApplyCommit kind) land in the **submitting agent's** inbox, carrying
both the canonical sha and the terminal tag. Helper events route to
the submitting agent via `notify_submitter` (the approval row carries
a `submitter` column recording which agent called `request_apply_commit`
or `request_init_config`).
### Withdrawing a pending approval
@ -91,10 +91,8 @@ without it has nothing of its own to withdraw.
`InitConfig` approvals are the first step in a two-step spawn
flow. On approve, hive-c0re seeds the proposed config repo with
a default `agent.nix` template and sends `HelperEvent::ConfigReady { agent }`
to the root agent's inbox (current limitation — all helper events route
to the root agent via `notify_manager` regardless of which agent
submitted; routing to the submitting agent is under active development).
The submitting agent then reviews,
to the submitting agent's inbox via `notify_submitter`. The submitting
agent then reviews,
edits, and commits the template before calling `request_apply_commit`
to proceed to an `ApplyCommit` approval. The first `ApplyCommit`
creates the container; subsequent ones rebuild it with new config.
@ -545,15 +543,14 @@ Two more paths resolve a pending question with a sentinel answer:
resolved races no-op. The dashboard surfaces a `⏳ MM:SS` chip
on each pending question with a deadline.
## Helper events to the root agent
## Helper events to the submitting agent
`Coordinator::notify_manager(&HelperEvent)` enqueues an inbox
message from sender `system` with the event JSON in the body. The
root agent's harness no longer short-circuits these — they drive a
regular claude turn so the root agent can react. (Today these go to the
root agent regardless of which agent submitted the approval — routing to
the submitting agent is a known limitation under active development.) Variants
(`hive_sh4re::HelperEvent`):
`Coordinator::notify_submitter(approval_id, &HelperEvent)` routes the
event to the agent that originally submitted the approval (looked up from
the `submitter` column on the `approvals` table). The harness delivers it
as a regular `system` inbox message so it drives a normal claude turn.
Legacy approval rows that predate the submitter column fall back to the
root agent. Variants (`hive_sh4re::HelperEvent`):
- `ApprovalResolved { id, agent, commit_ref, status, note }`
fired by `actions::approve` + `actions::deny` whenever an