diff --git a/README.md b/README.md
index 05810a6..eef857c 100644
--- a/README.md
+++ b/README.md
@@ -195,7 +195,8 @@ Then arrow keys ←/→ to navigate, **Space** to play/pause, the bottom slider
## Where to read next
- **[INSTALL.md](INSTALL.md)** — clone-to-running on a fresh macOS box. Prerequisites, Python venv setup, Swift toolchain, regenerating sim data, running the agents demo, troubleshooting.
-- **[src/crisis_agents/README.md](src/crisis_agents/README.md)** — the AI-agent coordination layer: architecture, six-phase walkthrough, decentralization principles, async event loop, quorum formula, live Claude mode, proof JSON shape.
+- **[src/crisis_agents/README.md](src/crisis_agents/README.md)** — the AI-agent coordination layer: pragmatic overview, threat model, modules, build/run/test, live Claude mode.
+- **[src/crisis_agents/DESIGN.md](src/crisis_agents/DESIGN.md)** — formal design reference for the agent layer: invariants (no chokepoint, no clock), proof sketches, the chain-constraint trap, quorum derivation, termination, failure-mode analysis, tests-as-invariants table.
- **[CrisisViz/README.md](CrisisViz/README.md)** — Swift-side guide: serial-timeline pattern, testbed outputs, controls, cast convention.
- **[CrisisViz/HANDOFF.md](CrisisViz/HANDOFF.md)** — engineering log for the next coding agent.
diff --git a/src/crisis_agents/DESIGN.md b/src/crisis_agents/DESIGN.md
new file mode 100644
index 0000000..88acf58
--- /dev/null
+++ b/src/crisis_agents/DESIGN.md
@@ -0,0 +1,355 @@
+# DESIGN — `crisis_agents`
+
+> **Audience.** Engineers and curriculum authors who need to *reason about whether the design is correct*, not just run it. The [README](README.md) is the lobby; this is the reference. Where the README walks you through a scenario, this document states invariants and argues them.
+
+## Abstract
+
+We formalize the design of `crisis_agents`, the AI-agent coordination layer built on the Crisis consensus protocol. We state two invariants the design enforces — **no chokepoint** ($\S 2$) and **no clock** ($\S 1$) — and argue them from the protocol's primitives. We give a structural definition of byzantine equivocation ($\S 3$) and show it is detectable from any honest agent's vantage. We identify the chain-constraint trap that our first gossip-propagation attempt hit and explain why the byzantine's "introduction" emission is structurally necessary ($\S 4$). We derive the alarm-ratification quorum threshold $q = \lceil 2N/3 \rceil$ from the standard BFT bound ($\S 5$), argue termination of the asynchronous event loop ($\S 6$), explain why an `AlarmClaim` is cryptographically signed for free by being an ordinary Crisis message ($\S 7$), enumerate failure modes ($\S 8$), discuss the design space we chose from ($\S 9$), and map every invariant to the test file that enforces it ($\S 10$).
+
+---
+
+## 0. Notation and preliminaries
+
+| Symbol | Meaning |
+|---|---|
+| $G = (V, E)$ | A Lamport graph: directed acyclic graph of vertices |
+| $v$ | A vertex; wraps a `Message` plus locally-computed fields |
+| $v.\text{id}$ | The vertex's stable virtual process id (32 bytes) |
+| $H(m)$ | Cryptographic digest of message $m$ (random-oracle model) |
+| $v_1 \preceq v_2$ | $v_1$ happens before $v_2$ (timelike, $v_2 \in \text{future}(v_1)$) |
+| $v_1 \mathbin{\\|} v_2$ | $v_1$ and $v_2$ are spacelike: $\neg(v_1 \preceq v_2) \wedge \neg(v_2 \preceq v_1)$ |
+| $V_a$ | The vertex set of agent $a$'s `LamportGraph` |
+| $\text{past}(v)$ | The set of all vertices $v' \preceq v$ |
+| $N$ | Total number of agents in the boundary after `open_boundary()` |
+| $f$ | Maximum number of byzantine agents the network tolerates |
+| $q$ | Quorum threshold for alarm ratification |
+| $w(v)$ | Vertex weight (proof-of-work) |
+| $A_h, A_b$ | The honest and byzantine subsets of agents |
+
+The agent layer reuses the protocol primitives directly: `LamportGraph` from `crisis.graph`, `Message`/`Vertex` from `crisis.message`, and the core detection primitive `LamportGraph.find_mutations` from `crisis.graph`. Paper references throughout cite [Crisis (Richter, 2019)](../../Crisis.mirco-richter-2019.pdf).
+
+---
+
+## 1. The asynchronicity model
+
+### 1.1 What the protocol assumes
+
+Crisis assumes a **fully asynchronous unstructured P2P network** (paper, §4 and §5.9): no upper bound on message delivery time, no synchronized clocks, no central coordinator. The agent layer inherits the assumption.
+
+### 1.2 What synchronicity exists
+
+The only synchronicity in Crisis is **virtual** — derived inside the consensus algorithm from the DAG's causal structure. The round number $r(v)$ assigned to vertex $v$ by `crisis.rounds.compute_rounds` is a function of $\text{past}(v)$ and the proof-of-work weights it accumulates; **nothing about wall-clock time enters**.
+
+The agent layer does not invoke `compute_rounds` because it only needs mutation detection (a graph property, not a round property). The principle nonetheless applies: nothing externally synchronous is allowed.
+
+### 1.3 The driver loop, formally
+
+```
+run_until_quiescent(max_steps):
+ step ← 0
+ repeat:
+ progress ← false
+ for each agent a:
+ if a.try_emit() produces emissions:
+ route_emission(...); progress ← true
+ if run_gossip_round() produces transfers:
+ progress ← true
+ for each agent a:
+ if a.pending_alarm_claims() produces claims:
+ broadcast_alarm(...); progress ← true
+ step ← step + 1
+ until not progress or step ≥ max_steps
+```
+
+Three properties matter:
+
+- **No turn argument is exposed to agents.** `CrisisAgent.try_emit()` has signature `(self) → list[AgentTurn]`. Agents in an asynchronous network do not observe a global tick.
+- **The order (emission → gossip → alarm) is one specific scheduler choice.** Other valid schedulers (random, priority-based, agent-driven) would also be correct. The protocol does not depend on this ordering — it depends only on each step *eventually* happening.
+- **Termination is by quiescence, not by step count.** `max_steps` is a safety bound. $\S 6$ argues termination formally.
+
+### 1.4 Relationship to the paper's §5.9
+
+The paper describes Crisis as "infinite parallel loops" running concurrently on every node: gossip, message generation, consensus. Our in-process driver is the single-process analog: instead of $N$ event loops running on $N$ machines, we have one event loop that cycles through $N$ in-memory agents. The interleaving is different; the semantic content is the same.
+
+A future deployment over `crisis.gossip.GossipServer` replaces the in-process loop with $N$ independent agent loops, with no agent-layer code change.
+
+---
+
+## 2. The chokepoint principle
+
+### 2.1 Definition
+
+Let $O$ be an entity in the network. $O$ is a **chokepoint** for byzantine detection iff
+
+$$\big[\text{network can detect}\big] \;\Longrightarrow\; \big[O \text{ holds state inaccessible to honest agents}\big].$$
+
+Equivalently: removing $O$ would prevent detection. A protocol with chokepoints has single points of failure even if those points are not themselves byzantine.
+
+### 2.2 Claim
+
+Our design contains no chokepoint. The mothership is a bootstrap and scheduler; it holds no state that honest agents do not also hold in the limit of eventual gossip consistency.
+
+### 2.3 Proof sketch
+
+**Setup.** Let $A = A_h \cup A_b$ with $|A| = N$ and $|A_b| = f < N/3$. Let the byzantine $b \in A_b$ emit a forking pair $v_1, v_2 \in V$ with $v_1.\text{id} = v_2.\text{id} = b.\text{id}$ and $v_1 \mathbin{\\|} v_2$. By the byzantine's emission script there exist non-empty disjoint $T_1, T_2 \subseteq A$ such that $v_1$ is initially delivered to $T_1$ and $v_2$ to $T_2$.
+
+**Lemma (eventual consistency of gossip).** For any honest agent $a \in A_h$ and any vertex $v \in V$ that exists somewhere in the network, there is a finite gossip schedule after which $v \in V_a$, provided the chain-link prerequisite from $\S 4$ holds (the byzantine's intro vertex must exist in $a$'s graph first; our scenario ensures this).
+
+**Main argument.** By the lemma applied to $v_1$ and $v_2$, every $a \in A_h$ eventually has $\{v_1, v_2\} \subseteq V_a$. The past relation in $V_a$ is monotone under graph extension — adding vertices can only enlarge $\text{past}(v)$, never shrink it. Since $v_1 \mathbin{\\|} v_2$ holds globally (neither was delivered with knowledge of the other), it holds in every $V_a$. Therefore
+
+$$\forall a \in A_h:\quad \{v_1, v_2\} \in \texttt{a.graph.find\_mutations}(b.\text{id}).$$
+
+**Conclusion.** Every honest agent independently detects the equivocation from its own vantage. No privileged observer is required. ∎
+
+### 2.4 What the mothership actually does
+
+The mothership has two roles, both unprivileged:
+
+- **Bootstrap.** Knows the initial member set; introduces a joiner via `open_boundary`. Bootstrap is unavoidable in any P2P system — you must know at least one peer to begin.
+- **Scheduler.** Runs the event loop. In our PoC this is in-process for testability; in a deployed system, each agent runs its own loop and the mothership disappears.
+
+Neither role reads any agent's internal state. The regression test `test_no_chokepoint_attribute_on_mothership` asserts the mothership exposes no `all_graphs`, `graph_of`, `_graphs`, or `scan_for_mutations` attribute — a sentinel against re-introducing the chokepoint.
+
+---
+
+## 3. Equivocation as a structural DAG property
+
+### 3.1 Definition (paper, Definition 4.2)
+
+Two vertices $v_1, v_2 \in V$ in a Lamport graph $G$ are a **mutation** of a virtual process iff
+
+$$v_1.\text{id} = v_2.\text{id} \quad \wedge \quad v_1 \mathbin{\\|} v_2.$$
+
+That is, they share an emitter id but are causally incomparable: each was emitted without acknowledging the other.
+
+### 3.2 Why this is byzantine
+
+A correct emitter maintains a **single chain**: each new message references its prior same-id message via `digests`. The chain forms a path in $G$, so any two vertices from an honest emitter are timelike — one $\preceq$ the other.
+
+A byzantine intentionally forks: it emits two messages neither referencing the other, dispatched to disjoint peer subsets $T_1, T_2$. Each receiver, seeing only one variant, accepts it. After gossip cross-pollinates, the full DAG reveals the fork as a same-id spacelike pair.
+
+### 3.3 Why detection needs no consensus
+
+Equivocation is **structural** — a property of the DAG that any process with the relevant vertices can verify by direct examination. `LamportGraph.find_mutations(id)` returns the answer deterministically; no voting is required.
+
+Consensus (the paper's BBA-based virtual leader election) is needed for *agreement on which value is canonical* — a fundamentally different problem. The agent layer never invokes `compute_safe_voting_pattern` or `compute_virtual_leader_election` because detection of *who lied* is strictly cheaper than agreement on *what is true*.
+
+---
+
+## 4. The chain-constraint trap
+
+### 4.1 What went wrong in attempt 1
+
+First design: the byzantine emits variant $v_A$ (delivered to $T_1$) and $v_B$ (to $T_2$), both with empty `digests`. Gossip then tries to propagate $v_B$ to agents in $T_1$ who already have $v_A$.
+
+This **fails** at `message_integrity` step 6 (paper, §4.2, Algorithm 2):
+
+> If there is a vertex $v$ in $G$ with $v.\text{id} = m.\text{id}$, one of $m.\text{digests}$ must reference $v$ (or a vertex in $v$'s past).
+
+For $a \in T_1$ already holding $v_A$: $a$'s graph contains a vertex with $v_B.\text{id}$. The new message $v_B$ must reference *some* vertex of that id — but $v_B.\text{digests} = \emptyset$. Rejected. Equivocation cannot propagate via gossip.
+
+### 4.2 The fix: an introduction vertex
+
+The byzantine first broadcasts a benign **introduction** $v_\text{intro}$ with $v_\text{intro}.\text{id} = b.\text{id}$. After gossip, $v_\text{intro} \in V_a$ for every $a \in A_h$.
+
+The byzantine's two equivocating variants then both chain to $v_\text{intro}$:
+
+$$H(v_\text{intro}) \in v_A.\text{digests} \quad \wedge \quad H(v_\text{intro}) \in v_B.\text{digests}.$$
+
+Now when $v_B$ tries to extend $a$'s graph (with $v_A, v_\text{intro} \in V_a$): $v_B$ references $v_\text{intro}$, which is in $V_a$ and has the right id. Step 6 satisfied. Accepted.
+
+### 4.3 The structural picture
+
+```mermaid
+flowchart TD
+ intro["v_intro
id = byz
broadcast to all"]
+ vA["v_A
id = byz
delivered to T₁"]
+ vB["v_B
id = byz
delivered to T₂"]
+ intro --> vA
+ intro --> vB
+
+ classDef byz fill:#fce5cd,stroke:#cc4125
+ class intro,vA,vB byz
+```
+
+$v_A$ and $v_B$ are siblings under $v_\text{intro}$. Neither references the other. Therefore $v_A \mathbin{\\|} v_B$ in every graph that holds both. `find_mutations(b.id)` returns $\{v_A, v_B\}$.
+
+### 4.4 Why this isn't a design wart
+
+A real-world byzantine has the same constraint and the same workaround: it must establish presence in the network before it can equivocate, because equivocation requires the network to already know its id. In a deployed network the "introduction" is just the byzantine's first honest-looking emission. We model it explicitly in the scenario for legibility — it lets the reader see the fork pattern cleanly.
+
+---
+
+## 5. Quorum threshold derivation
+
+### 5.1 The BFT bound
+
+We assume up to $f$ byzantine agents out of $N$ with $f < N/3$. This is the classical Lamport bound for asynchronous BFT; the paper's §6 proves Crisis tolerates exactly this.
+
+### 5.2 Choosing $q$
+
+For the alarm-voting layer we need a quorum size $q$ satisfying two constraints.
+
+**Safety.** Any ratified alarm must reflect honest consensus, not byzantine collusion. If $q \leq f$, then the $f$ byzantines could alone ratify any false alarm. So $q > f$. Stronger: to ensure any two valid quorums overlap in at least one honest signer (and therefore cannot disagree), we require
+
+$$q \geq 2f + 1.$$
+
+**Liveness.** Honest agents alone must be able to reach quorum — otherwise the protocol cannot ratify even valid alarms. So
+
+$$q \leq N - f.$$
+
+The two constraints are simultaneously satisfiable iff $2f + 1 \leq N - f \iff 3f + 1 \leq N \iff f < N/3$, which is exactly the BFT bound.
+
+### 5.3 The chosen form
+
+We pick
+
+$$q = \left\lceil \frac{2N}{3} \right\rceil.$$
+
+For $N$ divisible by $3$ this equals $2f + 1$ (the smallest safe choice). For other $N$ it is one greater than strictly necessary — slightly conservative, but uniform and easy to remember.
+
+### 5.4 Worked example: $N = 4, f = 1$
+
+$$q = \lceil 8/3 \rceil = 3.$$
+
+Implications:
+
+- A single byzantine acting alone cannot ratify ($1 < 3$).
+- All three honest agents must concur — which by $\S 2$ they do, because each independently detects the same equivocation.
+- One byzantine + one duped honest agent ($2 < 3$) still cannot ratify, which is the desired property: the honest agent's "dupe" status is irrelevant once the byzantine's lie is structurally visible.
+
+---
+
+## 6. Termination of the event loop
+
+### 6.1 Claim
+
+`Mothership.run_until_quiescent` terminates with `QuiescenceReport.reached_quiescence = True` for every well-formed scenario (finite agent scripts, finite byzantine emission set).
+
+### 6.2 Proof
+
+Define a **monotone progress measure**: let $\mathcal{D}(s)$ be the union, over all agents, of message digests in their graphs *and* the union of alarm-keys in their `_already_alarmed` sets after step $s$:
+
+$$\mathcal{D}(s) = \bigcup_{a \in A} \big( \{H(m) : m \in V_a \} \cup \{k : k \in a.\text{\_already\_alarmed}\} \big).$$
+
+**Boundedness.** $\mathcal{D}(s)$ is bounded above by the total set of emissions the agent scripts can produce (finite by assumption) plus the set of distinct AlarmClaim payloads (bounded by the number of mutations, also finite).
+
+**Monotonicity.** $\mathcal{D}(s+1) \supseteq \mathcal{D}(s)$. Each loop body either adds a new vertex digest to some agent's graph (emission, gossip-acceptance, or alarm receive), adds an alarm-key to some agent's `_already_alarmed`, or does nothing.
+
+**Strict growth on progress.** If a loop iteration sets `progress ← true`, at least one of the operations was non-trivial: an emission was routed (new digest), a gossip pair transferred (new digest at receiver), or an alarm was emitted (new alarm-key at sender + new digest at receivers). In every case $|\mathcal{D}(s+1)| > |\mathcal{D}(s)|$.
+
+**Conclusion.** $|\mathcal{D}|$ strictly increases on each progress step and is bounded above. So progress steps are finite. The first step with no progress sets the loop's exit condition. ∎
+
+### 6.3 Liveness
+
+In our test scenarios the loop terminates in 3–7 steps. The `max_steps=200` cap is two orders of magnitude above what is needed. `QuiescenceReport.reached_quiescence` distinguishes natural termination from a cap-out.
+
+---
+
+## 7. AlarmClaim as a first-class Crisis payload
+
+### 7.1 No new protocol
+
+An `AlarmClaim` is a JSON payload distinguished only by `kind = "alarm"`. It is wrapped into an ordinary Crisis `Message` via the agent's `_build_message` machinery — same chain-link logic, same cross-reference logic, same PoW nonce mining. It then enters the gossip layer like any other vertex.
+
+### 7.2 Why this gives us cryptographic signing for free
+
+Any recipient who has the AlarmClaim's `Message` can:
+
+1. Recompute $H(\text{message})$ and verify it matches the claimed digest.
+2. Verify the nonce satisfies the network's PoW threshold.
+3. Read `message.id` to learn which process emitted it.
+
+The process_id is a stable cryptographic identifier (derived as $\text{digest}(\text{name})[:32]$). The PoW nonce is unforgeable in the random-oracle model. Therefore an AlarmClaim is cryptographically attributable to its emitter **without any separate identity PKI**.
+
+### 7.3 Quorum over signed claims
+
+`tally_alarms(graph, threshold)` groups vertices by `(accused, statement_id, witness_pair)` and counts unique signer process_ids. Because signers are cryptographically attributed, a byzantine cannot forge another agent's signature. The count is therefore a faithful count of *independent honest detectors who agree*, which is exactly what the quorum threshold requires.
+
+### 7.4 Canonical witness pairs
+
+For two detectors to "agree" on the same equivocation, they must produce identical AlarmClaim payloads. We canonicalize:
+
+- `witness_digests` is always a sorted hex tuple — `tuple(sorted([d1, d2]))`. Two detectors observing the same fork therefore emit byte-identical witness pairs, which `tally_alarms` keys on.
+
+This canonicalization happens in `LamportGraph.find_mutations` callers (`detect_mutations_in_graph` in `alarm.py`) so it cannot be bypassed by a careless subclass.
+
+---
+
+## 8. Failure-mode analysis
+
+| Scenario | Outcome |
+|---|---|
+| Byzantine equivocates; all honest agents see both variants via gossip | Every honest agent detects; quorum met; alarm ratified. **Correct.** |
+| Byzantine equivocates; gossip is partial (one honest agent sees only $v_A$) | Partial-view agent does not detect. Remaining detectors must alone meet $q$; if they do not, alarm sits un-ratified. **Correct conservative outcome** — no false ratification. |
+| Byzantine emits false `AlarmClaim` against an honest agent | No honest agent seconds it (their graphs do not contain the alleged equivocation). Count $= 1 < q$. **Not ratified.** |
+| Two colluding byzantines attempt to ratify a false alarm | Requires $2 \geq q = \lceil 2N/3 \rceil$, i.e. $N \leq 3$. Outside our threat model ($f < N/3$ requires $N \geq 4$). |
+| Byzantine never emits anything | No alarm to detect. Network proceeds normally. |
+| Byzantine emits intro but no equivocation | Network treats it as a benign new member. |
+| Honest agent equivocates due to a bug | Detection mechanism fires regardless. This is correct: equivocation is byzantine *whether intentional or not*, and a byzantine-shaped vertex pair must be flagged so honest agents can react. |
+| Gossip never reaches some honest agent (partition) | No detection from the isolated agent. As soon as the partition heals, gossip catches it up and detection fires. |
+
+---
+
+## 9. Trade-offs and what we didn't build
+
+### 9.1 Quorum-count vs. full BBA voting
+
+The paper's full virtual leader election (Algorithm 7) achieves agreement on a *value*. Our alarm domain is different: we need agreement on *who lied*, not on what the truth is. Equivocation is binary — either the fork exists in the DAG or it does not — so a simple count of cryptographically-signed independent observations suffices.
+
+Cost difference is dramatic. We measured BBA convergence at $\text{pow\\_zeros}=1, \text{steps}=80, N=7$ in pure Python: minutes. Quorum-count over the same data: microseconds.
+
+If a future scenario needs value-agreement (e.g., agreeing on which of two contradictory facts is canonical), the full BBA pipeline from `crisis.voting` is available and unchanged — it would be invoked on the application-layer payload, not on alarm claims.
+
+### 9.2 In-process gossip vs. TCP
+
+`crisis.gossip.GossipServer` exists and works over real sockets. We use in-process function calls because:
+
+- Co-located agents (Claude sub-agents in one Python process)
+- Determinism for tests
+- Network reliability is a separate concern
+
+A future deployment swaps in `GossipServer`; no `crisis_agents` code changes.
+
+### 9.3 No second-order detection
+
+If a byzantine emits a false `AlarmClaim`, the quorum threshold prevents ratification. We do not recursively raise a second-order alarm against the false-accuser. Doing so would be a stronger result — "we identified the lying accuser" — but is not necessary for correctness. The quorum unblock-by-default behavior is the necessary invariant.
+
+### 9.4 No visualization
+
+CrisisViz visualizes the protocol PoC's `crisis_data.json`, which comes from `crisis.demo.Simulation`. A future CrisisViz chapter set could absorb agent-coordination runs (multi-DAG rendering, gossip propagation, alarm-vote convergence) but would require new visual idioms. Out of scope for this PoC.
+
+---
+
+## 10. Tests as invariants
+
+Each row maps an invariant claimed in this document to the test file that enforces it. If you weaken any invariant, at least one of these tests must fail.
+
+| Invariant | Section | Test file → assertion |
+|---|---|---|
+| No chokepoint — honest agents agree | $\S 2$ | `test_no_chokepoint.py::test_all_honest_agents_agree_on_ratified_alarms` |
+| No privileged state on mothership | $\S 2.4$ | `test_no_chokepoint.py::test_no_chokepoint_attribute_on_mothership` |
+| Single byzantine accuser cannot ratify | $\S 8$ | `test_no_chokepoint.py::test_byzantine_alone_cannot_ratify` |
+| No clock — agents see no turn argument | $\S 1.3$ | `test_async_quiescence.py::test_no_turn_argument_exposed_to_agents` |
+| Local sequence numbers, not global clock | $\S 1.3$ | `test_async_quiescence.py::test_no_turn_field_on_alarmclaim` |
+| Loop terminates | $\S 6$ | `test_async_quiescence.py::test_run_until_quiescent_terminates` |
+| Two runs converge identically | $\S 1.3, \S 6$ | `test_async_quiescence.py::test_two_runs_produce_identical_final_state` |
+| Async loop alone ratifies | $\S 1.3$ | `test_async_quiescence.py::test_alarms_propagate_through_async_loop_alone` |
+| Decentralized detection | $\S 2.3, \S 3$ | `test_alarm.py::test_each_honest_agent_detects_the_same_mutation` |
+| Canonical witness pairs | $\S 7.4$ | `test_alarm.py::test_all_honest_detectors_produce_canonical_witness_pairs` |
+| Byzantine doesn't accuse itself | $\S 3$ | `test_alarm.py::test_byzantine_does_not_detect_its_own_equivocation` |
+| Chain-link propagation via intro | $\S 4$ | `test_mothership.py::test_gossip_propagates_byzantine_equivocation` |
+| Quorum formula | $\S 5.3$ | `test_vote.py::test_quorum_formulas` |
+| Quorum met by 3 honest signers (N=4) | $\S 5.4$ | `test_vote.py::test_tally_meets_quorum` |
+| Quorum blocks single signer | $\S 5.2$ | `test_vote.py::test_tally_blocks_single_signer` |
+| Proof self-consistency catches tampering | $\S 7$ | `test_proof.py::TestSelfConsistentVerification` (whole class) |
+
+The two **sentinel files** — `test_no_chokepoint.py` and `test_async_quiescence.py` — exist specifically to fail loudly if anyone reintroduces a chokepoint or a clock. Treat them as part of the design, not the test suite.
+
+---
+
+## Pointers
+
+- [README](README.md) — pragmatic overview, build/run/test, demo
+- [Parent README](../../README.md) — full repo architecture
+- [Paper](../../Crisis.mirco-richter-2019.pdf) — Mirco Richter, _Crisis: Probabilistically Self Organizing Total Order in Unstructured P2P Networks_, 2019
diff --git a/src/crisis_agents/README.md b/src/crisis_agents/README.md
index 266fe0c..212c821 100644
--- a/src/crisis_agents/README.md
+++ b/src/crisis_agents/README.md
@@ -2,63 +2,25 @@
A Python package that lifts the Crisis consensus protocol from "consensus between machines" to "consensus between AI agents." Each participant is a Crisis node with its own Lamport graph; the network catches byzantine equivocation via decentralized detection and quorum-ratified alarms. The engine is **asynchronous** and **event-driven** — no global clock, no privileged observer.
-> If you're new to this repo, start at the [parent README](../../README.md). This document is the architectural reference for the agent layer.
+> **For the formal design** — invariants, proofs, derivations, failure modes, tests-as-invariants — see **[DESIGN.md](DESIGN.md)**. This README is the lobby; that document is the reference.
+>
+> For repo-wide orientation see the **[parent README](../../README.md)**.
---
## Threat model
-The setting is a small team of AI agents (Claude sub-agents, in our live demo) coordinated by an orchestrator we call the **mothership**.
+A small team of AI agents is coordinated by an orchestrator we call the **mothership**.
-- **Normal life** — the team is closed. Agents talk freely with each other and the mothership. No Crisis layer; the conversation is the medium.
-- **Boundary opens** — an external agent of unknown trust joins. Its internal motivation may diverge from the team's task. It may equivocate — telling one peer one thing while telling another peer the opposite — to mislead the network.
-- **Crisis to the rescue** — from the moment the boundary opens, every claim is wrapped into a Crisis Message with the emitting agent's stable process_id and a PoW nonce. The per-agent Lamport DAG is the immutable, replayable ledger. Mutation detection (built on `LamportGraph.find_mutations` from the protocol layer) catches equivocation. Every honest agent who has gossiped enough to see both contradictory variants raises an alarm. A quorum of independent alarms produces a network-ratified proof of malfeasance.
+- **Normal life** — the team is closed; agents talk directly with the mothership and each other. No Crisis layer needed.
+- **Boundary opens** — an external agent of unknown trust joins. It may equivocate — telling one peer one thing while telling another peer the opposite — to mislead the network.
+- **Crisis to the rescue** — from the moment the boundary opens, every claim is wrapped into a Crisis message with the emitter's stable process id and a PoW nonce. The per-agent Lamport DAG is the immutable, replayable ledger. Mutation detection catches equivocation; a quorum of independent detectors ratifies a multi-signer proof of malfeasance.
-What's deliberately **not** in scope (this is a PoC):
-
-- Visualization. The CrisisViz application is a separate effort that visualizes the protocol PoC; visualizing an agent-coordination run would require a substantial new chapter set there.
-- Real TCP gossip. Agents talk via in-process function calls in the mothership process. The existing `crisis.gossip.GossipServer` shows how it would look across sockets.
-- Detection of *false claims that aren't equivocations*. An agent who consistently lies but never equivocates is out-voted, not "caught." Catching it would require a ground-truth oracle, which is application-layer, not protocol-layer.
+The headline architectural commitments — **no chokepoint**, **no clock** — are stated and argued formally in [DESIGN.md §2 and §1](DESIGN.md). Both are guarded by sentinel test files (`test_no_chokepoint.py`, `test_async_quiescence.py`).
---
-## Two architectural principles, enforced by tests
-
-### 1. No chokepoint
-
-Every honest agent maintains **its own** `LamportGraph`. The mothership does NOT hold a privileged graph of the whole network. Detection runs on each agent independently; alarms are emitted by each detector independently; proofs are signed by a quorum of detectors.
-
-The regression-test file `tests/test_no_chokepoint.py` asserts:
-
-- After the full lifecycle, every honest agent's *ratified-alarms set* is byte-identical to every other honest agent's.
-- The mothership does not expose `all_graphs`, `graph_of`, `_graphs`, or any other privileged collection.
-- A single byzantine accuser alone cannot ratify an alarm.
-
-### 2. No clock
-
-Crisis is supposed to work in asynchronous P2P networks. Any synchronicity in the protocol is *virtual* — derived inside the consensus algorithm from the causal structure of the Lamport graph — not imposed from outside by a coordinator.
-
-The driver loop is **event-driven and quiescence-terminated**, not turn-counted:
-
-```python
-def run_until_quiescent(max_steps=200):
- while progress:
- progress = False
- # 1. Any agent has something to emit? Let them speak.
- # 2. Any gossip pair has new info? Exchange.
- # 3. Any agent has detected a new mutation? Emit AlarmClaim.
-```
-
-`tests/test_async_quiescence.py` asserts:
-
-- `CrisisAgent.try_emit()` takes no `turn` argument.
-- `AlarmClaim` has no `detected_at_turn` field (the wall-clock-implying name); only `emitted_at_step`, which is a per-agent local sequence number.
-- Two runs of the same scenario produce identical end states (determinism — no hidden wall-time dependence).
-- The loop alone (no manual phase orchestration) ratifies an alarm.
-
----
-
-## The mental model
+## Architecture
```mermaid
flowchart TB
@@ -70,19 +32,16 @@ flowchart TB
Mom1 <--> A1
Mom1 <--> B1
Mom1 <--> C1
- A1 <--> B1
- B1 <--> C1
end
- Boundary{"BOUNDARY OPENS
agent_δ joins;
trust unknown"}
+ Boundary{"BOUNDARY OPENS
agent_δ joins"}
Closed --> Boundary --> Open
subgraph Open["🟡 Phase 2 — Crisis active, async event loop"]
- Mom2["mothership
(bootstrap + driver only)"]
- A2["agent_α
own LamportGraph
detect · alarm"]
- B2["agent_β
own LamportGraph
detect · alarm"]
- C2["agent_γ
own LamportGraph
detect · alarm"]
- D2["agent_δ ⚠
own LamportGraph
byzantine"]
+ A2["agent_α
own DAG · detect · alarm"]
+ B2["agent_β
own DAG · detect · alarm"]
+ C2["agent_γ
own DAG · detect · alarm"]
+ D2["agent_δ ⚠
own DAG · (byzantine)"]
D2 -. variant_A .-> A2
D2 -. variant_A .-> C2
@@ -90,20 +49,14 @@ flowchart TB
A2 <-. gossip .-> B2
B2 <-. gossip .-> C2
A2 <-. gossip .-> C2
- A2 -- alarm --> Mom2
- B2 -- alarm --> Mom2
- C2 -- alarm --> Mom2
end
- Open --> Quorum
- Quorum{"QUORUM VOTE
≥ ⌈2N/3⌉ honest signers
independently agree"}
- Quorum --> Proof
- Proof["📜 Multi-signer proof
signed JSON; replayable
schema_version=2"]
+ Open --> Quorum{"QUORUM
≥ ⌈2N/3⌉ honest signers"}
+ Quorum --> Proof["📜 Multi-signer proof
signed JSON"]
classDef closed fill:#d9ead3,stroke:#38761d
classDef boundary fill:#fff2cc,stroke:#bf9000
classDef open fill:#fce5cd,stroke:#cc4125
- classDef quorum fill:#cfe2f3,stroke:#2c5f8f
classDef proof fill:#ead1dc,stroke:#741b47
class Closed closed
class Boundary,Quorum boundary
@@ -111,162 +64,73 @@ flowchart TB
class Proof proof
```
----
-
-## Six-phase walkthrough (the `crisis-agents demo`)
-
-The canonical scenario is `scenarios/fact_check.py`: three honest agents and one byzantine adjudicate six factual statements about a small reference document.
-
-### Phase 1 — closed team, no Crisis
-The mothership drives `run_closed_phase()` until quiescent. Each honest agent emits its six fact-check claims via plain function calls — appended to a flat log. Per-agent LamportGraphs aren't yet allocated. **No Crisis overhead.**
-
-### Phase 2 — boundary opens
-`mothership.open_boundary(agent_delta)`. Atomically: δ is added to the trust set, a fresh `LamportGraph` is created on every agent (including δ), and `boundary.is_open` flips to `True`.
-
-### Phase 3 — asynchronous event loop
-`mothership.run_until_quiescent()`. The driver cycles through:
-
-1. **Emission** — `agent.try_emit()` is called on each agent. Returned `AgentTurn`s are first-hop routed to their target subset (or broadcast). The byzantine emits an intro (broadcast), then a pair of contradictory variants (split delivery).
-2. **Gossip** — every ordered pair `(sender, receiver)` exchanges what `sender` has that `receiver` doesn't. Eventually-consistent propagation.
-3. **Alarm emission** — `agent.pending_alarm_claims()` runs `LamportGraph.find_mutations(...)` on each agent's own graph and produces `AlarmClaim`s for any newly observed equivocation. AlarmClaims are wrapped as Crisis Messages and broadcast.
-
-The loop exits when none of these three concerns make progress. `QuiescenceReport` (returned) carries: `steps`, `emissions`, `gossip_transfers`, `alarm_claims_emitted`, `reached_quiescence`.
-
-### Phase 4 — decentralized detection
-Each agent independently runs `detect_mutations()` on its own graph. In our scenario, every honest agent observes the byzantine's same-id spacelike pair and reports it. The byzantine doesn't accuse itself.
-
-### Phase 5 — ratification by quorum
-The quorum threshold is
-
-$$\text{quorum}(N) = \left\lceil \frac{2N}{3} \right\rceil$$
-
-where $N$ is the boundary size at ratification. For our scenario $N=4$ (3 honest + 1 byzantine), so the threshold is $\left\lceil 2 \cdot 4 / 3 \right\rceil = 3$ — every honest agent must concur. `tally_alarms(graph, threshold)` groups AlarmClaim vertices by `(accused, statement_id, witness_pair)`, counts unique signer process_ids per group, and ratifies groups meeting the threshold. **All honest agents produce identical `RatifiedAlarm` lists** (this is the no-chokepoint property in action).
-
-### Phase 6 — proof emission
-`build_proof(ratified_alarm)` produces a self-contained JSON document. Schema:
-
-```json
-{
- "schema_version": 2,
- "accused_process_id_hex": "...",
- "statement_id": "s03",
- "witness_digests": ["...", "..."],
- "signer_process_id_hexes": ["...", "...", "..."],
- "quorum_threshold": 3,
- "summary": "agent id=... emitted contradictory Crisis vertices about ..."
-}
-```
-
-`verify_proof_self_consistent(proof)` checks distinct witnesses, distinct signers, signer count ≥ threshold. Future Phase-6+ work: full replay verification that re-derives the alarm from a recorded simulation log.
+The mothership shrinks to **bootstrap + scheduler**. Detection runs on each agent's own LamportGraph; alarms gossip as ordinary Crisis messages; ratification is a per-agent tally of independent signers. See [DESIGN.md §1–§7](DESIGN.md) for the formal walkthrough.
---
-## Module reference
+## Modules
-| File | What it owns |
+| File | Role |
|---|---|
-| `claim.py` | `Claim` dataclass — the application-layer payload (verdict + evidence) |
+| `claim.py` | `Claim` payload — application-layer verdict + evidence |
| `boundary.py` | `Boundary` — trust set, `open()` trigger |
-| `agent.py` | `CrisisAgent` (abstract) + `MockAgent` + `MockByzantineAgent`. Each agent owns its `LamportGraph`, `emit_claim`, `receive`, `gossip_to`, `detect_mutations`, `pending_alarm_claims` |
+| `agent.py` | `CrisisAgent` (abstract) + `MockAgent` + `MockByzantineAgent` — each owns its `LamportGraph`, `emit_claim`, `receive`, `gossip_to`, `detect_mutations`, `pending_alarm_claims` |
| `live_agent.py` | `LiveClaudeAgent` — same interface, backed by real Anthropic API calls |
-| `mothership.py` | `Mothership` — bootstrap + async event-loop driver. No privileged graph state. `run_closed_phase()`, `run_until_quiescent()`, `ratified_alarms_from(name)` |
-| `alarm.py` | `LocalAlarm` + `detect_mutations_in_graph(graph, ...)` — pure function, runs on one agent's graph |
-| `vote.py` | `AlarmClaim` payload, `RatifiedAlarm`, `quorum_for(n)`, `tally_alarms(graph, threshold)` |
+| `mothership.py` | `Mothership` — bootstrap + async event-loop driver; `run_until_quiescent()`; `ratified_alarms_from(name)` |
+| `alarm.py` | `LocalAlarm` + `detect_mutations_in_graph(graph, ...)` — pure function on one agent's graph |
+| `vote.py` | `AlarmClaim` payload, `quorum_for(n) = ⌈2n/3⌉`, `tally_alarms`, `RatifiedAlarm` |
| `proof.py` | `ProofDocument` (schema v2), `build_proof`, `verify_proof_self_consistent` |
| `cli.py` | `crisis-agents demo` + `crisis-agents verify` |
-| `scenarios/fact_check.py` | The canonical demo scenario: reference doc, six statements, scripted agents |
+| `scenarios/fact_check.py` | The canonical demo scenario |
| `scenarios/reference_doc.txt` | The factual paragraph the demo adjudicates |
---
-## Reuse map from `src/crisis/`
-
-Almost all the heavy lifting comes from the protocol layer; `crisis_agents` is a thin adapter.
-
-| `src/crisis/` primitive | How `crisis_agents` uses it |
-|---|---|
-| `Message`, `Vertex` | Claims and AlarmClaims become `Message.payload`. Agent's stable id → `Message.id`. |
-| `LamportGraph` | One per agent. `extend()`, `find_mutations()`, `are_spacelike()` all reused. |
-| `LamportGraph.find_mutations(pid)` | The core of decentralized detection. Returns same-id spacelike groups. |
-| `ProofOfWorkWeight` + `mine_nonce()` | Each emission's PoW comes from here, with a shared weight system across the network so PoW is verifiable across graphs. |
-| `digest(name)[:ID_LENGTH]` | Agent process_id derivation. Same convention as `crisis.demo.Simulation` so agents could coexist with simulated nodes in a future mixed scenario. |
-
----
-
## Build · run · test
```sh
-# From repo root, after setup per INSTALL.md
cd /path/to/crisis
source .venv/bin/activate
-pip install -e ".[dev]" # editable install with pytest
+pip install -e ".[dev]"
-# All tests, including crisis_agents
-pytest -q # ~170 tests in 0.8s
+# Full test suite (includes crisis_agents)
+pytest -q # ~170 tests in ~0.8s
-# Just the agent layer
-pytest tests/test_claim.py tests/test_boundary.py tests/test_agent*.py \
- tests/test_mothership.py tests/test_alarm.py tests/test_vote.py \
- tests/test_proof.py tests/test_demo_fact_check.py \
- tests/test_no_chokepoint.py tests/test_async_quiescence.py -v
+# Mocked, deterministic demo
+crisis-agents demo --out-dir /tmp/demo
-# Run the demo (mocked, deterministic)
-crisis-agents demo --out-dir /tmp/crisis_demo
+# Verify the emitted proof
+crisis-agents verify /tmp/demo/proof_*.json
+```
-# Run with real Claude sub-agents (requires API key + extras)
+For real Claude sub-agents:
+
+```sh
pip install -e ".[live]"
export ANTHROPIC_API_KEY=sk-ant-...
crisis-agents demo --live --model claude-haiku-4-5-20251001
-
-# Verify a proof
-crisis-agents verify /tmp/crisis_demo/proof_*.json
```
----
+The byzantine stays scripted even in `--live` mode (reliable equivocation matters more than full LLM realism). See [DESIGN.md §9.4](DESIGN.md) for why.
-## The live-Claude path
-
-`LiveClaudeAgent` (in `live_agent.py`) makes one Anthropic Messages API call per `try_emit()` invocation, asking Claude to fact-check the scenario's statements against the reference document. The response is parsed as a JSON array of `Claim`-shaped objects; malformed responses degrade gracefully (the agent emits nothing rather than crashing).
-
-The byzantine joiner stays **mocked** even in `--live` mode: producing deterministic equivocation from an LLM requires multiple API calls per turn (one per peer subset) for unreliable yields, and the demo's narrative is cleaner with a scripted byzantine. The honest agents are the real LLM participants.
-
-Default model: `claude-haiku-4-5-20251001` (fast, cheap, plenty of capability for structured-output adjudication). Override with `--model`.
-
-The live path is intentionally not in CI — it costs API credits and has nondeterministic outputs.
-
----
-
-## Test taxonomy
-
-| Test file | What it asserts |
-|---|---|
-| `tests/test_claim.py` | Claim dataclass validation + JSON round-trip |
-| `tests/test_boundary.py` | Boundary state machine (closed → open) |
-| `tests/test_mothership.py` | Per-agent graph ownership; broadcast vs. targeted delivery; gossip propagation; no privileged attribute |
-| `tests/test_alarm.py` | Decentralized detection; every honest agent finds the same mutation; canonical witness pairs |
-| `tests/test_vote.py` | AlarmClaim round-trip; quorum formulas; tally determinism |
-| `tests/test_proof.py` | ProofDocument schema; JSON round-trip; tampered-witness/below-quorum rejection |
-| `tests/test_demo_fact_check.py` | End-to-end scenario produces one ratified alarm; CLI output contains all six phases |
-| `tests/test_live_agent.py` | LiveClaudeAgent parsing (fake Anthropic client; no real API calls) |
-| **`tests/test_no_chokepoint.py`** | **Centerpiece: every honest agent's ratified set is byte-identical; no privileged attributes exist** |
-| **`tests/test_async_quiescence.py`** | **Centerpiece: no clock; `try_emit()` takes no arg; `AlarmClaim.detected_at_turn` doesn't exist; two runs converge identically** |
-
-The two centerpiece files are sentinels — if you ever re-introduce a chokepoint or a wall clock, one of those tests should fail.
+Setup from scratch on a fresh macOS box: see [`../../INSTALL.md`](../../INSTALL.md).
---
## What's deliberately out of scope
-- **CrisisViz integration.** The visualizer's data file (`crisis_data.json`) is produced by `crisis.demo.Simulation`, not by `crisis_agents`. A future CrisisViz upgrade could absorb agent-coordination runs (multi-DAG rendering, gossip arrows, alarm-vote convergence) — but that's a separate effort, sketched in the parent README.
-- **Real TCP gossip.** In-process function calls only. Lifting to multi-process requires plugging into `crisis.gossip.GossipServer` — independent work.
-- **Cryptographic signatures beyond what Crisis already provides.** Crisis already provides nonces + message-digest chaining + PoW. Agent identity is `digest(name)[:32]`. We don't add a separate identity-PKI.
-- **Sybil resistance.** Threat model is "a few byzantine joiners with valid PoW", not "an attacker spawning unlimited identities." Sybil defense is what the PoW weight in Crisis is *for*; it's not the agent layer's concern.
-- **Byzantine false-accusations.** A byzantine could emit a false AlarmClaim against an honest agent. The quorum mechanism prevents ratification (honest agents won't second the false claim, so it stays at 1-of-N). Second-order detection of false accusers isn't in this PoC.
+- **Visualization.** CrisisViz visualizes the protocol PoC; absorbing agent runs would need new visual idioms. Separate effort.
+- **Real TCP gossip.** In-process function calls only. Lifting to multi-process plugs into `crisis.gossip.GossipServer` without `crisis_agents` code changes.
+- **Cryptographic signatures beyond Crisis itself.** Crisis already provides nonces + digests + PoW; agent identity is `digest(name)[:32]`. No separate PKI. See [DESIGN.md §7](DESIGN.md).
+- **Sybil resistance.** What PoW is for; not this layer's concern.
+- **Detection of false claims that aren't equivocations.** Out-voted, not "caught." Catching them would require a ground-truth oracle, which is application-layer.
+- **Second-order detection of false-accusers.** Quorum prevents ratification; second-order alarms are a stronger result we chose not to build. See [DESIGN.md §9.3](DESIGN.md).
---
## Pointers
-- Parent README: [`../../README.md`](../../README.md)
-- Install guide: [`../../INSTALL.md`](../../INSTALL.md)
-- The paper this is all based on: [`../../Crisis.mirco-richter-2019.pdf`](../../Crisis.mirco-richter-2019.pdf)
+- **[DESIGN.md](DESIGN.md)** — formal reference: invariants, proofs, the chain-constraint trap, quorum derivation, termination, failure-mode matrix, tests-as-invariants table
+- **[Parent README](../../README.md)** — full repo architecture
+- **[INSTALL.md](../../INSTALL.md)** — fresh-macOS install + demo guide
+- **[Paper](../../Crisis.mirco-richter-2019.pdf)** — Mirco Richter, _Crisis: Probabilistically Self Organizing Total Order in Unstructured P2P Networks_, 2019