Fix race condition in task result caching and wire result streamer

README.md

@@ -155,6 +155,7 @@ For detailed documentation, see:
 - **[docs/](./docs/)** - Complete documentation
 - **[docs/coordinator/](./docs/coordinator/)** - Coordinator documentation
 - **[docs/worker/](./docs/worker/)** - Worker documentation
+- **[docs/local-backlog/e2e-test-proposal.md](./docs/local-backlog/e2e-test-proposal.md)** - E2E testing implementation
 
 ---
 

api/proto/v1/tools.proto

@@ -123,6 +123,23 @@ message PackageInfo {
   string location = 3;      // Installation location
 }
 
+// ============================================================================
+// Artifact Tool - Retrieve generated artifacts
+// ============================================================================
+
+message ArtifactGetRequest {
+  string artifact_id = 1;   // Artifact identifier to retrieve
+  map<string, string> metadata = 100;
+}
+
+message ArtifactGetResponse {
+  bytes data = 1;           // Artifact binary data
+  string artifact_id = 2;   // Artifact identifier
+  int64 size_bytes = 3;     // Size of artifact
+  string content_type = 4;  // MIME type (e.g., "application/zip")
+  map<string, string> metadata = 100;
+}
+
 // ============================================================================
 // Tool Request/Response Unions
 // Used in TaskAssignment and TaskStreamResult
@@ -136,6 +153,7 @@ message ToolRequest {
     FsListRequest fs_list = 4;
     RunPythonRequest run_python = 5;
     PkgInstallRequest pkg_install = 6;
+    ArtifactGetRequest artifact_get = 7;
   }
 }
 
@@ -147,5 +165,6 @@ message ToolResponse {
     FsListResponse fs_list = 4;
     RunPythonResponse run_python = 5;
     PkgInstallResponse pkg_install = 6;
+    ArtifactGetResponse artifact_get = 7;
   }
 }

docs/README.md

@@ -18,18 +18,18 @@ The Coordinator is the central MCP server that orchestrates code generation work
 - **[Deployment Guide](./coordinator/deployment.md)** - Docker, Kubernetes, and production deployment
 - **[Testing Guide](./coordinator/testing.md)** - Test strategies and coverage
 
-**Status:** ✅ Implemented (v0.1.0, 33.2% overall / 80%+ core logic coverage, 51 tests)
+**Status:** ✅ Implemented (v0.1.0, 80% overall coverage)
 
-### Worker (Coming Soon)
+### [Worker](./worker/)
 
 The Worker executes code generation tasks inside secure Python environments.
 
-- Architecture Overview - Component design and communication protocols
-- API Reference - gRPC/HTTP API documentation
-- Deployment Guide - Container configuration and Kubernetes manifests
-- Testing Guide - Unit and integration tests
+- **[Architecture Overview](./worker/README.md)** - Component design and communication protocols
+- **[API Reference](./worker/api-reference.md)** - gRPC/HTTP API documentation
+- **[Deployment Guide](./worker/deployment.md)** - Container configuration and Kubernetes manifests
+- **[Testing Guide](./worker/testing.md)** - Unit and integration tests
 
-**Status:** ⏳ Planned
+**Status:** ✅ Implemented (v0.1.0, 80% overall coverage)
 
 ### Builder Container (Coming Soon)
 
@@ -191,33 +191,41 @@ Multi-layered security approach:
 |------|-------------|-----------|
 | `echo` | Echo message (test tool) | `message: string` |
 | `fs.read` | Read file from workspace | `path: string` |
-| `fs.write` | Write file to workspace | `path: string, contents: string` |
+| `fs.write` | Write file to workspace | `path: string, content: string` |
+| `fs.list` | List files and directories | `path: string` (optional) |
+| `run.python` | Execute Python code or file | `code: string` or `file: string` |
+| `pkg.install` | Install Python packages | `packages: string` |
+| `artifact.get` | Retrieve generated artifact | `artifact_id: string` |
+| `task.get_result` | Get task result | `task_id: string` |
+| `task.get_status` | Get task status | `task_id: string` |
 
 ### Planned Tools
 
 | Tool | Description | Status |
 |------|-------------|--------|
-| `run.python` | Execute Python code | ⏳ Planned |
-| `pkg.install` | Install Python packages | ⏳ Planned |
 | `test.run` | Run test suites | ⏳ Planned |
 | `lint.check` | Run linters/type checkers | ⏳ Planned |
 | `git.clone` | Clone repository | ⏳ Planned |
 | `git.commit` | Commit changes | ⏳ Planned |
-| `artifact.create` | Build distributable packages | ⏳ Planned |
+| `artifact.list` | List session artifacts | ⏳ Planned |
+| `artifact.upload` | Upload artifact to storage | ⏳ Planned |
 
 ## 🔍 Component Status
 
 | Component | Version | Status | Description |
 |-----------|---------|--------|-------------|
-| Coordinator | v0.1.0 | ✅ Stable | Central orchestrator for session and task management |
-| Worker | v0.1.0 | ✅ Stable | Python code execution with venv isolation |
+| Coordinator | v0.1.0 | ✅ Stable | Central orchestrator for session and task management (80% coverage) |
+| Worker | v0.1.0 | ✅ Stable | Python code execution with venv isolation (80% coverage) |
 | Docker Compose | v0.1.0 | ✅ Stable | Multi-worker deployment with session distribution |
-| Integration Tests | v0.1.0 | ✅ Complete | Docker-based end-to-end testing |
+| Integration Tests | v0.1.0 | ✅ Complete | Docker-based end-to-end testing (see tests/e2e/) |
 | Kubernetes | - | ⏳ Planned | Production orchestration |
 
 ## 📊 Quality Metrics
 
+Current test coverage: **80%** (unit tests, excludes infrastructure code)
+
 All quality metrics are tracked in SonarQube:
+
 - **Test Coverage**: See [SonarQube Dashboard](https://sonarcloud.io/project/overview?id=AltairaLabs_CodeGen-MCP)
 - **Code Quality**: Automated analysis on every commit
 - **Security Scanning**: gosec + SonarQube security rules
@@ -226,7 +234,7 @@ All quality metrics are tracked in SonarQube:
 
 - **Linting**: 24+ golangci-lint rules enabled (`.golangci.yml`)
 - **Testing**: Automated unit + integration tests
-- **Coverage**: Excludes generated proto files and main.go entrypoints
+- **Coverage**: Excludes generated proto files, main.go entrypoints, and infrastructure code
 - **Integration**: Full Docker Compose e2e test suite
 
 ## 🛠️ Development
@@ -258,11 +266,14 @@ make docker-build
 make test
 
 # Run with coverage
-make test-coverage
+make coverage
 
 # Run linting
 make lint
 
+# Run full CI pipeline locally
+make ci
+
 # Run specific component tests
 go test -v ./internal/coordinator/...
 ```

docs/coordinator/api-reference.md

@@ -10,6 +10,7 @@ Complete reference for the Coordinator's internal APIs, types, and interfaces.
 ## Table of Contents
 
 - [MCP Server](#mcp-server)
+- [MCP Tools](#mcp-tools)
 - [Session Manager](#session-manager)
 - [Worker Client](#worker-client)
 - [Worker Lifecycle](#worker-lifecycle)
@@ -71,6 +72,217 @@ if err := server.Serve(); err != nil {
 }
 ```
 
+## MCP Tools
+
+The Coordinator exposes the following MCP tools to clients.
+
+### File System Tools
+
+#### `fs.read`
+
+Read a file from the session workspace.
+
+**Parameters:**
+- `path` (string, required) - Relative path to file within workspace
+
+**Returns:** File contents as text
+
+**Example:**
+```json
+{
+  "tool": "fs.read",
+  "arguments": {
+    "path": "src/main.py"
+  }
+}
+```
+
+#### `fs.write`
+
+Write contents to a file in the session workspace.
+
+**Parameters:**
+- `path` (string, required) - Relative path to file within workspace
+- `contents` (string, required) - File contents to write
+
+**Returns:** Success confirmation with path
+
+**Example:**
+```json
+{
+  "tool": "fs.write",
+  "arguments": {
+    "path": "hello.py",
+    "contents": "print('Hello, World!')"
+  }
+}
+```
+
+#### `fs.list`
+
+List files and directories in the workspace.
+
+**Parameters:**
+- `path` (string, optional) - Relative path to list (default: workspace root)
+
+**Returns:** Newline-separated list of files and directories
+
+**Example:**
+```json
+{
+  "tool": "fs.list",
+  "arguments": {
+    "path": "src"
+  }
+}
+```
+
+### Python Execution Tools
+
+#### `run.python`
+
+Execute Python code or a Python file in the session's isolated virtual environment.
+
+**Parameters:**
+- `code` (string) - Python code to execute directly
+- `file` (string) - Path to Python file to execute
+
+**Note:** Exactly one of `code` or `file` must be provided.
+
+**Returns:** Standard output from Python execution
+
+**Example (code):**
+```json
+{
+  "tool": "run.python",
+  "arguments": {
+    "code": "print(2 + 2)"
+  }
+}
+```
+
+**Example (file):**
+```json
+{
+  "tool": "run.python",
+  "arguments": {
+    "file": "hello.py"
+  }
+}
+```
+
+#### `pkg.install`
+
+Install Python packages in the session's virtual environment.
+
+**Parameters:**
+- `packages` (string, required) - Space-separated package names or requirements
+
+**Returns:** Installation output from pip
+
+**Example:**
+```json
+{
+  "tool": "pkg.install",
+  "arguments": {
+    "packages": "requests flask pandas"
+  }
+}
+```
+
+### Artifact Management Tools
+
+#### `artifact.get`
+
+Retrieve a generated artifact (file, package, build output) from the session.
+
+**Parameters:**
+- `artifact_id` (string, required) - Artifact identifier (format: `sessionID-timestamp-filename`)
+
+**Returns:** Artifact data with metadata (artifact_id, size_bytes, content_type)
+
+**Example:**
+```json
+{
+  "tool": "artifact.get",
+  "arguments": {
+    "artifact_id": "session-1732550000-1732550123-hello-package.zip"
+  }
+}
+```
+
+**Notes:**
+- Artifacts are scoped to sessions - only the owning session can retrieve an artifact
+- Artifact IDs are generated when files are created in the `artifacts/` subdirectory
+- Currently uses local filesystem storage (file:// URLs)
+- Production deployments can upgrade to S3/MinIO presigned URLs
+
+**Security:**
+- Session validation prevents cross-session artifact access
+- Artifact IDs include session ID for ownership verification
+- All artifact operations are audit logged
+
+### Task Management Tools
+
+#### `task.get_result`
+
+Get the result of a previously queued task.
+
+**Parameters:**
+- `task_id` (string, required) - Task identifier from async operation
+
+**Returns:** Task result or status
+
+**Example:**
+```json
+{
+  "tool": "task.get_result",
+  "arguments": {
+    "task_id": "task-abc123"
+  }
+}
+```
+
+#### `task.get_status`
+
+Get the current status of a task.
+
+**Parameters:**
+- `task_id` (string, required) - Task identifier
+
+**Returns:** Task status (queued, running, completed, failed)
+
+**Example:**
+```json
+{
+  "tool": "task.get_status",
+  "arguments": {
+    "task_id": "task-abc123"
+  }
+}
+```
+
+### Utility Tools
+
+#### `echo`
+
+Echo back a message (test/debug tool).
+
+**Parameters:**
+- `message` (string, required) - Message to echo
+
+**Returns:** The input message
+
+**Example:**
+```json
+{
+  "tool": "echo",
+  "arguments": {
+    "message": "Hello, MCP!"
+  }
+}
+```
+
 ### `ServeWithLogger`
 
 Starts the MCP server with custom logger.