docs/specification.md

@@ -25140,6 +25140,25 @@ Not every resource in the DAG is independently sandboxable — a file cannot be
 3. Multiple files in the same git checkout share one git_worktree sandbox.
 4. When a virtual resource has physical manifestations in **different sandbox domains** (e.g., a file in both a git-checkout domain and a container-instance domain), cross-mechanism coordination is needed at commit time (see Cross-Mechanism Write Coordination above).
 
+**Sandbox State Persistence:**
+
+Sandbox state (the mapping from `(plan_id, sandbox_boundary_id)` to the physical sandbox location, e.g., git worktree path) **must be persisted to the database**. This is required because `agents plan execute`, `agents plan diff`, and `agents plan apply` are separate CLI invocations — the sandbox created by `execute` must be discoverable by `diff` and `apply` in a subsequent process.
+
+The `SandboxManager` maintains an in-memory cache of active sandboxes keyed by `(plan_id, sandbox_boundary_id)`. On startup, it loads existing sandbox records from the database. On sandbox creation, it writes to both the cache and the database. On sandbox cleanup (after apply or rollback), it removes from both.
+
+The database schema includes a `v3_sandboxes` table:
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `id` | TEXT (ULID) | Primary key |
+| `plan_id` | TEXT | Foreign key to `v3_plans.plan_id` |
+| `sandbox_boundary_id` | TEXT | Resource ID of the sandbox boundary |
+| `strategy` | TEXT | Sandbox strategy (`git_worktree`, `copy_on_write`, etc.) |
+| `location` | TEXT | Physical location (worktree path, snapshot directory, etc.) |
+| `status` | TEXT | `active`, `committed`, `rolled_back`, `cleaned_up` |
+| `created_at` | DATETIME | Creation timestamp (UTC) |
+| `updated_at` | DATETIME | Last update timestamp (UTC) |
+
 **Dependency ordering for lifecycle operations:**
 
 | Operation | Traversal Direction | Rationale |
@@ -43848,10 +43867,10 @@ This section enumerates every technology choice in the CleverAgents stack, organ
 | Technology | Version | Role | Rationale |
 |---|---|---|---|
 | **LangChain** | >= 0.2.14 | LLM abstraction layer | Provider-agnostic interface for chat models, embeddings, output parsing, prompt templates, and tool calling. The `BaseLanguageModel` protocol enables swapping providers without changing application code. |
-| **LangGraph** | (transitive) | Stateful workflow orchestration | `StateGraph` with conditional edges, checkpointing (`MemorySaver`), and streaming execution. Used for the plan generation graph (`load_context -> analyze -> generate -> validate`) and auto-debug graph. |
+| **LangGraph** | (transitive) | Stateful workflow orchestration | `StateGraph` with conditional edges, checkpointing (`MemorySaver`), and streaming execution. Used for the plan generation graph (`load_context -> analyze -> generate -> validate`) and auto-debug graph. **State schemas passed to `StateGraph()` must be `TypedDict` subclasses** — not Pydantic `BaseModel`. LangGraph requires `TypedDict` for state merging semantics and reducer annotations (e.g., `Annotated[list, operator.add]`). Actor YAML-defined graphs compile to native `StateGraph` instances via `StateGraph.compile(checkpointer=MemorySaver())`. |
 | **LangChain Provider Packages** | varies | LLM provider integrations | `langchain-openai` (>= 0.2.0), `langchain-google-genai` (>= 0.2.0), `langchain-anthropic`, `langchain-groq`, `langchain-together`, `langchain-cohere`. Each provides a `ChatModel` implementation. |
 | **LangChain Community** | >= 0.2.14 | Community integrations | FAISS vector store, FakeListLLM/FakeEmbeddings for testing. |
-| **RxPY** | >= 3.2.0 | Reactive stream processing | `Subject`, `BehaviorSubject`, `ReplaySubject`, and operators (`map`, `filter`, `flat_map`, `debounce`, `throttle`, `scan`) for real-time event routing between actors, stream-to-graph bridging, and backpressure management. |
+| **RxPY** | >= 3.2.0 | Reactive stream processing | `Subject`, `BehaviorSubject`, `ReplaySubject`, and operators (`map`, `filter`, `flat_map`, `debounce`, `throttle`, `scan`) for **real-time event routing between actors** and stream-to-graph bridging. RxPY handles the messaging layer between actors — it is **not** used for graph node execution, which is handled exclusively by native LangGraph `StateGraph`. |
 | **MCP SDK** | >= 1.4.0 | Model Context Protocol | Client SDK for communicating with MCP servers. Enables CleverAgents to discover and invoke tools exposed by any MCP-compliant server. |
 
 #### Data and Persistence