Merge branch 'main' into dev

.pre-commit-config.yaml

@@ -1,4 +1,7 @@
 repos:
+  # ============================================
+  # BACKEND HOOKS (Python)
+  # ============================================
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.14.8
     hooks:
@@ -17,6 +20,36 @@ repos:
         # Exclude auto-generated Gradio custom component files
         exclude: ^packages/niivueviewer/
 
+  # ============================================
+  # FRONTEND HOOKS (TypeScript/React)
+  # ============================================
+  - repo: local
+    hooks:
+      - id: frontend-lint
+        name: frontend-lint (eslint)
+        entry: bash -c 'cd frontend && npm run lint'
+        language: system
+        files: ^frontend/.*\.(ts|tsx|js|jsx)$
+        pass_filenames: false
+
+      - id: frontend-typecheck
+        name: frontend-typecheck (tsc)
+        entry: bash -c 'cd frontend && npx tsc --noEmit'
+        language: system
+        files: ^frontend/.*\.(ts|tsx)$
+        pass_filenames: false
+
+      - id: frontend-test
+        name: frontend-test (vitest coverage)
+        entry: bash -c 'cd frontend && npm run test:coverage'
+        language: system
+        files: ^frontend/.*\.(ts|tsx)$
+        pass_filenames: false
+        stages: [pre-push]  # Run on push only (tests are slow)
+
+  # ============================================
+  # GENERAL HOOKS
+  # ============================================
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
     hooks:

BUGS-AUDIT-2024-12-12.md

@@ -0,0 +1,208 @@
+# Bug Audit Report - 2024-12-12
+
+Consolidated audit findings validated from first principles by reading source code.
+**Status: FIXED** - P1 and P2 bugs addressed in PR #40.
+
+---
+
+## P1 - High Priority (Functional Bugs)
+
+### BUG-005: Exception Handling Converts 400→500
+
+**File:** `src/stroke_deepisles_demo/api/routes.py:127-129`
+
+**Issue:** The exception handler catches ALL exceptions including HTTPException,
+converting intentional 400 Bad Request responses into 500 Internal Server Errors.
+
+```python
+# Lines 96-99: Raises 400 for invalid case_id
+if body.case_id not in valid_cases:
+    raise HTTPException(
+        status_code=400,
+        detail=f"Invalid case ID: '{body.case_id}'. Use GET /api/cases for available cases.",
+    )
+
+# Lines 127-129: BUG - catches the HTTPException above and converts to 500
+except Exception:
+    logger.exception("Failed to create segmentation job")
+    raise HTTPException(status_code=500, detail="Failed to create segmentation job") from None
+```
+
+**Impact:** Frontend receives 500 errors for invalid input, making debugging difficult.
+
+**Fix:** Add `except HTTPException: raise` before `except Exception:` to re-raise HTTP exceptions.
+
+---
+
+### BUG-006: Unbounded Concurrent Inference
+
+**Files:** `src/stroke_deepisles_demo/api/routes.py`, `src/stroke_deepisles_demo/api/main.py`
+
+**Issue:** No rate limiting, semaphores, or concurrency controls exist. Every request
+spawns a GPU-bound background task without limits.
+
+**Validation:** `grep -r "semaphore|rate.?limit|concurrent|max.*jobs|throttl"` returns 0 hits.
+
+**Impact:**
+- N concurrent requests = N GPU inference tasks = OOM or GPU memory exhaustion
+- Denial of service risk (intentional or accidental)
+- HF Spaces free tier could be overwhelmed
+
+**Fix Options:**
+1. Add `asyncio.Semaphore(1)` to limit concurrent inference
+2. Add job queue depth limit (reject if >N pending jobs)
+3. Add rate limiting middleware (slowapi or similar)
+
+---
+
+## P2 - Medium Priority (Resource Leaks, Misconfigurations)
+
+### BUG-008: Temp Directory Leak in Convenience Functions
+
+**File:** `src/stroke_deepisles_demo/data/__init__.py:20-34`
+
+**Issue:** `get_case()` and `list_case_ids()` create dataset instances without using
+the context manager, causing temp directory accumulation.
+
+```python
+def get_case(case_id: str | int) -> CaseFiles:
+    dataset = load_isles_dataset()  # Creates temp dir internally
+    return dataset.get_case(case_id)  # cleanup() never called!
+
+def list_case_ids() -> list[str]:
+    dataset = load_isles_dataset()  # Creates temp dir internally
+    return dataset.list_case_ids()  # cleanup() never called!
+```
+
+**Validation:** The loader.py docstring explicitly says:
+> "Use as context manager: `with load_isles_dataset() as ds: ...` for automatic cleanup"
+
+**Impact:** Unbounded /tmp growth over time, eventual disk exhaustion.
+
+**Fix:** Refactor to use context manager or call `dataset.cleanup()` explicitly.
+
+---
+
+### BUG-009: Results Directory Configuration Drift
+
+**Files:**
+- `src/stroke_deepisles_demo/core/config.py:93` → `results_dir: Path = Path("./results")`
+- `src/stroke_deepisles_demo/api/config.py:10` → `RESULTS_DIR = Path("/tmp/stroke-results")`
+
+**Issue:** Two different default values for results directory in two config modules.
+API uses `/tmp/stroke-results`, core uses `./results`.
+
+**Impact:**
+- Confusion about canonical location
+- Risk of code using wrong config and writing to wrong location
+- core/config.py's `./results` won't work on HF Spaces (not writable)
+
+**Fix:** Consolidate to single source of truth. Remove one or make them reference each other.
+
+---
+
+### BUG-010: Case ID Logged Despite Sensitivity Comment
+
+**File:** `src/stroke_deepisles_demo/api/routes.py:264`
+
+**Issue:** Code explicitly logs case_id despite comment on line 118 saying not to:
+
+```python
+# Line 118 (comment):
+# Note: Don't log case_id as it may be sensitive (medical domain)
+
+# Line 264 (violation):
+logger.info(
+    "Job %s completed: case=%s, dice=%.3f, time=%.1fs",
+    job_id,
+    case_id,  # <-- Logged here
+    result.dice_score or 0,
+    result.elapsed_seconds,
+)
+```
+
+**Impact:** Potential PHI/PII exposure in logs if case IDs contain patient identifiers.
+
+**Fix:** Remove `case=%s` from log format string and remove `case_id` argument.
+
+---
+
+### BUG-011: Frontend Mock Filenames Don't Match Real Backend
+
+**Files:**
+- `frontend/src/mocks/handlers.ts:167-168`
+- `src/stroke_deepisles_demo/api/routes.py:246-256`
+- `src/stroke_deepisles_demo/pipeline.py:123`
+- `src/stroke_deepisles_demo/inference/direct.py:85`
+
+**Issue:** Mock uses different filenames than actual backend output:
+
+| File Type | Mock (handlers.ts) | Real Backend |
+|-----------|-------------------|--------------|
+| DWI | `dwi.nii.gz` | `{case_id}_dwi.nii.gz` |
+| Prediction | `prediction.nii.gz` | `lesion_msk.nii.gz` |
+
+**Validation:**
+- Mock: `dwiUrl: \`\${API_BASE}/files/\${jobId}/\${updatedJob.caseId}/dwi.nii.gz\``
+- Backend pipeline.py:123: `dwi_dest = results_dir / f"{resolved_case_id}_dwi.nii.gz"`
+- Backend direct.py:85: `expected_path = output_dir / "lesion_msk.nii.gz"`
+
+**Impact:** Frontend tests pass but fail in production. Integration gap.
+
+**Fix:** Update mock to match actual backend output filenames.
+
+---
+
+## P3 - Low Priority (Observability, Best Practices)
+
+### BUG-012: Loose Dependency Pinning
+
+**Files:**
+- `pyproject.toml` - Uses `>=` ranges (e.g., `fastapi>=0.115.0`)
+- `frontend/package.json` - Uses `^` ranges (e.g., `"react": "^19.2.0"`)
+
+**Issue:** Dependencies use loose version ranges instead of exact pins.
+
+**Impact:** Non-reproducible builds. Breaking changes in minor updates could cause silent failures.
+
+**Note:** Lock files (uv.lock, package-lock.json) may mitigate this if checked in.
+
+---
+
+## Validated as FALSE (Not Bugs)
+
+### CLAIM: .env tracked despite .gitignore
+**Status:** FALSE
+**Validation:** `git ls-files .env` returns empty. File is not tracked.
+
+### CLAIM: CORS missing .static.hf.space variant
+**Status:** LIKELY FALSE
+**Validation:** HuggingFace Static Spaces use `.hf.space` domain, not `.static.hf.space`.
+The current CORS config includes `https://vibecodermcswaggins-stroke-viewer-frontend.hf.space`.
+
+---
+
+## Fix Status
+
+| Bug | Status | PR |
+|-----|--------|-----|
+| BUG-005 | ✅ FIXED | #40 |
+| BUG-006 | ✅ FIXED | #40 |
+| BUG-008 | ✅ FIXED | #40 |
+| BUG-009 | 🔄 DEFERRED | See NEXT-CONCERNS.md |
+| BUG-010 | ✅ FIXED | #40 |
+| BUG-011 | ✅ FIXED | #40 |
+| BUG-012 | 🔄 DEFERRED | See NEXT-CONCERNS.md |
+
+## Notes
+
+1. **BUG-004 (StaticFiles CORS bypass)** was already fixed in the codebase via `files.py` router.
+   The fix comment at `api/main.py:131-132` documents this.
+
+2. **BUG-007 (No Authentication)** was removed from audit - intentional design for public demo.
+
+---
+
+**Audited by:** Claude Code
+**Date:** 2024-12-12
+**Fixed:** 2024-12-12 (PR #40)

Dockerfile

@@ -75,9 +75,13 @@ EXPOSE 7860
 # Reset ENTRYPOINT from base image
 ENTRYPOINT []
 
-# Explicit frontend origin for CORS (backup to regex)
+# Explicit frontend origin for CORS
 ENV FRONTEND_ORIGIN=https://vibecodermcswaggins-stroke-viewer-frontend.hf.space
 
+# Explicit backend public URL for constructing file URLs
+# This ensures correct https:// URLs even if proxy headers aren't forwarded correctly
+ENV BACKEND_PUBLIC_URL=https://vibecodermcswaggins-stroke-deepisles-demo.hf.space
+
 # Run FastAPI with uvicorn (module path: stroke_deepisles_demo.api.main:app)
 # --proxy-headers: Trust X-Forwarded-Proto from HF Spaces proxy (ensures https:// in request.base_url)
 CMD ["uvicorn", "stroke_deepisles_demo.api.main:app", "--host", "0.0.0.0", "--port", "7860", "--proxy-headers"]

NEXT-CONCERNS.md

@@ -0,0 +1,77 @@
+# Next Concerns - To Investigate
+
+Deferred items from BUGS-AUDIT-2024-12-12.md that need deeper investigation.
+
+---
+
+## BUG-009: Results Directory Configuration Drift
+
+**Priority:** P2 (Medium)
+
+### Current State
+
+Two files define where results go:
+- `core/config.py:93` → `results_dir: Path = Path("./results")`
+- `api/config.py:10` → `RESULTS_DIR = Path("/tmp/stroke-results")`
+
+### Investigation Needed
+
+1. **Does anything actually use `core/config.py`'s `results_dir`?**
+   - Grep codebase for imports from `core/config`
+   - If nothing uses it, delete the duplicate
+   - If something uses it, consolidate to single source of truth
+
+2. **Gold standard pattern:**
+   ```python
+   # api/config.py (SSOT)
+   RESULTS_DIR = Path("/tmp/stroke-results")
+
+   # core/config.py (if needed)
+   from stroke_deepisles_demo.api.config import RESULTS_DIR
+   ```
+
+### Action
+
+Run investigation, then either:
+- Delete unused `core/config.py` results_dir, OR
+- Make it import from `api/config.py`
+
+---
+
+## BUG-012: Loose Dependency Pinning
+
+**Priority:** P3 (Low)
+
+### Current State
+
+- `pyproject.toml` uses `>=` ranges (e.g., `fastapi>=0.115.0`)
+- `package.json` uses `^` ranges (e.g., `"react": "^19.2.0"`)
+
+### Reality Check
+
+Lock files exist and are committed:
+- `uv.lock` → Backend installs are deterministic
+- `package-lock.json` → Frontend installs are deterministic
+
+**Builds ARE reproducible** if you use the lock files.
+
+### Investigation Needed
+
+1. Verify `uv.lock` is committed: `git ls-files uv.lock`
+2. Verify Docker uses `uv sync` (respects lock) not `uv pip install` (ignores lock)
+3. Verify CI uses lock files
+
+### Action
+
+If lock files are committed and used correctly:
+- Close as "mitigated by lock files"
+- Optionally add README note about reproducible builds
+
+If lock files are NOT being used:
+- Fix CI/Docker to use them
+- Document requirement
+
+---
+
+**Created:** 2024-12-12
+**Status:** Pending investigation

frontend/README.md

@@ -99,7 +99,7 @@ If you fork this repository, update these files before deploying:
    ```
 
 2. **Backend CORS** (`src/stroke_deepisles_demo/api/main.py`):
-   Update the `allow_origin_regex` to match your frontend Space URL.
+   Add your frontend URL to the `CORS_ORIGINS` list, or set `FRONTEND_ORIGIN` env var.
 
 3. **Rebuild frontend**:
    ```bash

frontend/src/components/CaseSelector.tsx

@@ -1,5 +1,10 @@
 import { useEffect, useState } from "react";
-import { apiClient } from "../api/client";
+import { apiClient, ApiError } from "../api/client";
+
+// Cold start retry configuration (matches useSegmentation.ts)
+const MAX_COLD_START_RETRIES = 5;
+const INITIAL_RETRY_DELAY = 2000;
+const MAX_RETRY_DELAY = 30000;
 
 interface CaseSelectorProps {
   selectedCase: string | null;
@@ -13,36 +18,84 @@ export function CaseSelector({
   const [cases, setCases] = useState<string[]>([]);
   const [isLoading, setIsLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
+  const [retryCount, setRetryCount] = useState(0);
+  const [isWakingUp, setIsWakingUp] = useState(false);
 
+  // Fetch cases on mount with cold-start retry logic
+  // Using inline async function pattern recommended by React docs for data fetching
   useEffect(() => {
+    let isActive = true;
     const abortController = new AbortController();
 
-    const fetchCases = async () => {
-      try {
-        const data = await apiClient.getCases(abortController.signal);
-        setCases(data.cases);
-      } catch (err) {
-        // Ignore abort errors - component unmounted
-        if (err instanceof Error && err.name === "AbortError") return;
+    async function fetchCases() {
+      let attempts = 0;
+
+      while (attempts <= MAX_COLD_START_RETRIES && isActive) {
+        try {
+          const data = await apiClient.getCases(abortController.signal);
+          if (!isActive) return;
+          setCases(data.cases);
+          setIsWakingUp(false);
+          setRetryCount(0);
+          setIsLoading(false);
+          return; // Success
+        } catch (err) {
+          if (!isActive) return;
+          if (err instanceof Error && err.name === "AbortError") return;
+
+          const is503 = err instanceof ApiError && err.status === 503;
+          const isNetworkError =
+            err instanceof TypeError &&
+            err.message.toLowerCase().includes("fetch");
 
-        const message = err instanceof Error ? err.message : "Unknown error";
-        setError(`Failed to load cases: ${message}`);
-      } finally {
-        if (!abortController.signal.aborted) {
+          // Retry on cold start (503) or network errors
+          if ((is503 || isNetworkError) && attempts < MAX_COLD_START_RETRIES) {
+            attempts++;
+            setRetryCount(attempts);
+            setIsWakingUp(true);
+
+            // Exponential backoff
+            const delay = Math.min(
+              INITIAL_RETRY_DELAY * Math.pow(2, attempts - 1),
+              MAX_RETRY_DELAY,
+            );
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            continue;
+          }
+
+          // Max retries exceeded or non-retryable error
+          const message =
+            is503 || isNetworkError
+              ? "Backend failed to wake up. Please refresh the page."
+              : err instanceof Error
+                ? err.message
+                : "Unknown error";
+          setError(`Failed to load cases: ${message}`);
+          setIsWakingUp(false);
           setIsLoading(false);
+          return;
         }
       }
-    };
+    }
 
     fetchCases();
 
-    return () => abortController.abort();
+    return () => {
+      isActive = false;
+      abortController.abort();
+    };
   }, []);
 
   if (isLoading) {
     return (
       <div className="bg-gray-800 rounded-lg p-4">
-        <p className="text-gray-400">Loading cases...</p>
+        {isWakingUp ? (
+          <p className="text-yellow-400">
+            Backend waking up... Retry {retryCount}/{MAX_COLD_START_RETRIES}
+          </p>
+        ) : (
+          <p className="text-gray-400">Loading cases...</p>
+        )}
       </div>
     );
   }

frontend/src/components/__tests__/CaseSelector.test.tsx

@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { server } from "../../mocks/server";
-import { errorHandlers } from "../../mocks/handlers";
+import { errorHandlers, resetCasesAttempts } from "../../mocks/handlers";
 import { CaseSelector } from "../CaseSelector";
 
 describe("CaseSelector", () => {
@@ -10,6 +10,7 @@ describe("CaseSelector", () => {
 
   beforeEach(() => {
     mockOnSelectCase.mockClear();
+    resetCasesAttempts();
   });
 
   it("shows loading state initially", () => {
@@ -117,4 +118,32 @@ describe("CaseSelector", () => {
     const container = screen.getByRole("combobox").closest("div");
     expect(container).toHaveClass("bg-gray-800");
   });
+
+  it("retries on 503 cold-start and succeeds", async () => {
+    server.use(errorHandlers.casesColdStart);
+
+    render(
+      <CaseSelector selectedCase={null} onSelectCase={mockOnSelectCase} />,
+    );
+
+    // Should show waking up message during retry
+    await waitFor(
+      () => {
+        expect(screen.getByText(/waking up/i)).toBeInTheDocument();
+      },
+      { timeout: 3000 },
+    );
+
+    // Should eventually succeed and show cases
+    await waitFor(
+      () => {
+        expect(screen.getByRole("combobox")).toBeInTheDocument();
+      },
+      { timeout: 5000 },
+    );
+
+    expect(
+      screen.getByRole("option", { name: /sub-stroke0001/i }),
+    ).toBeInTheDocument();
+  });
 });

frontend/src/hooks/useSegmentation.ts

@@ -111,7 +111,19 @@ export function useSegmentation() {
         // Ignore abort errors
         if (err instanceof Error && err.name === "AbortError") return;
 
-        // Don't stop polling on transient network errors - retry next interval
+        // 404 = job expired or lost (HF restart) - this is TERMINAL, not transient
+        if (err instanceof ApiError && err.status === 404) {
+          stopPolling();
+          setIsLoading(false);
+          setJobStatus("failed");
+          setError(
+            "Job expired or lost. This can happen if the backend restarted. Please try again.",
+          );
+          setResult(null);
+          return;
+        }
+
+        // Other errors (network, 5xx) - retry next interval
         console.warn("Polling error (will retry):", err);
       }
     },

frontend/src/mocks/handlers.ts

@@ -159,13 +159,14 @@ export const handlers = [
 
     // Include result if completed
     if (updatedJob.status === "completed") {
+      // Filenames must match actual backend output format
       response.result = {
         caseId: updatedJob.caseId,
         diceScore: 0.847,
         volumeMl: 15.32,
         elapsedSeconds: updatedJob.fastMode ? 12.5 : 45.0,
-        dwiUrl: `${API_BASE}/files/${jobId}/${updatedJob.caseId}/dwi.nii.gz`,
-        predictionUrl: `${API_BASE}/files/${jobId}/${updatedJob.caseId}/prediction.nii.gz`,
+        dwiUrl: `${API_BASE}/files/${jobId}/${updatedJob.caseId}/${updatedJob.caseId}_dwi.nii.gz`,
+        predictionUrl: `${API_BASE}/files/${jobId}/${updatedJob.caseId}/lesion_msk.nii.gz`,
       };
     }
 
@@ -173,6 +174,14 @@ export const handlers = [
   }),
 ];
 
+// Track retry attempts for cold-start testing
+let casesAttempts = 0;
+
+/** Reset the cases attempt counter (call in test beforeEach) */
+export function resetCasesAttempts(): void {
+  casesAttempts = 0;
+}
+
 // Error handlers for testing error states
 export const errorHandlers = {
   casesServerError: http.get(`${API_BASE}/api/cases`, () => {
@@ -186,6 +195,21 @@ export const errorHandlers = {
     return HttpResponse.error();
   }),
 
+  // 503 on first attempt, success on retry (tests cold-start retry)
+  casesColdStart: http.get(`${API_BASE}/api/cases`, async () => {
+    casesAttempts++;
+    if (casesAttempts === 1) {
+      return HttpResponse.json(
+        { detail: "Service Unavailable" },
+        { status: 503 },
+      );
+    }
+    // Succeed on retry
+    return HttpResponse.json({
+      cases: ["sub-stroke0001", "sub-stroke0002", "sub-stroke0003"],
+    });
+  }),
+
   segmentCreateError: http.post(`${API_BASE}/api/segment`, () => {
     return HttpResponse.json(
       { detail: "Failed to create job: case not found" },

src/stroke_deepisles_demo/api/config.py

@@ -0,0 +1,16 @@
+"""API configuration constants.
+
+Single source of truth for API configuration values.
+"""
+
+from pathlib import Path
+
+# Results directory for job outputs (must be in /tmp for HF Spaces)
+# CRITICAL: This is the single source of truth. Import this instead of hardcoding.
+RESULTS_DIR = Path("/tmp/stroke-results")
+
+# Maximum active jobs (pending + running) accepted by the API
+# This limits how many jobs can be queued/running at once, NOT serialized GPU execution
+# T4 GPU (16GB) can handle ~1-2 concurrent DeepISLES inferences safely
+# Value of 10 allows reasonable queue depth while preventing unbounded accumulation
+MAX_CONCURRENT_JOBS = 10

src/stroke_deepisles_demo/api/files.py

@@ -0,0 +1,85 @@
+"""File serving routes for NIfTI result files.
+
+BUG-004 FIX: This module replaces the StaticFiles mount approach.
+
+Previously, files were served via:
+    app.mount("/files", StaticFiles(directory=RESULTS_DIR))
+
+The problem: StaticFiles is a mounted sub-application, and FastAPI/Starlette
+middleware (including CORSMiddleware) does NOT propagate to mounted apps.
+This caused NiiVue's cross-origin fetch to fail with "Failed to fetch".
+
+Solution: Use explicit route handlers that go through the main app's middleware.
+Now CORS headers are correctly applied to file responses.
+
+Reference: https://github.com/fastapi/fastapi/discussions/7319
+"""
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse
+
+from stroke_deepisles_demo.api.config import RESULTS_DIR
+from stroke_deepisles_demo.core.logging import get_logger
+
+logger = get_logger(__name__)
+
+files_router = APIRouter(prefix="/files", tags=["files"])
+
+
+@files_router.get("/{job_id}/{case_id}/{filename}")
+async def get_result_file(job_id: str, case_id: str, filename: str) -> FileResponse:
+    """Serve NIfTI result files with proper CORS headers.
+
+    This route goes through the main FastAPI app's middleware stack,
+    ensuring CORS and CORP headers are applied to the response.
+
+    Args:
+        job_id: The job UUID from segmentation
+        case_id: The case identifier (e.g., sub-stroke0001)
+        filename: The NIfTI filename (e.g., dwi.nii.gz, prediction_fused.nii.gz)
+
+    Returns:
+        FileResponse with the NIfTI file
+
+    Raises:
+        404: File not found (job expired, invalid path, or doesn't exist)
+    """
+    # Construct file path
+    file_path = RESULTS_DIR / job_id / case_id / filename
+
+    # Security: Ensure path doesn't escape RESULTS_DIR (path traversal protection)
+    # Using is_relative_to() instead of startswith() to prevent prefix-collision bypass
+    # e.g., /tmp/stroke-results-evil/file.txt would pass startswith but fail is_relative_to
+    try:
+        base_dir = RESULTS_DIR.resolve()
+        resolved = file_path.resolve()
+        if not resolved.is_relative_to(base_dir):
+            logger.warning("Path traversal attempt blocked: %s", filename)
+            raise HTTPException(status_code=404, detail="File not found")
+    except (OSError, ValueError):
+        raise HTTPException(status_code=404, detail="Invalid file path") from None
+
+    # Check file exists
+    if not resolved.exists() or not resolved.is_file():
+        logger.debug("File not found: %s", resolved)
+        raise HTTPException(
+            status_code=404,
+            detail=f"File not found: {filename}. Job may have expired (1 hour TTL).",
+        )
+
+    # Determine media type based on extension
+    # NIfTI files are typically gzip-compressed
+    if filename.endswith(".nii.gz"):
+        media_type = "application/gzip"
+    elif filename.endswith(".nii"):
+        media_type = "application/octet-stream"
+    else:
+        media_type = "application/octet-stream"
+
+    logger.debug("Serving file: %s (type: %s)", resolved, media_type)
+
+    return FileResponse(
+        path=resolved,
+        media_type=media_type,
+        filename=filename,
+    )

src/stroke_deepisles_demo/api/job_store.py

@@ -23,11 +23,14 @@ import threading
 from dataclasses import dataclass
 from datetime import datetime, timedelta
 from enum import Enum
-from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
+from stroke_deepisles_demo.api.config import RESULTS_DIR
 from stroke_deepisles_demo.core.logging import get_logger
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
 logger = get_logger(__name__)
 
 # Regex for safe job IDs (alphanumeric, hyphens, underscores only)
@@ -135,7 +138,7 @@ class JobStore:
         self._jobs: dict[str, Job] = {}
         self._lock = threading.RLock()
         self._ttl = ttl
-        self._results_dir = results_dir or Path("/tmp/stroke-results")
+        self._results_dir = results_dir or RESULTS_DIR
         self._cleanup_thread: threading.Thread | None = None
         self._shutdown = threading.Event()
 
@@ -147,6 +150,18 @@ class JobStore:
         """
         return bool(job_id) and _SAFE_JOB_ID_PATTERN.match(job_id) is not None
 
+    def get_active_job_count(self) -> int:
+        """Return the number of active (pending or running) jobs.
+
+        Used for concurrency limiting to prevent GPU memory exhaustion.
+        """
+        with self._lock:
+            return sum(
+                1
+                for job in self._jobs.values()
+                if job.status in (JobStatus.PENDING, JobStatus.RUNNING)
+            )
+
     def create_job(self, job_id: str, case_id: str, fast_mode: bool) -> Job:
         """Create a new job in PENDING status.
 

src/stroke_deepisles_demo/api/main.py

@@ -16,23 +16,20 @@ Architecture designed to work within HuggingFace Spaces constraints:
 import os
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
-from pathlib import Path
 from typing import Any
 
 from fastapi import FastAPI, Request, Response
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.staticfiles import StaticFiles
 from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
 
+from stroke_deepisles_demo.api.config import RESULTS_DIR
+from stroke_deepisles_demo.api.files import files_router
 from stroke_deepisles_demo.api.job_store import init_job_store
 from stroke_deepisles_demo.api.routes import router
 from stroke_deepisles_demo.core.logging import get_logger
 
 logger = get_logger(__name__)
 
-# Results directory (must be in /tmp for HF Spaces)
-RESULTS_DIR = Path("/tmp/stroke-results")
-
 
 @asynccontextmanager
 async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
@@ -115,24 +112,25 @@ if FRONTEND_ORIGIN and FRONTEND_ORIGIN not in CORS_ORIGINS:
 # Add CORP middleware first (for COEP compatibility)
 app.add_middleware(CORPMiddleware)
 
-# Add CORS middleware with strict security settings
+# Add CORS middleware with settings for NiiVue binary file fetching
 # Note: Using allow_origins list for exact matching (no regex needed)
 # This eliminates regex security concerns while maintaining single source of truth
 app.add_middleware(
     CORSMiddleware,
     allow_origins=CORS_ORIGINS,
     allow_credentials=False,  # Not needed - no cookies/auth
-    allow_methods=["GET", "POST"],  # Only methods we use
-    allow_headers=["Content-Type"],  # Only headers we need
+    allow_methods=["GET", "POST", "HEAD"],  # HEAD for preflight checks
+    allow_headers=["Content-Type", "Range"],  # Range needed for partial content requests
+    expose_headers=["Content-Range", "Content-Length", "Accept-Ranges"],  # NiiVue needs these
 )
 
-# API routes
+# API routes (includes /api/* endpoints)
 app.include_router(router, prefix="/api")
 
-# Static files for NIfTI results
-# Note: Mount happens at import time; ensure directory exists here as well.
-RESULTS_DIR.mkdir(parents=True, exist_ok=True)
-app.mount("/files", StaticFiles(directory=str(RESULTS_DIR)), name="files")
+# File routes (serves NIfTI results through main app's middleware for CORS)
+# BUG-004 FIX: Previously used StaticFiles mount which bypassed CORS middleware.
+# Now using explicit routes so CORS headers are applied to file responses.
+app.include_router(files_router)
 
 
 @app.get("/")

src/stroke_deepisles_demo/api/routes.py

@@ -12,10 +12,10 @@ from __future__ import annotations
 
 import os
 import uuid
-from pathlib import Path
 
 from fastapi import APIRouter, BackgroundTasks, HTTPException, Request
 
+from stroke_deepisles_demo.api.config import MAX_CONCURRENT_JOBS, RESULTS_DIR
 from stroke_deepisles_demo.api.job_store import JobStatus, get_job_store
 from stroke_deepisles_demo.api.schemas import (
     CasesResponse,
@@ -33,9 +33,6 @@ logger = get_logger(__name__)
 
 router = APIRouter()
 
-# Base directory for results
-RESULTS_BASE = Path("/tmp/stroke-results")
-
 
 def get_backend_base_url(request: Request) -> str:
     """Get the backend's public URL for building absolute file URLs.
@@ -93,7 +90,15 @@ def create_segment_job(
     - Returning immediately avoids timeout errors
     """
     try:
-        # Validate case_id exists before creating job (BUG-012 fix)
+        # Concurrency limit to prevent GPU memory exhaustion (BUG-006 fix)
+        store = get_job_store()
+        if store.get_active_job_count() >= MAX_CONCURRENT_JOBS:
+            raise HTTPException(
+                status_code=503,
+                detail="Server busy: too many active jobs. Please try again later.",
+            )
+
+        # Validate case_id exists before creating job
         valid_cases = list_case_ids()
         if body.case_id not in valid_cases:
             raise HTTPException(
@@ -103,7 +108,6 @@ def create_segment_job(
 
         # Use full UUID hex for uniqueness (no truncation)
         job_id = uuid.uuid4().hex
-        store = get_job_store()
         backend_url = get_backend_base_url(request)
 
         # Create job record
@@ -127,6 +131,10 @@ def create_segment_job(
             message=f"Segmentation job queued for {body.case_id}",
         )
 
+    except HTTPException:
+        # Re-raise HTTP exceptions (400, 404, 503, etc.) as-is
+        # Without this, they'd be caught by `except Exception` and converted to 500
+        raise
     except Exception:
         logger.exception("Failed to create segmentation job")
         raise HTTPException(status_code=500, detail="Failed to create segmentation job") from None
@@ -215,7 +223,7 @@ def run_segmentation_job(
         store.update_progress(job_id, 10, "Loading case data...")
 
         # Set up output directory
-        output_dir = RESULTS_BASE / job_id
+        output_dir = RESULTS_DIR / job_id
 
         store.update_progress(job_id, 20, "Staging files for DeepISLES...")
 
@@ -263,10 +271,10 @@ def run_segmentation_job(
         # Mark as completed
         store.complete_job(job_id, result_data)
 
+        # Note: Don't log case_id as it may be sensitive (medical domain)
         logger.info(
-            "Job %s completed: case=%s, dice=%.3f, time=%.1fs",
+            "Job %s completed: dice=%.3f, time=%.1fs",
             job_id,
-            case_id,
             result.dice_score or 0,
             result.elapsed_seconds,
         )

src/stroke_deepisles_demo/data/__init__.py

@@ -21,14 +21,21 @@ def get_case(case_id: str | int) -> CaseFiles:
     """
     Load a single case by ID or index.
 
+    Uses context manager to ensure HuggingFace temp files are cleaned up.
+    This prevents unbounded disk usage from accumulating temp NIfTI files.
+
     Returns:
         CaseFiles dictionary
     """
-    dataset = load_isles_dataset()
-    return dataset.get_case(case_id)
+    with load_isles_dataset() as dataset:
+        return dataset.get_case(case_id)
 
 
 def list_case_ids() -> list[str]:
-    """List all available case IDs."""
-    dataset = load_isles_dataset()
-    return dataset.list_case_ids()
+    """List all available case IDs.
+
+    Uses context manager to ensure HuggingFace temp files are cleaned up.
+    This prevents unbounded disk usage from accumulating temp NIfTI files.
+    """
+    with load_isles_dataset() as dataset:
+        return dataset.list_case_ids()