parallelize graceful agent drains, serialize container stops on fast lane; unify shutdown+checkpoint+compact prompt

docs/coordinator.md

@@ -40,7 +40,7 @@ somewhere."
 | `Destroy` | For future use (`destroy --purge` does real I/O). Variant exists so the wire shape doesn't change later; not currently routed through the queue. |
 | `Restart` | Stop + start a container without touching config (~5-10s). Routed through the queue so it serialises against in-flight rebuilds for the same agent — prevents a restart racing a rebuild mid-flight. Sources: dashboard ↺ button, the `restart` MCP tool. |
 | `PermChange` | Write a tool-group or capability change to the shared JSON file (`tool-groups.json` / `capabilities.json`), then rebuild the agent so the updated `HIVE_TOOL_GROUPS` / `HIVE_CAPABILITIES` env var takes effect. Serialising the file write through the queue prevents concurrent dashboard batch-apply actions from racing on the shared file. After a successful file write, emits `CapabilitiesChanged` or `ToolGroupsChanged` SSE snapshot so the P3RM1SS10NS tab updates live. |
-| `GracefulStop` | Quiesce then stop a container (the `?graceful=true` path on `/api/kill/<agent>`). Signals the harness (its next `Recv` returns `GracefulStop` — the inbound fence — so it runs one stop-checkpoint turn to flush durable `/state`, then exits), waits for it to drain (bounded by a 3-min timeout → hard-stop fallback), then runs the normal container-stop teardown. Queued so it can't race an in-flight rebuild for the same agent. |
+| `GracefulStop` | Quiesce then stop a container (the `?graceful=true` path on `/api/kill/<agent>`). Signals the harness (its next `Recv` returns `GracefulStop` — the inbound fence — so it runs **one** stop-checkpoint turn that flushes durable `/state` and compacts the session if it crossed the watermark, then exits) and **immediately releases the build lane**, spawning a detached watcher that holds the `Stopping` transient across the drain (bounded by a 3-min timeout → hard-stop fallback) and then enqueues a fast-lane `Stop` (`parent_id` = this entry) for the actual `nixos-container stop`. Net: a whole-hive graceful stop signals every agent up front, drains overlap, and only the container teardowns serialise (on the fast lane). Queued so the signal can't race an in-flight rebuild for the same agent. |
 
 **Intentionally not queued** (sub-second ops): the *hard* `start`, `stop`, `kill`. (A *graceful* stop is the `GracefulStop` kind above — it takes a checkpoint turn, so it rides the queue.)
 

docs/turn-loop.md

@@ -517,6 +517,12 @@ ttl_seconds?, to?)`, `answer(id, answer)`.
   explicit `from: "graceful-stop"` message instead of an empty inbox.
   This unmissably directs the agent to flush durable state (`/state`
   files) and end the turn — the container exits when the turn completes.
+  This is a **single** wake: the graceful-stop turn *is* the checkpoint
+  (its prompt carries the full notes/CLAUDE.md/TODO.md flush guidance),
+  so the harness compacts directly afterwards if the context crossed the
+  watermark (`CompactionMode::CompactOnly`) rather than waking a second
+  dedicated checkpoint turn. Compacting before shutdown keeps a later
+  cold start cheap instead of re-uploading a huge transcript.
 - `ask` — surface a structured question to the operator (default) or
   a peer agent (`to: "<agent>"`). Non-blocking — returns a question
   id; the answer arrives as a `question_answered` system event in the