From 99a4a75bf7d831ddada981a2ba4a7c4bd5b58d59 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 14:29:48 +0200 Subject: [PATCH 1/5] docs: clear write-good.Passive hits in docs/agent-lifecycle/approvals.md --- docs/agent-lifecycle/approvals.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/agent-lifecycle/approvals.md b/docs/agent-lifecycle/approvals.md index cbdec977..fa401402 100644 --- a/docs/agent-lifecycle/approvals.md +++ b/docs/agent-lifecycle/approvals.md @@ -25,9 +25,9 @@ CLI) before it takes effect. What you'll see, and what to do with it: the agent stays on its last-good config, no recovery action needed from you. - **New agent** (`Spawn`) — the one approval in creating a brand-new - agent. Its config repo is scaffolded first, outside the approval - queue, by the swarm controller's `InitAgentConfigRepo` job - (`POST /api/agents`); `Spawn` then creates the container from that + agent. The swarm controller's `InitAgentConfigRepo` job + (`POST /api/agents`) scaffolds its config repo first, outside the + approval queue; `Spawn` then creates the container from that config. Tailoring what the template seeded isn't a separate mechanism — it's the config-change flow above, a PR you review like any other. Every later change goes through that flow — there's no @@ -133,9 +133,9 @@ agent that lacks the `approvals` tool group: only an agent with that group submits approvals (for its direct children), so an agent without it has nothing of its own to withdraw. -A brand-new agent's config repo is created outside this queue, by the -swarm controller's `InitAgentConfigRepo` job, which seeds it with a -default `agent.nix` template. The operator then **spawns** the agent +The swarm controller's `InitAgentConfigRepo` job creates a brand-new +agent's config repo outside this queue, seeding it with a default +`agent.nix` template. The operator then **spawns** the agent (the `Spawn` approval / `◆ R3QU3ST SP4WN` button), which creates the container from that config. @@ -612,8 +612,8 @@ root agent. Variants (`hive_sh4re::manager::HelperEvent`): approval transitions to its terminal state. - `ContainerCrash { agent, note }` — `crash_watch`: a previously- running container went away with no operator-initiated transient - state (Stopping / Restarting / Destroying / Rebuilding) AND no - such transient was cleared in the last 30s (`RECENT_TRANSIENT_GRACE` + state (Stopping / Restarting / Destroying / Rebuilding) AND nothing + cleared that transient in the last 30s (`RECENT_TRANSIENT_GRACE` tombstone, three `POLL_INTERVAL`s — closes the race where a lifecycle op finishes between two crash-watch polls and the container shows briefly as "stopped without transient" before From 80e17f536d9d9dd0b6cb587a81f9d389dea8ee58 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 14:30:39 +0200 Subject: [PATCH 2/5] docs: clear write-good.Passive hits in docs/tools/bash.md --- docs/tools/bash.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/tools/bash.md b/docs/tools/bash.md index ac0d7afc..43459219 100644 --- a/docs/tools/bash.md +++ b/docs/tools/bash.md @@ -23,14 +23,14 @@ When the task completes (or times out, or the process errors), it surfaces as a todo in the agent's loose-ends (via `get_loose_ends`), carrying the exit code and a `Read()` pointer to the captured output. Handle it on a future turn — unless `wait_seconds` already -delivered the terminal result inline, in which case no todo is created -(see `status` below). +delivered the terminal result inline, in which case the daemon creates +no todo (see `status` below). - `timeout_secs` — kill the task after N seconds and mark it `timed_out`. Omit for no timeout (runs until natural exit). - `wait_seconds` — inline poll before returning (capped at 30). When the task finishes within the window the full status is - returned immediately and no todo is created; when the window expires + returned immediately and the daemon creates no todo; when the window expires the task keeps running and the daemon returns the normal `task started: id=` response. **Defaults to 3** — pass `wait_seconds: 0` to disable inline waiting and always get the immediate response. @@ -55,7 +55,7 @@ Poll the status of a task submitted with `run`. Returns: `wait_seconds` — optional inline poll (capped at 30): when the task finishes within the window the call returns the full status immediately. -Useful to avoid a separate round-trip when the task is expected to +Useful to avoid a separate round-trip when you expect the task to finish soon. Any `status` call (waited or not) that observes a terminal task clears @@ -124,14 +124,14 @@ loose-end follows. ## Relationship to the `execution` tool group -`ToolGroup::Execution` (in `AGENT_DEFAULT`) is the real gate on bash: it -controls whether the `bash` MCP server is rendered into the agent's -claude config at all (`extra_server_required_group` in -`hive-agent/src/mcp_config.rs`), suppressing every `mcp__bash__*` tool +`ToolGroup::Execution` (in `AGENT_DEFAULT`) is the real gate on bash: +`extra_server_required_group` (in `hive-agent/src/mcp_config.rs`) +controls whether the `bash` MCP server reaches the agent's claude +config at all, suppressing every `mcp__bash__*` tool when absent — not just leaving them unused. Its own `tools()` returns `&[]` and stays that way: `mcp__bash__run`/`status`/`kill` belong to a different, out-of-process MCP server (`bash`, not `hyperhive`), so they were never real entries in the `mcp__hyperhive__*` allowlist `tools()` builds — the two dead `["run", "status"]` strings it used to return -matched nothing and have been removed. Removing `execution` from an +matched nothing, so they're gone now. Removing `execution` from an agent's groups **does** remove bash availability. From bf9f9126afdb6118101808deafbb28d22765a396 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 14:31:20 +0200 Subject: [PATCH 3/5] docs: clear write-good.Passive hits in docs/tools/forge.md --- docs/tools/forge.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tools/forge.md b/docs/tools/forge.md index a8fb9489..552aaee8 100644 --- a/docs/tools/forge.md +++ b/docs/tools/forge.md @@ -17,8 +17,8 @@ markdown-docs > docs/tools/forge-cli.md`. - Credentials: `$HYPERHIVE_STATE_DIR/forge-token` - Active repo resolves, highest priority first: global `-r/--repo` flag > the `origin` remote of the cwd's git checkout > `$HIVE_FORGE_REPO` - (last-resort override, unset by default) > a hard error. No single - repo is assumed by default — see `client::Client::from_env`. + (last-resort override, unset by default) > a hard error. + `client::Client::from_env` assumes no single repo by default. ## Verbs @@ -128,7 +128,7 @@ distinct output shape — pick by what you need: | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The full human view of one item — title, body, **and** every comment in order | `view ` | prose dump; **marks the thread read** (clears the read-before-comment guard). Top-level `view` autodetects issue-or-PR by number; scoped `issue view ` / `pr view ` do the same when you already know the kind | | Just the structured metadata of one item (state, labels, assignees, head sha…) | `issue ` / `pr ` | JSON object | -| Only the comments (skip the body), for example to catch up a long thread; for PRs, review bodies (approve/request-changes/comment summaries) are merged in too | `comments ` [`--tail N`] | comment + review-body list; **marks read** | +| Only the comments (skip the body), for example to catch up a long thread; for PRs, review bodies (approve/request-changes/comment summaries) come along too | `comments ` [`--tail N`] | comment + review-body list; **marks read** | | One specific comment by its id | `comment-show ` | single comment | | The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline ` | event list | | The code change | `pr diff ` | unified diff | From 420b55bda152da792438b647784aa9a8a696d109 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 14:31:53 +0200 Subject: [PATCH 4/5] docs: clear write-good.Passive hits in docs/web-ui/agent.md --- docs/web-ui/agent.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/web-ui/agent.md b/docs/web-ui/agent.md index c53fd28d..cb90e0cf 100644 --- a/docs/web-ui/agent.md +++ b/docs/web-ui/agent.md @@ -173,7 +173,7 @@ The todos flyout is the only per-agent flyout — there is no separate "loose-ends" or "tasks" list. There used to be a note here about the `ask`/`answer` MCP tools having no inline answer form in this terminal — that whole mechanism (the tools, the dashboard's questions -pane, the wire protocol) has since been removed entirely, so there's +pane, the wire protocol) no longer exists, so there's nothing left to render a form for. ## Live view @@ -270,7 +270,7 @@ Successful POSTs return 200 (no 303 redirects). Error responses use semantic status codes: **400** for missing/invalid input (`body` required, unknown model name, invalid effort level), **409** for retryable state conflicts (turn in flight when -`/compact` is called), **500** only for genuine server/transport +`/compact` fires), **500** only for genuine server/transport failures. The matching mutations fire `LiveEvent` variants on the per-agent bus, so the client doesn't refetch `/api/state` on submit — the SSE stream From 9fd5a7a6898295c9ed2976faec2e0af02674d7e9 Mon Sep 17 00:00:00 2001 From: iris Date: Sun, 20 Sep 2026 14:32:39 +0200 Subject: [PATCH 5/5] docs: clear write-good.Passive hits in docs/swarm/services.md --- docs/swarm/services.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/swarm/services.md b/docs/swarm/services.md index 2eebc2a6..96403566 100644 --- a/docs/swarm/services.md +++ b/docs/swarm/services.md @@ -17,7 +17,7 @@ visible difference rather than one more paragraph saying the same thing. `singleHostSwarm` is the all-on-one-box switch above it: it defaults both `deploy.allSwarmServices` and `swarm.ca.autoConfigure` (this host -generates the swarm CA here). Each derived toggle can still be set on its own, +generates the swarm CA here). You can still set each derived toggle on its own, which wins, so "all local except X" needs no further option. **Both default to off**, and that's deliberate: a host can't tell @@ -46,7 +46,7 @@ the shapes worth naming are the ones they produce: somewhere. **These are a set, not a ladder with a correct top, and hyperhive -supports in-between shapes.** Each derived toggle can be set on its own (see +supports in-between shapes.** You can set each derived toggle on its own (see above), which is what makes "all local except X" a configuration rather than an unsupported edge case. Nothing in hyperhive prescribes a deployment model, so a doc that treats one shape as the real one and @@ -75,8 +75,8 @@ there is one IdP and one auth path. joining someone else's swarm sets it explicitly. Null means "no SSO configured", and consumers say so rather than guessing an address. -swarm-controller writes the users database, not by hand: agents -are created and destroyed continuously, so the subject set is dynamic. +swarm-controller writes the users database, not by hand: hive-c0re +creates and destroys agents continuously, so the subject set is dynamic. This module only guarantees the file exists and parses, so authelia starts with nobody in it rather than failing to start — a provider with no subjects yet is the correct state before anything has provisioned @@ -98,8 +98,8 @@ generates and reads each of its keys. The swarm's telemetry lands in one VictoriaMetrics, and one Grafana reads it, in two containers at `metrics.` and -`grafana.`. Two containers rather than one so Grafana can -be restarted or broken without taking the time-series database with it. +`grafana.`. Two containers rather than one so you can +restart or break Grafana without taking the time-series database with it. They derive together: a store with no UI is unreadable and a UI with no store is empty. To run one without the other, set it directly: @@ -143,11 +143,11 @@ Drilldown_ app is deliberately not installed: it only supports Loki, and no setting here changes that, so Explore is the log browser for this swarm. -| Option | When you'd touch it | -| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `deploy.victorialogs.retentionPeriod` | Default `30d`, far shorter than the metrics store's — logs are bulkier per unit of value and are typically read within days of being written. Raise it if you need to answer questions about last quarter. | -| `swarm.victorialogs.domain` | Only to rename it. | -| `swarm.victorialogs.port` | Only if something else on the services host already claims `9428`. | +| Option | When you'd touch it | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `deploy.victorialogs.retentionPeriod` | Default `30d`, far shorter than the metrics store's — logs are bulkier per unit of value and are typically read within days of ingestion. Raise it if you need to answer questions about last quarter. | +| `swarm.victorialogs.domain` | Only to rename it. | +| `swarm.victorialogs.port` | Only if something else on the services host already claims `9428`. | Like the metrics store, it binds loopback and takes no credential of its own: the gateway vhost is the only way in, and the collector is the only