# Cortex Agent Node: Workspace Mirroring & Real-time Sync

## 📌 Overview
This document outlines the architecture for the **Cortex Workspace Sync System**, designed to provide the AI with "Zero-latency Perception" of remote node files while maintaining high-fidelity synchronization across a collaborative agent mesh.

The core innovation is the **"Ghost Mirror" pattern**, where the Cortex Server maintains a local, hash-verified copy of the node's workspace to allow instantaneous AI analysis without gRPC round-trips for every file read.

---

## 🏗️ Core Concepts

### 1. The Session-Based Attachment
When a user begins an AI session, they can "Attach Nodes" to that specific execution context. 
- **Workspace Selection**: During attachment, the user chooses the **Source of Truth (SoT)** for the files.
- **Unique Identification**: Every sync folder in a node uses a session-specific UUID to prevent path collisions.

### 2. Dual Source-of-Truth Models

#### A. Server-Primary (The "Scratchpad" Model)
Used for new projects or AI-generated tasks.
- **Root**: A temporary or persistent directory on the Cortex Server.
- **Propagation**: On initialization, the server pushes the initial manifest and data to all attached nodes.
- **Lifecycle**: Node folders are "mirrors" of the server. Any code generated by the AI on the server is instantly pushed down to the nodes for execution.

#### B. Node-Primary (The "Local Codebase" Model)
Used for existing local repositories (e.g., a professional dev machine).
- **Root**: A specific local folder on one "Lead" Agent Node.
- **Mirroring**: The server pulls the initial state to create a local **Ghost Mirror**.
- **Change Detection**: The Lead Node uses OS-level watchers (`inotify`, `FSEvents`) to detect changes and stream deltas back to the server.
- **Propagation**: The server then broadcasts these changes to any other "Support" nodes attached to the session.

---

## 🚀 Technical Architecture

### 1. Change Detection & Reconciliation
- **Watcher-Driven Deltas**: Nodes stream `(File Path, Hash, ContentDelta)` messages via the gRPC `TaskStream` whenever local files change.
- **Hashed State Checks**: Before the AI begins a complex multi-file refactor, the server executes a quick "Fingerprint" check (comparing top-level directory hashes) to ensure the Ghost Mirror isn't drifting from the Node.

### 2. Efficiency & Large Data Handling
- **Cortex-Ignore**: Native support for `.cortexignore` (and inherited `.gitignore`) to block heavy assets (`node_modules`, `.git`, `.venv`).
- **Chunked Deduplication**: Using chunk-based transfer to only send binary changes, minimizing bandwidth during repeated refactors.

### 3. Conflict Resolution & Safety
- **Workspace Locking**: During AI "Write" operations, the target node's sync folder can be briefly locked to prevent concurrent manual edits from corrupting the refactor.
- **Deterministic Reconciliation**: If a conflict is detected (Node changed during AI planning), the server enters a **Reconcile Mode**, forcing a pull of the node state before retrying the edit.

---

## 🛠️ Implementation Phasing

### Phase 1: Ghost Mirror Foundations
- [x] Implement `FSMirror` service on the Orchestrator.
- [x] Implement basic gRPC `FileSync` messages in `agent.proto`.
- [x] support for `server-to-node` initial push.

### Phase 2: Active Watchers & Multi-Node Sync
- [x] Integrate local directory watchers on Agent Nodes.
- [x] Implement `node-to-server` delta streaming.
- [x] Multi-node propagation (Server broadcasts Lead Node updates to Support Nodes).

### Phase 3: Conflict Handling & Optimization
- [x] Implementation of `.cortexignore` and `.gitignore` filtering.
- [x] Workspace state locking and concurrency guards.
- [x] Dynamic reloading of ignore rules on change.

### Phase 4: Browser & Skill Integration
- [x] Integrate browser download handling into mirrored workspace.
- [x] Implement dynamic session mounting for agent skills (CWD sharing).

### Phase 5: Distributed Conflict Resolution & Resiliency
- [x] Implement incremental hash-based drift detection.
- [x] Finalize automatic drift recovery logic for reconnection.
