sequenceDiagram
    participant Agent as Agent Process
    participant CM as get_context()
    participant Ctx as AsyncCodeModeContext
    participant Tracker as AgentReadTracker
    participant Doc as NotebookDocument
    participant Kernel

    Note over Agent,Kernel: Read-Before-Write Protection Flow

    Agent->>CM: get_context(skip_staleness_check=False)
    CM->>Ctx: NEW: create with AgentReadTracker ref
    Ctx->>Kernel: access kernel.agent.read_tracker

    alt Agent reads a cell via cells[...]
        Agent->>Ctx: nb.cells[cell_id].code
        Ctx->>Doc: get NotebookCell for cell_id
        Doc-->>Ctx: NotebookCell with version
        Ctx->>Tracker: record_read(cell_id, version)
        Ctx-->>Agent: NotebookCell.code
    end

    Note over Agent,Doc: edit_cell() with staleness check

    Agent->>Ctx: nb.edit_cell(target, code="new_code")
    Ctx->>Ctx: resolve target cell_id
    alt code is not None AND not skip_staleness_check AND cell not pending_add
        Ctx->>Doc: get(cell_id)
        Doc-->>Ctx: NotebookCell or None
        alt cell exists AND code.strip() non-empty
            Ctx->>Tracker: has_read(cell_id, current_version)
            alt has_read returns False
                Tracker->>Ctx: False
                Ctx-->>Agent: raise StaleCellError
                Note over Ctx: Includes stale_cells frozenset
            else has_read returns True
                Tracker->>Ctx: True
                Ctx->>Ctx: proceed with edit
            end
        else empty cell or cell not found
            Ctx->>Ctx: skip staleness check
        end
    end

    Note over Agent,Doc: Post-apply read recording for agent writes

    Ctx->>Doc: apply transaction (SetCode changes)
    Doc->>Doc: bump cell.version if code changed
    loop for each applied op
        alt op is AddOp or UpdateOp with code
            Ctx->>Doc: get_cell_version(written_id)
            Doc-->>Ctx: current version
            Ctx->>Tracker: record_read(written_id, current_version)
        end
    end

    Note over Agent,Doc: File-watch reload path

    alt File-watch triggers _replace_cells
        Doc->>Doc: _replace_cells(new_cells)
        Doc->>Doc: reconcile versions with prior state
        alt cell code unchanged
            Doc->>Doc: inherit prior version
        else cell code changed
            Doc->>Doc: bump version to prior + 1
        end
    end

    Note over Agent,Kernel: Error recovery

    alt StaleCellError raised
        Agent->>Agent: catch StaleCellError
        Agent->>Agent: re-read stale cells via cells[...]
        Agent->>Ctx: edit_cell() again (now has read)
        Note over Agent,Ctx: Fresh materialization records read
    end