docs(examples): add the "snake pit" worker-pool example

Based on @ponder.ooo's "snake pit agent orchestrator" idea (bsky 2026-05-28) and
Claude's metaphor-mapping elaboration: agents are snakes, tasks are food tossed
into a shared pit; snakes devour/digest/regurgitate/excrete.

A worker-pool-over-a-shared-queue topology (contrast the builder-adversary phase
machine):
- pit/ is a filesystem queue; snakes claim by atomic mv (no two eat the same food)
- species = specialized agents: keeper (zookeeper), planner (regurgitation IS
  task decomposition), snake-1..3 (worker pool), cleanup (scavenger + coprophagy)
- no [loop] phase machine; persistent agents self-pace via /loop
- README carries the full bio→compute mapping table from the thread image

Verified: `agents.py status --config agents.toml` lists all 6 agents + service.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

examples/snakepit/pit/README.md

@@ -0,0 +1,49 @@
+# The pit — a filesystem task queue
+
+The pit is just directories. Snakes coordinate entirely through atomic `mv` between them — moving a
+file within one filesystem is atomic, so two snakes can never devour the same food.
+
+```
+pit/
+  food/      the queue: tasks waiting to be eaten        (food-<id>-<slug>.md)
+  claimed/   in digestion: a snake is working this one   (<snake-id>.food-<id>-<slug>.md)
+  done/      regurgitated WHOLE: a finished result        (food-<id>-<slug>.result.md)
+  scraps/    regurgitated in PARTS: notes/leftovers        (anything; informational)
+  waste/     excreted waste: chat logs, debug traces       (<snake-id>-<ts>.log)
+```
+
+> Sub-tasks ("broken / digested parts") are regurgitated back into **`food/`** as new food items, so
+> any snake can devour them. `scraps/` is for non-actionable leftovers a snake wants to keep around.
+
+## Food schema (`pit/food/food-<id>-<slug>.md`)
+
+```markdown
+# food-0007-reverse-string
+- **task:** Implement a `reverse(s)` function in scraps/reverse.py and a test that proves it.
+- **done-when:** `python -m pytest scraps/test_reverse.py -q` is green.
+- **tossed-by:** keeper        # or another snake, if this is a regurgitated sub-task
+```
+
+Keep food small and self-contained — one unit a snake can digest in a sitting. If a task is too big,
+a snake regurgitates it as several smaller food items.
+
+## The eating protocol (snakes)
+
+1. **Devour** — atomically claim one item:
+   `mv pit/food/food-0007-reverse-string.md pit/claimed/snake-2.food-0007-reverse-string.md`
+   If the `mv` fails, another snake beat you to it — pick a different one.
+2. **Digest** — do the work described in the food.
+3. **Regurgitate** — *whole*: write the result to `pit/done/food-0007-reverse-string.result.md`
+   and `git`-free remove the claimed file. *In parts*: if it decomposes, write new `food-*` items
+   into `pit/food/` for other snakes, and note that in your result.
+4. **Excrete** — drop your working log/trace as `pit/waste/snake-2-<ts>.log`; don't let it pile up
+   in the workspace.
+5. **Choke?** On the 3rd identical failure, regurgitate the food back to `pit/food/` (or leave it in
+   `claimed/` past the cleanup timeout) with a note in `scraps/`, so another snake or the keeper
+   takes it.
+
+## Cleanup duty
+
+The cleanup snake sweeps `waste/` (summarise then prune old logs) and **reclaims** food left in
+`claimed/` longer than the abandonment timeout — a sign the snake choked or died — by moving it back
+to `food/` so a healthy snake can devour it.

examples/snakepit/pit/claimed/.gitkeep

@@ -0,0 +1 @@
+# in digestion — food a snake has devoured: <snake-id>.food-<id>-<slug>.md  (see ../README.md)

examples/snakepit/pit/done/.gitkeep

@@ -0,0 +1 @@
+# regurgitated whole — finished results: food-<id>-<slug>.result.md (and planner *.plan.md). See ../README.md

examples/snakepit/pit/food/food-0001-reverse-string.md

@@ -0,0 +1,9 @@
+# food-0001-reverse-string
+- **task:** Implement a `reverse(s)` function in `pit/scraps/reverse.py` and a pytest that proves it
+  (empty string, ASCII, and a unicode string round-trip: `reverse(reverse(s)) == s`).
+- **done-when:** `python -m pytest pit/scraps/test_reverse.py -q` is green.
+- **tossed-by:** keeper
+
+<!-- A sample piece of food so the pit isn't empty on first `up`. Snakes devour it per
+     pit/README.md: mv it into pit/claimed/<snake-id>.food-0001-reverse-string.md, digest, then
+     write pit/done/food-0001-reverse-string.result.md. The keeper tosses real food the same way. -->

examples/snakepit/pit/scraps/.gitkeep

@@ -0,0 +1 @@
+# regurgitated in parts — non-actionable leftovers, stuck-notes, reclaims. See ../README.md

examples/snakepit/pit/waste/.gitkeep

@@ -0,0 +1 @@
+# excreted waste — snake logs/traces: <snake-id>-<ts>.log; cleanup composts these. See ../README.md