---
phase: 01-core-infrastructure
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - src/gsd_openclaw/__init__.py
  - src/gsd_openclaw/state_manager.py
  - tests/conftest.py
  - tests/test_state_manager.py
autonomous: true
requirements:
  - SESS-04
user_setup: []
must_haves:
  truths:
    - "State can be saved to JSON file atomically"
    - "State can be loaded from JSON file"
    - "Corrupted state falls back to backup automatically"
    - "State schema includes session metadata, tmux references, and activity stats"
  artifacts:
    - path: "src/gsd_openclaw/state_manager.py"
      provides: "State persistence with atomic writes"
      exports: ["SessionState", "StateManager", "save_state", "load_state"]
      min_lines: 80
    - path: "tests/test_state_manager.py"
      provides: "Test coverage for state operations"
      contains: "test_save_load_state"
  key_links:
    - from: "src/gsd_openclaw/state_manager.py"
      to: "~/gsd-workspaces/{project}/.gsd/state.json"
      via: "atomic write (tempfile + os.replace)"
      pattern: "tempfile\\.mkstemp.*os\\.replace"
---

<objective>
Implement state persistence layer with atomic writes and backup rotation for crash-safe session checkpointing.

Purpose: Provides the foundation for all session state management. Other components depend on this for storing and recovering session metadata.

Output: Working state_manager.py with atomic save, load with validation, and automatic backup rotation.
</objective>

<execution_context>
@/home/starmen1265/.claude/get-shit-done/workflows/execute-plan.md
@/home/starmen1265/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-core-infrastructure/01-CONTEXT.md
@.planning/phases/01-core-infrastructure/01-RESEARCH.md
@.planning/phases/01-core-infrastructure/01-VALIDATION.md
</context>

<interfaces>
<!-- Key interfaces from RESEARCH.md code examples -->

**SessionState dataclass:**
```python
@dataclass
class SessionState:
    schema_version: str = "1.0"
    session_id: str = ""
    project_name: str = ""
    tmux_session_name: str = ""
    tmux_pane_id: str = ""
    created_at: str = ""
    last_active_at: str = ""
    command_count: int = 0
    last_output_snapshot: Optional[str] = None
    display_name: Optional[str] = None
```

**Atomic write pattern:**
```python
def save_state(state: dict, state_path: Path) -> None:
    fd, temp_path = tempfile.mkstemp(dir=state_path.parent, suffix='.tmp')
    try:
        with os.fdopen(fd, 'w', encoding='utf-8') as f:
            json.dump(state, f, indent=2, ensure_ascii=False)
        os.replace(temp_path, state_path)
    except Exception:
        if os.path.exists(temp_path):
            os.unlink(temp_path)
        raise
```
</interfaces>

<tasks>

<task type="auto" tdd="true">
  <name>Task 1: Create state schema with dataclasses</name>
  <files>src/gsd_openclaw/__init__.py, src/gsd_openclaw/state_manager.py</files>
  <behavior>
    - Test 1: SessionState can be created with all fields
    - Test 2: SessionState.to_dict() returns complete dict
    - Test 3: SessionState.from_dict() reconstructs from dict
    - Test 4: SessionState ignores unknown fields in from_dict()
  </behavior>
  <action>
Create the SessionState dataclass with all fields from CONTEXT.md:
- schema_version (default "1.0")
- session_id, project_name, tmux_session_name, tmux_pane_id
- created_at, last_active_at (ISO format strings)
- command_count (int)
- last_output_snapshot, display_name (Optional[str])

Implement to_dict() using dataclasses.asdict() and from_dict() with field filtering.

Also create the package __init__.py with version and exports.

Do NOT add validation logic yet - that comes in Task 3.
  </action>
  <verify>
    <automated>pytest tests/test_state_manager.py::test_session_state_creation -x</automated>
    <automated>pytest tests/test_state_manager.py::test_session_state_serialization -x</automated>
  </verify>
  <done>SessionState dataclass exists with all fields, to_dict() and from_dict() methods work correctly</done>
</task>

<task type="auto" tdd="true">
  <name>Task 2: Implement atomic state save with backup rotation</name>
  <files>src/gsd_openclaw/state_manager.py, tests/test_state_manager.py</files>
  <behavior>
    - Test 1: save_state creates file atomically (temp file + rename)
    - Test 2: save_state creates parent directories if missing
    - Test 3: save_state rotates backup (state.json -> state.json.bak)
    - Test 4: save_state cleans up temp file on failure
    - Test 5: Temp file is created in same directory as target (for atomic rename)
  </behavior>
  <action>
Implement save_state(state: SessionState, state_path: Path) function:

1. Create parent directories with mkdir(parents=True, exist_ok=True)
2. If state_path exists, rotate backup:
   - Delete old state.json.bak if exists
   - Rename state_path to state.json.bak
3. Write to temp file using tempfile.mkstemp(dir=state_path.parent, suffix='.tmp')
4. Use os.fdopen to write JSON with indent=2, ensure_ascii=False
5. Atomic replace with os.replace(temp_path, state_path)
6. On exception, clean up temp file if it exists

Use the pattern from RESEARCH.md - this is the atomic write pattern proven to prevent corruption.

Do NOT use file locking - os.replace is atomic on POSIX systems.
  </action>
  <verify>
    <automated>pytest tests/test_state_manager.py::test_atomic_write -x</automated>
    <automated>pytest tests/test_state_manager.py::test_backup_rotation -x</automated>
  </verify>
  <done>State saves atomically, backup rotates correctly, temp files cleaned up on failure</done>
</task>

<task type="auto" tdd="true">
  <name>Task 3: Implement state load with validation and fallback</name>
  <files>src/gsd_openclaw/state_manager.py, tests/test_state_manager.py, tests/conftest.py</files>
  <behavior>
    - Test 1: load_state returns None for missing file
    - Test 2: load_state returns SessionState for valid file
    - Test 3: load_state raises ValueError for unsupported schema version
    - Test 4: load_state raises ValueError for missing required fields
    - Test 5: load_state falls back to backup when main file is corrupted (JSONDecodeError)
    - Test 6: load_state falls back to backup when validation fails
  </behavior>
  <action>
Implement load_state(state_path: Path) -> Optional[SessionState] function:

1. If state_path doesn't exist, try backup (state_path.with_suffix('.json.bak'))
2. If neither exists, return None
3. Read JSON with proper encoding (utf-8)
4. Validate:
   - schema_version == "1.0" (raise ValueError if not)
   - Required fields present: session_id, project_name, tmux_session_name
5. On JSONDecodeError or ValueError, try backup (if backup != state_path)
6. Return SessionState.from_dict(data)

Also create tests/conftest.py with pytest fixtures:
- tmp_state_dir fixture using pytest's tmp_path
- sample_state fixture returning a valid SessionState instance
  </action>
  <verify>
    <automated>pytest tests/test_state_manager.py::test_save_load_state -x</automated>
    <automated>pytest tests/test_state_manager.py::test_state_validation -x</automated>
    <automated>pytest tests/test_state_manager.py::test_backup_fallback -x</automated>
  </verify>
  <done>State loads with validation, corrupted files fall back to backup, missing files return None</done>
</task>

<task type="auto">
  <name>Task 4: Create StateManager class with workspace path resolution</name>
  <files>src/gsd_openclaw/state_manager.py, tests/test_state_manager.py</files>
  <behavior>
    - Test 1: StateManager.get_state_path returns correct path for project
    - Test 2: StateManager.save persists state to correct location
    - Test 3: StateManager.load retrieves state from correct location
  </behavior>
  <action>
Create StateManager class that encapsulates state operations:

```python
class StateManager:
    WORKSPACES_ROOT = Path.home() / "gsd-workspaces"

    def __init__(self, project_name: str):
        self.project_name = project_name
        self.workspace_path = self.WORKSPACES_ROOT / project_name
        self.state_path = self.workspace_path / ".gsd" / "state.json"

    def save(self, state: SessionState) -> None:
        save_state(state, self.state_path)

    def load(self) -> Optional[SessionState]:
        return load_state(self.state_path)

    def get_state_path(self) -> Path:
        return self.state_path
```

This provides a clean interface for other components to use state persistence without managing paths directly.
  </action>
  <verify>
    <automated>pytest tests/test_state_manager.py::test_state_manager_class -x</automated>
  </verify>
  <done>StateManager class provides clean interface for state persistence with correct workspace paths</done>
</task>

</tasks>

<verification>
Run full test suite to verify all state operations:
```bash
pytest tests/test_state_manager.py -v
```

All tests must pass. Coverage should include:
- Atomic write pattern
- Backup rotation
- Validation logic
- Fallback to backup
- StateManager convenience methods
</verification>

<success_criteria>
- SessionState dataclass with all required fields exists
- Atomic save_state function prevents corruption
- load_state validates schema and required fields
- Backup rotation works (state.json.bak)
- Corrupted files fall back to backup automatically
- StateManager class provides clean interface
- All tests pass: `pytest tests/test_state_manager.py -v`
</success_criteria>

<output>
After completion, create `.planning/phases/01-core-infrastructure/01-01-SUMMARY.md`
</output>