docs: repair the CLAUDE.md repo map

This file auto-loads into every agent's context on every turn, so each
error in it is paid continuously by everyone rather than once by whoever
reads it. Four of them:

Five workspace members were missing entirely: hive-jobq, hive-types,
hive-agent-sock, hive-core-agent-sock, hive-screen-mcp. hive-jobq is the
worst of those to omit -- it is the crate the c0re-side job_queue layer
is being folded into, so the map that loads every turn did not mention
the target crate exists.

hive-claude was listed as a workspace member. It has no directory here
and is consumed as a dependency, so anyone following the map went
looking for source that is not in this repo. Moved to its own section
that says so.

The issue tracker was linked at a loopback address. Inside an agent
container loopback is the agent, not the forge, so the link cannot
resolve for its primary audience; point at the env var instead.

The ops label was written with a colon. The real label uses a slash,
and a colon does not fail loudly -- the filter matches nothing and
returns unfiltered results, which reads like a backlog instead of like
an error.
This commit is contained in:
atlas 2026-08-02 04:50:26 +02:00 committed by mara
commit a9e05d3bb1

View file

@ -5,11 +5,15 @@ Hey claude. This is your starting page. The detailed docs live in
when you need depth on a subsystem. This file is the index.
- High-level project intro: **[README.md](README.md)**.
- Open work + backlog: the **[forge issue
tracker](http://localhost:3000/hyperhive/hyperhive/issues)**.
- Open work + backlog: the forge issue tracker at
**`$HIVE_FORGE_URL/hyperhive/hyperhive/issues`**. Read the host out of
the env var — inside an agent container `localhost` is the *agent*, not
the forge, so a hardcoded loopback address fails to connect.
- Operator/agent trust-boundary design:
**[docs/boundary.md](docs/boundary.md)** (`area:ops` issues
for the deployment/gateway/privsep work).
**[docs/boundary.md](docs/boundary.md)** (`area/ops` issues
for the deployment/gateway/privsep work — the separator is a **slash**;
`--label area:ops` matches nothing and silently returns *unfiltered*
results, which reads like a backlog rather than like an error).
- Agent trust model (trust boundary, prompt-injection threat model,
capability = accepted risk), credential isolation + sandbox threat model:
**[docs/security.md](docs/security.md)**.
@ -50,12 +54,20 @@ hand-maintained per-file tree drifts out of sync with the code.
streamable-http listener, `hive-mcp-http` systemd unit) + its claude
launch-config layer (tool-group/capability → `--allowedTools`,
`--mcp-config` render).
- **`hive-claude/`** — reusable, app-agnostic driver for headless
`claude --print`: spawns the CLI, streams + classifies stream-json,
parses per-turn `Telemetry`, and drives a durable self-compacting
`InfiniteSession` (name + `SessionStore` + `CompactionPolicy`). Uses
`thiserror` (it's a library); the `hive-*` binaries consume it with
`anyhow`. See `hive-claude/README.md`.
- **`hive-jobq/`** — persistent job-DAG scheduler, extracted from
hive-c0re's in-tree `job_queue` as a domain-agnostic library. One
persistent graph for the whole system (not a DAG per job); enqueuing
inserts a self-contained sub-DAG and returns its node ids. Generic over
the node payload `N` and the resource name `R`; resource deps are named
counting semaphores acquired all-or-nothing at node start. `hive-c0re`'s
remaining `job_queue/` module is the c0re-specific layer *over* this
crate, and is being removed in favour of it — new scheduler-shaped code
belongs here, not there.
- **`hive-screen-mcp/`** — stdio MCP bridge for GUI agents
(`hyperhive.gui.enable`): `screenshot` via `grim`, `type_text` /
`key_press` via `wtype` (Wayland virtual-keyboard protocol), and
`mouse_move` / `mouse_click` as RFB pointer events to the local neatvnc
server. All userspace, no daemon of its own.
- **`hive-priv/`** — minimal root privileged-helper, socket-activated at
`/run/hive/priv.sock`; performs the few root operations (bind-mount
edits, nsenter) the unprivileged `hive-c0re` delegates to it. See
@ -89,6 +101,23 @@ hand-maintained per-file tree drifts out of sync with the code.
- **`hive-priv-sock/`** — wire types for the `hive-priv` privileged-helper
socket (`/run/hive/priv.sock`), shared by `hive-priv` (server) and
`hive-c0re` (client). Also split out of `hive-sh4re`.
- **`hive-core-agent-sock/`** — wire types for the *host*-served per-agent
+ manager socket (`/run/hive/mcp.sock`), the protocol an agent's harness
speaks to `hive-c0re`. Same split rationale as the two above; the shared
payload types it references stay in `hive-sh4re`.
- **`hive-agent-sock/`** — wire types for the *in-agent* socket, served by
the harness to in-container producers (matrix / bash MCP daemons,
`forge_notify`). Carries the loose-ends-v2 **todo** ops plus
harness-local reminders + questions. ⚠️ Distinct from
`hive-core-agent-sock` above: **this socket never leaves the container**
and `hive-c0re` is not in the path at all — no broker round-trip, no
long-poll, no marker files.
- **`hive-types/`** — zero-dependency (bar serde) leaf crate holding the
foundational newtypes, chiefly `Ident` (163 chars of `[a-z0-9-]`,
constructed only via the validating parser). Lets every wire-type crate
and both binaries type their agent-name fields as a validated ident and
get serde-checked parsing at the socket boundary, without coupling to
`hive-sh4re`.
- **`hive-sock-client/`** — the shared JSON-line-over-unix-socket client
every daemon uses to talk to a hyperhive socket. Generic over the
request/response types, so the host-served control socket and the
@ -101,6 +130,17 @@ hand-maintained per-file tree drifts out of sync with the code.
- **`hive-metric/`** — small CLI to push a single labeled metric to the
OTEL collector via the OpenTelemetry Rust SDK / OTLP HTTP exporter.
### External dependencies with no directory here
- **`hive-claude`** — reusable, app-agnostic driver for headless
`claude --print`: spawns the CLI, streams + classifies stream-json,
parses per-turn `Telemetry`, and drives a durable self-compacting
`InfiniteSession` (name + `SessionStore` + `CompactionPolicy`). Uses
`thiserror` (it's a library); the `hive-*` binaries consume it with
`anyhow`. ⚠️ **Its own repo, not a workspace member** — consumed as a
dependency in the root `Cargo.toml`, so there is no `hive-claude/`
directory to read and `grep` here will not find it.
### Other top-level dirs
- **`frontend/`** — npm workspaces → static dashboard + per-agent UI