docs: update for recent commits (rate limiting, reply threading, screen, auto-reset, two-step spawn, ctx chip)

docs/turn-loop.md

@@ -20,7 +20,12 @@ Each agent harness (`hive-ag3nt serve` or `hive-m1nd serve`) runs:
    `LiveEvent::Stream(value)`. Pump stderr as `Note`.
 6. Wait for claude to exit. Compaction is two-pronged — *reactive*
    on `Prompt is too long` and *proactive* on a context watermark
-   (see [Compaction](#compaction) below).
+   (see [Compaction](#compaction) below). **Rate-limit detection**:
+   if stdout contains `429` or `rate_limit` markers, the harness
+   sets the `rate_limited` sentinel (`Bus::emit_status("rate_limited")`),
+   sleeps `HIVE_RATE_LIMIT_SLEEP_SECS` (default 300), then retries.
+   The dashboard and per-agent page show a `⊘ rate limited` badge
+   while the harness is parked.
 7. Emit `LiveEvent::TurnEnd { ok, note }`. Sleep `poll_ms` to avoid
    tight loops on transient failures.
 
@@ -78,6 +83,20 @@ best-effort — a failed checkpoint turn or `/compact` is surfaced as a
 `Note` but never fails the turn that already succeeded. The operator
 can also force a compaction any time via `/api/compact`.
 
+- **Auto session-reset** — a third path that fires when both
+  conditions hold: context is ≥ a watermark (`HIVE_AUTO_RESET_WATERMARK_TOKENS`,
+  default `100_000`) AND the time since the last turn exceeds the
+  assumed prompt-cache TTL (`HIVE_CACHE_TTL_SECS`, default `300`).
+  Claude's prompt cache lives ~5 minutes; if the cache is already
+  cold, resuming with `--continue` pays the full re-upload cost of
+  the current context with no benefit over starting fresh. So:
+  `drive_turn` injects one `AUTO_RESET_CHECKPOINT_PROMPT` notes turn
+  ("flush state to files, cache is cold") then arms
+  `Bus::take_skip_continue()` for the real turn — the next turn runs
+  without `--continue`, starting a fresh session. Unlike proactive
+  compaction the session is dropped entirely, not compacted. Set
+  `HIVE_AUTO_RESET_WATERMARK_TOKENS=0` to disable.
+
 The child runs with `cwd = /state` (when the bind exists; falls
 back to the parent's cwd in dev), so any relative path in a tool
 call (`Read foo.md`, `Bash ls`, `Write notes.md`) lands in the
@@ -126,9 +145,11 @@ it as a stdio child via `--mcp-config`. The hyperhive socket name is
 
 ### Sub-agent tools
 
-- `send(to, body)` — message a peer (logical agent name), another
-  agent, or the operator (recipient `operator`, surfaces in the
-  dashboard inbox).
+- `send(to, body, in_reply_to?)` — message a peer (logical agent
+  name), another agent, or the operator (recipient `operator`,
+  surfaces in the dashboard inbox). Optional `in_reply_to: i64`
+  links this message to a prior message id for thread rendering
+  in the dashboard message flow and the per-agent inbox.
 - `recv(wait_seconds?, max?)` — drain inbox messages. Without
   `wait_seconds` (or with `0`) returns immediately, a cheap
   "anything pending?" peek. Positive value parks the turn up
@@ -161,7 +182,9 @@ it as a stdio child via `--mcp-config`. The hyperhive socket name is
   this agent's own inbox at a future time (sender shows as
   `reminder`). Large payloads spill to
   `/agents/<self>/state/reminders/` with the inbox message a
-  short pointer.
+  short pointer. Each agent's pending-reminder count is capped
+  (default 50, override via `HIVE_REMIND_MAX_PENDING_PER_AGENT`);
+  scheduling a new one fails if the cap is already hit.
 - `whoami()` — `{ name, role, pronouns, hyperhive_rev }` for
   self-identification without scraping the system prompt.
 
@@ -209,8 +232,17 @@ meta's.
 
 ### Manager tools (in addition to send/recv)
 
-- `request_spawn(name)` — queue a Spawn approval for a brand-new
-  sub-agent (≤9 char name). Operator approves on the dashboard.
+- `request_init_config(name, description?)` — first step of a
+  two-step spawn. Queues an `InitConfig` approval (≤9 char name);
+  on operator approve, hive-c0re seeds the proposed config repo
+  with a default `agent.nix` template and sends the manager a
+  `HelperEvent::ConfigReady { agent }`. The manager then edits
+  `agent.nix`, commits the changes, and calls `request_spawn`.
+  Fails if a proposed repo for this name already exists.
+- `request_spawn(name)` — second step of a two-step spawn. Queues
+  a Spawn approval; requires the proposed config repo to exist
+  (from a prior approved `request_init_config`). Operator approves
+  on the dashboard to create the container.
 - `kill(name)` — graceful stop. No approval required.
 - `start(name)` — start a stopped sub-agent. No approval.
 - `restart(name)` — stop + start. No approval.