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