docs: prune landed todos + refresh scratchpad + as-built terminal-rendering

todo: drop landed entries (terminal coherence pass, get_state_file
defense-in-depth, self-management of loose ends, persist+cold-load
ctx-badge).

claude.md:
- scratchpad: new just-landed entries for ctx+cost badge split,
  terminal coherence pass, loose_ends rename + cancel_loose_end,
  whoami, reminder failure persistence, path linkify, tombstones+
  meta_inputs events, agent open-threads section + container pending-
  reminder chip + task event rendering. drops the meta-flake
  "just landed" — structural facts live in the file map +
  approvals.md, the narrative was no longer load-bearing.
- file map: hive-fr0nt now lists MARKED_JS + marked.min.js + the
  unified prefix-column terminal.css update.
- reading paths: terminal-rendering.md description matches as-built.

docs/terminal-rendering.md: rewritten as as-built reference. layout
contract documents the padding-left + negative text-indent prefix
column + how details inherits it. row taxonomy reflects current
state (notes split into .note / .note.stderr / .note.op; .sys is
amber; recv tool_results default-open with markdown body via
tool_use_id correlation; rich send/ask/answer renderers). new
sections for renderer dispatch flow, markdown integration,
fmtArgsGeneric extra-MCP fallback, dashboard msgrow text-indent
reset.
This commit is contained in:
müde 2026-05-18 19:25:50 +02:00
parent 2b38805c00
commit 69a3ca7469
3 changed files with 195 additions and 212 deletions

134
CLAUDE.md
View file

@ -77,19 +77,27 @@ hive-c0re/ host daemon + CLI (one binary, subcommand-dispatched)
assets/ index.html, dashboard.css, app.js (include_str!)
hive-fr0nt/ shared frontend-assets crate (browser only).
src/lib.rs pub const BASE_CSS / TERMINAL_CSS / TERMINAL_JS
re-exports; both binaries `include_str!` them
and prepend to their per-page serving routes.
src/lib.rs pub const BASE_CSS / TERMINAL_CSS / TERMINAL_JS /
MARKED_JS re-exports; both binaries
`include_str!` them and prepend to their per-
page serving routes.
assets/base.css Catppuccin palette + body typography (one source
of truth, no per-page redeclaration).
assets/terminal.css `.terminal-wrap` + `.live` + `.tail-pill` +
`.row` / `details.row` styling for both
pages' lit log panes.
pages' lit log panes. Unified prefix-column
(padding-left + negative text-indent) so glyph
alignment is consistent across row kinds + a
`.md` block scope for marked-rendered bodies.
assets/terminal.js `window.HiveTerminal.create(opts)`: scroll-
sticky log + "↓ N new" pill + history
backfill + SSE subscribe-buffer-snapshot-
dedupe dance. Pages register a kind→renderer
map; the terminal owns the lifecycle.
assets/marked.min.js vendored marked v4.0.2 UMD bundle. Per-agent
terminal uses the global `marked.parse` for
markdown bodies on send / recv / ask / answer
/ assistant text rows.
hive-ag3nt/ in-container harness crate; produces TWO binaries
src/lib.rs re-exports + DEFAULT_SOCKET, DEFAULT_WEB_PORT
@ -141,7 +149,8 @@ read them à la carte.
[`docs/web-ui.md`](docs/web-ui.md).
- **"How does the per-agent terminal classify + colour
events?"** → [`docs/terminal-rendering.md`](docs/terminal-rendering.md)
(taxonomy + known inconsistencies + a proposed coherence pass).
(as-built row taxonomy + layout contract + markdown +
extra-MCP fallback).
- **"How does claude get its prompt and what tools does it have?"** →
[`docs/turn-loop.md`](docs/turn-loop.md).
- **"How do config changes flow from manager to operator to
@ -174,31 +183,96 @@ read them à la carte.
In-flight or recent context that hasn't earned a section yet.
Prune freely.
- **Just landed:** meta-flake overhaul. Each agent's applied
repo is a module-only flake (forwards every `inputs.*`
through to `agent.nix` as the `flakeInputs` module arg —
manager edits `inputs` to pull in external flakes like an
MCP server's own flake; the new sha lands in the agent's
own `flake.lock` and rolls up to meta's). A single
hive-c0re-owned repo at `/var/lib/hyperhive/meta/`
declares one input per agent and one
`nixosConfigurations.<n>` output, wrapping the agent's
`nixosModules.default` with identity + `HIVE_PORT` /
`HIVE_LABEL` / `HIVE_DASHBOARD_PORT` /
`HIVE_OPERATOR_PRONOUNS`. Containers run against
`meta#<n>`. Every approve uses two-phase staging
(prepare → build → finalize/abort) so meta's git log only
records successful deploys; failures + denials live as
annotated tags in applied. All meta operations
serialize behind a tokio mutex; stale `.git/index.lock`
is cleared on hive-c0re startup. Manager has `/applied`
+ `/meta` RO-bound + the `applied` remote pre-wired in
every proposed repo. Migration runs idempotently on
startup (`HIVE_SKIP_META_MIGRATION=1` skips). Operator
pronouns are a NixOS module option
(`services.hive-c0re.operatorPronouns`, default
`"she/her"`); the harness substitutes them into the
system prompt at boot.
- **Just landed:** ctx + cost badges split. The per-agent
page now shows TWO chips — `ctx · N` (last inference's
prompt size = actual context window utilisation, parsed
from each `assistant` event's `.message.usage`; the
number to watch for compaction) and `cost · M` (sum
across every inference in the turn, the previous
behaviour now correctly labelled — tool-heavy turns
rebill the cached prefix per call and blow past the
model's window). Both fed by a single
`TokenUsageChanged { ctx, cost }` SSE event at turn-end
via `Bus::record_turn_usage`. `turn_stats` grew four
`last_*_tokens` columns (idempotent ALTER migration) so
cold-load seeds both badges from the most recent row.
Pre-migration rows yield no `ctx` seed (empty badge
until next turn) rather than a misleading zero.
- **Just landed:** per-agent terminal coherence pass.
Unified prefix column (padding-left + negative
text-indent so every row kind aligns); `<details>`
summaries drop the directional glyph and let CSS
`▸/▾` sit in the prefix column; turn boundaries
de-weighted (border-left rule only, no bold/margin/
tint); stderr lines render orange `!`,
operator-initiated notes mauve italic, catch-all `.sys`
escalated to orange so unrecognised stream-json
surfaces. Message-bearing tool calls
(`send`/`ask`/`answer`/`recv`) render default-open
with markdown bodies via vendored `marked` v4.0.2
(`hive-fr0nt::MARKED_JS`); assistant `text` rows also
markdown-rendered. Extra-MCP tools get a generic
args pretty-printer (`fmtArgsGeneric`) instead of
raw JSON. tool_use_id → name map carries through the
stream so `renderToolResult` knows when a result came
from `recv` and should default-open with markdown.
See `docs/terminal-rendering.md` for the as-built
taxonomy. Bonus: ctx badge seeded from `turn_stats`
on cold load via `Bus::seed_usage` so the chip paints
real numbers before the next turn finishes.
- **Just landed:** `open_threads``loose_ends` rename
(more honest about what the list is) + new
`cancel_loose_end(kind, id)` MCP tool on both
surfaces. `kind = "question"` posts a `[cancelled by
<self>]` answer to unblock the asker; `kind =
"reminder"` hard-deletes before fire. Auth: sub-agent
must own the row (`asker == self` / `owner == self`);
manager bypasses for hive-wide cleanup. `LooseEnd`
enum gained a `Reminder { id, owner, message, due_at,
age_seconds }` variant; sub-agent flavour filters by
owner, manager unfiltered. Shared dispatch in
`hive-c0re/src/questions.rs::handle_cancel_loose_end`.
Per-agent web UI's `/api/open-threads`
`/api/loose-ends`. Closes the agent-side "I have no
way to cancel what I queued" friction from the
ergonomics wishlist.
- **Just landed:** `whoami` MCP tool on both surfaces —
returns `{ name, role, pronouns, hyperhive_rev }`.
Lets an agent self-identify without scraping its own
system prompt; pronouns are pulled from the
`HIVE_OPERATOR_PRONOUNS` env that the system prompt
also substitutes, so the two stay in sync.
- **Just landed:** reminder delivery failures persist +
surface. The 5s scheduler now records the failure
reason on the `reminders` row instead of silently
dropping; the web UI surfaces them in the loose-ends
section so the owner agent can see "this reminder
never landed because the target was destroyed" without
reading journald.
- **Just landed:** path linkify. The broker tags every
message body server-side with `file_refs` at ingest
via `/api/state-file/check` (validates each path,
attaches container→host resolution). Last segment
must look like `name.ext` so directory mentions don't
fire spurious links. Dashboard renders refs as
collapsible path-preview blocks below the message
body; per-agent terminal picks them up from the same
field. Server-side validation means the JS doesn't
re-walk allow-lists on every render.
- **Just landed:** tombstones + meta_inputs as
`DashboardEvent`s. Closes the last two refetch loops
on the dashboard side — `purge-tombstone` and
`meta-update` POSTs now flip to 200 with
`data-no-refresh`. The 5s `/api/state` poll is gone
entirely; everything event-driven.
- **Just landed:** per-agent UI gained an open-threads
section (questions + approvals + reminders pending
against this agent) + the container row on the
dashboard gained a `⏰ N` pending-reminder count
chip. task_started / task_notification stream-json
events now pretty-render in the terminal with the
`⌁` glyph so subagent (Task tool) activity is
visually distinct from main-session tool calls.
- **Just landed:** per-agent extra MCP servers via the
`hyperhive.extraMcpServers.<key>` NixOS option in
`agent.nix`. Declares `{ command, args, env,