fix(audit): comprehensive P1-P4 audit fixes (#45)

* docs(audit): add remaining issues analysis for 2024-12-13

Cross-reference new audit findings against previous PR #44 fixes.
Categorizes P1-P4 issues that remain to be addressed.

Key findings:
- P1: max_concurrent_jobs default too high (10 -> 1)
- P1: timeout not propagated to direct invocation
- P2: Several unused settings (hf_cache_dir, temp_dir, deepisles_repo_path)
- P2: Concurrency check after expensive validation
- P3/P4: Documentation and cleanup items

Many issues from audit already fixed in PR #44 (confirmed).

* fix(audit): address remaining P1-P2 issues and remove config slop

P1 Fixes (Safety Critical):
- Change max_concurrent_jobs default from 10 to 1 (GPU OOM prevention)
- Pass timeout parameter through to direct invocation path

Config Slop Removed (speculative placeholders that duplicated native functionality):
- hf_cache_dir: use HF_HOME env var instead (already set in Dockerfile)
- temp_dir: use TMPDIR env var instead (Python native)
- deepisles_repo_path: no use case (direct mode only runs in container)
- DEEPISLES_PATH env var: removed from Dockerfile (unused)

P2 Fixes:
- Pre-check concurrency limit before expensive list_case_ids() validation
- Change direct invocation logging from INFO to DEBUG (prevent log explosion)
- Apply log settings (STROKE_DEMO_LOG_LEVEL/FORMAT) to FastAPI startup

P3/P4 Cleanup:
- Update package description from Gradio to React SPA + FastAPI
- Fix CORS comment (HEAD -> OPTIONS for preflight)
- Completely rewrite docs/guides/configuration.md with current settings

All 157 tests pass. ruff/mypy clean.

* fix(audit): P2 prediction path mismatch and P3 .env.example cleanup

Validated findings from external agent re-review:

P2 Fix - Prediction URL mismatch (Docker mode only):
- deepisles.py find_prediction_mask() may return path in results/ subdir
- URL contract expects files directly in output_dir
- Added copy step to ensure prediction is at expected location

P3 Fix - .env.example stale reference:
- Removed STROKE_DEMO_TEMP_DIR (setting was removed, use native TMPDIR)

Bug doc: POST-AUDIT-FINDINGS-2025-12-13.md with full analysis

* fix(audit): address P3/P4 findings from round 2 review

P3 fixes:
- main.py: add unused-ignore to torch type: ignore for env-independence
- deployment.md: complete rewrite for React+FastAPI architecture
- quickstart.md: reorder options, React SPA first, Gradio marked legacy

P4 fixes:
- direct.py: move path/command logging from INFO to DEBUG
- fixtures.ts: update URLs to match /files/{jobId}/{caseId}/ contract
- cli.py + data/__init__.py: wire --dataset arg to list_case_ids()

Docs:
- Consolidated audit findings in docs/bugs/AUDIT-FINDINGS-2025-12-13.md
- Removed redundant root-level bug docs

Test results: 157 passed (backend), 70 passed (frontend)

* docs(audit): fix P3/P4 doc drift from round 3 review

P3 fixes:
- quickstart.md/deployment.md/README.md: add --extra api/gradio to install
- README.md: React+FastAPI as primary, Gradio as legacy option 4
- TECHNICAL_DEBT.md: mark as resolved, note React migration superseded Gradio fixes

P4 fixes:
- deployment.md: clarify HF_SPACES set by Dockerfile, not auto by HF
- direct.py: docstring mentions FastAPI not Gradio
- NiiVueViewer.test.tsx: comment noting simplified URLs for component testing

Test results: 157 passed (backend), 70 passed (frontend)

* fix(coderabbit): address valid review feedback

Accepted:
- docs/bugs/NEXT-CONCERNS.md: add `text` language to fenced code block
- deepisles.py: add try/except for shutil.copy2 with DeepISLESError
- deepisles.py: improve timeout docstring (default value, None behavior)

Rejected (with justification):
- TECHNICAL_DEBT.md date: "December 2025" is correct (current year)
- fixtures.ts relative URLs: API returns absolute URLs, fixtures should match

Test results: 157 passed (backend), ruff/mypy clean

.env.example

@@ -14,7 +14,7 @@ STROKE_DEMO_DEEPISLES_USE_GPU=true
 
 # Paths
 STROKE_DEMO_RESULTS_DIR=./results
-# STROKE_DEMO_TEMP_DIR=/tmp/custom_temp
+# Note: For temp directory, use the native TMPDIR environment variable
 
 # UI
 STROKE_DEMO_GRADIO_SERVER_NAME=0.0.0.0

Dockerfile

@@ -59,10 +59,6 @@ RUN uv pip install --no-deps -e .
 ENV HF_SPACES=1
 ENV DEEPISLES_DIRECT_INVOCATION=1
 
-# Point to DeepISLES location for direct invocation
-# DeepISLES code is at /app in the base image
-ENV DEEPISLES_PATH=/app
-
 # Ensure HuggingFace cache uses our writable directory
 ENV HF_HOME=/home/user/demo/cache
 

README.md

@@ -74,8 +74,8 @@ This project provides a complete end-to-end workflow:
 git clone https://github.com/The-Obstacle-Is-The-Way/stroke-deepisles-demo.git
 cd stroke-deepisles-demo
 
-# Install dependencies
-uv sync
+# Install dependencies (includes FastAPI backend)
+uv sync --extra api
 ```
 
 ### Running the Demo
@@ -85,11 +85,15 @@ uv sync
     docker pull isleschallenge/deepisles
     ```
 
-2.  **Launch the UI**:
+2.  **Launch the Web UI** (React + FastAPI):
     ```bash
-    uv run python -m stroke_deepisles_demo.ui.app
+    # Terminal 1: Start backend
+    uv run uvicorn stroke_deepisles_demo.api.main:app --reload --port 7860
+
+    # Terminal 2: Start frontend
+    cd frontend && npm install && npm run dev
     ```
-    Open [http://localhost:7860](http://localhost:7860) in your browser.
+    Open [http://localhost:5173](http://localhost:5173) in your browser.
 
 3.  **Run via CLI**:
     ```bash
@@ -100,6 +104,12 @@ uv sync
     uv run stroke-demo run --case sub-stroke0001
     ```
 
+4.  **Legacy Gradio UI** (optional):
+    ```bash
+    uv sync --extra gradio
+    uv run python -m stroke_deepisles_demo.ui.app
+    ```
+
 ## Documentation
 
 -   [Quickstart Guide](docs/guides/quickstart.md)

docs/TECHNICAL_DEBT.md

@@ -1,12 +1,17 @@
 # Technical Debt and Known Issues
 
-> **Last Audit**: December 2025 (Revision 6)
+> **Last Audit**: December 2025 (Revision 7)
 > **Auditor**: Claude Code + External Senior Review
-> **Status**: P0 BLOCKER - NiiVue/WebGL integration broken on HF Spaces
+> **Status**: ✅ All P0/P1/P2 issues resolved
 
 ## Summary
 
-**CRITICAL ISSUE**: The NiiVue 3D viewer does not work on HuggingFace Spaces due to Gradio architecture limitations. See Issue #24.
+All critical issues have been resolved. The former P0 blocker (NiiVue/WebGL on HF Spaces)
+was bypassed by migrating to a **React SPA + FastAPI** architecture, which is now the
+primary deployment target.
+
+> **Note**: The sections below document the **historical Gradio-based approach** and its
+> resolution. They are preserved for context but describe legacy architecture.
 
 | Severity | Count | Description | Status |
 |----------|-------|-------------|--------|
@@ -90,6 +95,9 @@ See: `docs/specs/19-perf-base64-to-file-urls.md`
 
 ## Conclusion
 
-The codebase is **production-ready for all features EXCEPT the Interactive 3D Viewer (NiiVue)**. All other technical debt items are resolved.
+The codebase is **production-ready**. The P0 blocker was resolved by migrating to React + FastAPI:
+
+- **Primary UI**: React SPA with NiiVue (works correctly on HF Spaces)
+- **Legacy UI**: Gradio (preserved for backwards compatibility, NiiVue broken on HF Spaces)
 
-**Next step:** Implement Gradio Custom Component per spec #28 to fix the P0 blocker.
+The Gradio Custom Component approach (spec #28) was superseded by the React migration.

docs/bugs/AUDIT-FINDINGS-2025-12-13.md

@@ -0,0 +1,143 @@
+# Audit Findings - 2025-12-13 (Final)
+
+**Date:** 2025-12-13
+**Branch:** `dev`
+**Status:** ALL FIXED ✓
+
+---
+
+## Summary
+
+Two rounds of external agent audit findings validated and fixed:
+
+### Round 1 Findings (P1-P4) - All Fixed in Previous Commit
+
+| Issue | Severity | Status |
+|-------|----------|--------|
+| max_concurrent_jobs=10 unsafe | P1 | ✓ Fixed |
+| Timeout not passed to direct invocation | P1 | ✓ Fixed |
+| Slop settings removed (hf_cache_dir, temp_dir, deepisles_repo_path) | P2 | ✓ Fixed |
+| P2: Prediction path mismatch (Docker mode) | P2 | ✓ Fixed |
+| P3: .env.example stale TEMP_DIR reference | P3 | ✓ Fixed |
+| Concurrency pre-check, logging, package description | P2-P4 | ✓ Fixed |
+
+### Round 2 Findings (P3-P4) - Fixed in This Commit
+
+| Issue | Severity | Status |
+|-------|----------|--------|
+| mypy type: ignore becomes env-dependent | P3 | ✓ Fixed |
+| deployment.md describes outdated Gradio+DinD | P3 | ✓ Fixed |
+| quickstart.md missing React+FastAPI path | P3 | ✓ Fixed |
+| direct.py logs paths at INFO | P4 | ✓ Fixed |
+| frontend fixture URLs don't match contract | P4 | ✓ Fixed |
+| CLI --dataset arg "(not used yet)" | P4 | ✓ Fixed |
+| pytest-asyncio config | P4 | N/A (pkg not installed) |
+
+---
+
+## Round 2 Fixes Detail
+
+### P3: mypy type: ignore[import-not-found] environment-dependent
+
+**Problem:** On machines with torch installed, mypy complains about unused ignore.
+
+**File:** `src/stroke_deepisles_demo/api/main.py:54`
+
+**Fix:** Added `unused-ignore` to suppress both warnings:
+```python
+import torch  # type: ignore[import-not-found,unused-ignore]
+```
+
+### P3: deployment.md described outdated architecture
+
+**Problem:** Docs described Docker-in-Docker + Gradio as primary deployment.
+
+**File:** `docs/guides/deployment.md`
+
+**Fix:** Complete rewrite reflecting:
+- React SPA frontend (Static SDK Space)
+- FastAPI backend (Docker SDK Space with GPU)
+- Direct invocation mode (subprocess to conda env)
+- Gradio marked as legacy
+
+### P3: quickstart.md missing React+FastAPI path
+
+**Problem:** Only showed Gradio UI as primary option.
+
+**File:** `docs/guides/quickstart.md`
+
+**Fix:** Reordered options:
+1. React SPA + FastAPI (Recommended)
+2. CLI
+3. Python API
+4. Legacy Gradio UI
+
+### P4: direct.py logged paths at INFO
+
+**Problem:** Full input paths logged at INFO level, potentially exposing sensitive path info.
+
+**File:** `src/stroke_deepisles_demo/inference/direct.py:158-164, 189`
+
+**Fix:** Changed both logging calls from `logger.info` to `logger.debug`.
+
+### P4: frontend fixture URLs don't match API contract
+
+**Problem:** Fixture URLs were `/files/dwi.nii.gz` but actual API returns `/files/{jobId}/{caseId}/dwi.nii.gz`.
+
+**File:** `frontend/src/test/fixtures.ts:14-15`
+
+**Fix:** Updated URLs to match contract:
+```typescript
+dwiUrl: "http://localhost:7860/files/test-job-123/sub-stroke0001/dwi.nii.gz",
+predictionUrl: "http://localhost:7860/files/test-job-123/sub-stroke0001/prediction.nii.gz",
+```
+
+### P4: CLI --dataset arg not wired
+
+**Problem:** Help text said "(not used yet)".
+
+**Files:**
+- `src/stroke_deepisles_demo/cli.py:23`
+- `src/stroke_deepisles_demo/data/__init__.py:34`
+
+**Fix:**
+1. Added `source` parameter to `list_case_ids()` function
+2. Updated CLI to pass `args.dataset` to `list_case_ids(source=args.dataset)`
+3. Updated help text to "HF dataset ID or local path"
+
+### P4: pytest-asyncio config warning
+
+**Claim:** pytest-asyncio emits deprecation warning about unset `asyncio_default_fixture_loop_scope`.
+
+**Investigation:**
+- pytest-asyncio is NOT installed
+- No async tests in test suite
+- Warning was likely from different environment
+
+**Fix:** N/A - removed non-applicable config that was causing "unknown config option" warnings.
+
+---
+
+## Test Verification
+
+```
+Backend: 157 passed (pytest)
+Frontend: 70 passed (vitest)
+Linting: All checks passed (ruff)
+Types: No issues (mypy)
+```
+
+---
+
+## Files Modified (Round 2)
+
+| File | Change |
+|------|--------|
+| `src/stroke_deepisles_demo/api/main.py` | mypy ignore fix |
+| `src/stroke_deepisles_demo/inference/direct.py` | INFO → DEBUG logging |
+| `src/stroke_deepisles_demo/data/__init__.py` | Added source param to list_case_ids |
+| `src/stroke_deepisles_demo/cli.py` | Wired --dataset arg |
+| `docs/guides/deployment.md` | Complete rewrite for React+FastAPI |
+| `docs/guides/quickstart.md` | Reordered options, React first |
+| `frontend/src/test/fixtures.ts` | Fixed URL contract |
+| `pyproject.toml` | Removed non-applicable pytest-asyncio config |

docs/bugs/NEXT-CONCERNS.md

@@ -1,38 +1,76 @@
-# Next Concerns - Critical Architecture Debt
+# Next Concerns - Config Audit & Fixes Complete
 
-**Status:** VALIDATED - All claims verified from first principles
-**Priority:** P0/P1 - Production reproducibility and config integrity at risk
+**Date:** 2025-12-13
+**Branch:** `fix/remaining-audit-issues`
+**Status:** IMPLEMENTED - Ready for review
 
 ---
 
-## PART 1: CONFIG DRIFT (BUG-009) - RESOLVED
+## Summary of Changes
 
-### Status
-- **Consolidated:** `api/config.py` deleted.
-- **SSOT:** `core/config.py` now holds all API settings.
-- **Env Vars:** `Dockerfile` updated to use `STROKE_DEMO_*` prefix.
-- **Validation:** Tests pass, env var overrides work.
+### P1 Fixes (Safety Critical)
+
+| Issue | Fix | File |
+|-------|-----|------|
+| max_concurrent_jobs=10 unsafe | Changed default to 1 | `config.py:97-98` |
+| Timeout not passed to direct invocation | Added timeout parameter | `deepisles.py:222-223, 318` |
+
+### Slop Removed (Never Actually Needed)
+
+| Setting | Reason | Status |
+|---------|--------|--------|
+| `hf_cache_dir` | Duplicates `HF_HOME` (already set in Dockerfile) | **REMOVED** |
+| `temp_dir` | Duplicates `TMPDIR` (Python native) | **REMOVED** |
+| `deepisles_repo_path` | No valid use case (direct mode only in container) | **REMOVED** |
+| `DEEPISLES_PATH` env var | Unused in direct.py | **REMOVED** from Dockerfile |
+
+### P2 Fixes
+
+| Issue | Fix | File |
+|-------|-----|------|
+| Concurrency check after expensive validation | Added pre-check before list_case_ids() | `routes.py:95-101` |
+| Direct invocation logs verbose at INFO | Changed to DEBUG | `direct.py:200-206` |
+| FastAPI doesn't apply log settings | Added setup_logging() at startup | `main.py:47-48` |
+
+### P3/P4 Cleanup
+
+| Issue | Fix | File |
+|-------|-----|------|
+| Package description mentions Gradio | Updated to React SPA + FastAPI | `__init__.py:1` |
+| HEAD comment wrong (should be OPTIONS) | Fixed comment | `main.py:112` |
+| Configuration docs outdated | Completely rewritten | `docs/guides/configuration.md` |
 
 ---
 
-## PART 2: DEPENDENCY PINNING (BUG-012) - RESOLVED
+## Test Results
 
-### Status
-- **Base Image:** Pinned to `sha256:848c9eceb67dbc585bcb37f093389d142caeaa98878bd31039af04ef297a5af4`.
-- **Lock File:** Dockerfile now uses `uv sync --frozen` to respect `uv.lock`.
-- **Path:** Dockerfile adds `.venv/bin` to `PATH` for correct execution.
-- **Dependency Migration:** Migrated from hard-forked `datasets` to maintained `neuroimaging-go-brrrr` extension (v0.2.1) + standard `datasets` library. Validated end-to-end in Docker.
-- **Validation:** Docker build succeeds, runtime verifies settings load and modules importable.
+```text
+157 passed, 7 deselected in 12.73s
+ruff check: All checks passed!
+ruff format: 27 files already formatted
+mypy: Success: no issues found in 27 source files
+```
 
 ---
 
-## PART 3: FRONTEND CONFIG - NO ACTION NEEDED
+## Files Changed
 
-### Status
-- Keeping current build-time `.env.production` approach.
-- No immediate need for runtime variables via `window.huggingface.variables`.
+1. `src/stroke_deepisles_demo/core/config.py` - Removed slop, fixed max_concurrent_jobs
+2. `src/stroke_deepisles_demo/inference/deepisles.py` - Pass timeout to direct invocation
+3. `src/stroke_deepisles_demo/inference/direct.py` - DEBUG logging for verbose output
+4. `src/stroke_deepisles_demo/api/routes.py` - Pre-check concurrency before validation
+5. `src/stroke_deepisles_demo/api/main.py` - setup_logging() at startup, fix OPTIONS comment
+6. `src/stroke_deepisles_demo/__init__.py` - Updated package description
+7. `Dockerfile` - Removed unused DEEPISLES_PATH env var
+8. `docs/guides/configuration.md` - Complete rewrite with current settings
 
 ---
 
-**Validated:** 2025-12-12
-**Status:** COMPLETED
+## What's Left (P4 - Optional)
+
+These are exported in public API, so removing could be breaking change. Left as-is:
+- `DatasetInfo` class (defined but never instantiated)
+- `create_staging_directory` (has tests, is a utility function)
+
+These are minor doc issues, not affecting functionality:
+- Broken references to archived spec docs in some files

docs/bugs/REMAINING-ISSUES-2024-12-13.md

@@ -0,0 +1,260 @@
+# Remaining Issues - Post-Audit 2024-12-13
+
+**Context:** Deep audit performed after PR #44 merged (security + config wiring fixes).
+**Method:** Cross-referenced new audit against existing fixes. Validated each claim from first principles.
+
+---
+
+## Executive Summary
+
+The previous PR #44 addressed many issues. This document captures **genuinely new findings** that were not previously addressed. Issues are prioritized P1-P4.
+
+**Scope:** Fix these in branch `fix/remaining-audit-issues`
+
+---
+
+## P1 - High Priority (Should Fix)
+
+### P1-001: Default max_concurrent_jobs=10 is unsafe for single GPU
+
+**Location:** `src/stroke_deepisles_demo/core/config.py:98`
+
+**Issue:** Default of 10 concurrent jobs can trivially trigger GPU OOM on a single GPU (HF Spaces T4 has 16GB VRAM). Even 2-3 concurrent DeepISLES runs can cause thrashing.
+
+**Current:**
+```python
+max_concurrent_jobs: int = 10
+```
+
+**Fix:** Change default to 1 (safest for demo). Document tuning guidance.
+
+**Severity:** High - can crash the demo under moderate load.
+
+---
+
+### P1-002: Timeout not propagated to direct invocation path
+
+**Location:** `src/stroke_deepisles_demo/inference/deepisles.py:310-315`
+
+**Issue:** `_run_via_direct_invocation()` doesn't pass timeout to `run_deepisles_direct()`, making `STROKE_DEMO_DEEPISLES_TIMEOUT_SECONDS` ineffective on HF Spaces.
+
+**Current:**
+```python
+def _run_via_direct_invocation(..., fast: bool) -> DeepISLESResult:
+    # No timeout parameter!
+    result = run_deepisles_direct(
+        dwi_path=dwi_path,
+        adc_path=adc_path,
+        output_dir=output_dir,
+        flair_path=flair_path,
+        fast=fast,
+        # timeout missing!
+    )
+```
+
+**Fix:** Add `timeout` parameter to `_run_via_direct_invocation()` and pass it through.
+
+---
+
+## P2 - Medium Priority (Tech Debt)
+
+### P2-001: hf_cache_dir setting exists but is not used
+
+**Location:** `src/stroke_deepisles_demo/core/config.py:80` + `src/stroke_deepisles_demo/data/loader.py:224`
+
+**Issue:** `Settings.hf_cache_dir` is defined but `datasets.load_dataset()` doesn't receive `cache_dir=`. Operators setting `STROKE_DEMO_HF_CACHE_DIR` get no effect.
+
+**Fix:** Pass `cache_dir=settings.hf_cache_dir` when set, or remove the setting.
+
+**Decision:** Wire it in (per previous directive: wire in settings properly).
+
+---
+
+### P2-002: temp_dir setting exists but is not used
+
+**Location:** `src/stroke_deepisles_demo/core/config.py:92` + `src/stroke_deepisles_demo/pipeline.py:118`
+
+**Issue:** `Settings.temp_dir` defined but pipeline uses `tempfile.mkdtemp()` without `dir=` parameter.
+
+**Fix:** Use `dir=settings.temp_dir` when set.
+
+---
+
+### P2-003: deepisles_repo_path setting exists but is not used
+
+**Location:** `src/stroke_deepisles_demo/core/config.py:89` + `src/stroke_deepisles_demo/inference/direct.py:32-35`
+
+**Issue:** `Settings.deepisles_repo_path` defined but direct.py hardcodes `/app` and `/opt/conda`.
+
+**Fix:** Use setting to derive adapter path and cwd. Also wire `DEEPISLES_PATH` env var (Dockerfile:64).
+
+---
+
+### P2-004: Concurrency limit checked after expensive validation
+
+**Location:** `src/stroke_deepisles_demo/api/routes.py:95-110`
+
+**Issue:** `list_case_ids()` is called (potentially expensive HF dataset load) before checking concurrency limit. Wasted work when limit already reached.
+
+**Fix:** Reorder to check concurrency limit first, then validate case_id.
+
+---
+
+### P2-005: Direct invocation logs full stdout/stderr at INFO/WARN
+
+**Location:** `src/stroke_deepisles_demo/inference/direct.py:200-205`
+
+**Issue:** Can explode log volume with DeepISLES's verbose output, make JSON logging invalid.
+
+**Fix:** Log at DEBUG level, or truncate/summarize at INFO.
+
+---
+
+### P2-006: FastAPI doesn't apply log settings
+
+**Location:** `src/stroke_deepisles_demo/api/main.py`
+
+**Issue:** `STROKE_DEMO_LOG_LEVEL` and `STROKE_DEMO_LOG_FORMAT` are only applied in Gradio entrypoints. FastAPI startup doesn't call `setup_logging()`.
+
+**Fix:** Call `setup_logging(settings.log_level, format_style=settings.log_format)` in FastAPI startup.
+
+---
+
+## P3 - Low Priority (Documentation/Cleanup)
+
+### P3-001: DEEPISLES_PATH env var set but unused
+
+**Location:** `Dockerfile:64`
+
+**Issue:** `ENV DEEPISLES_PATH=/app` is set but direct.py doesn't read it.
+
+**Fix:** Either wire it in (ties to P2-003) or remove from Dockerfile.
+
+---
+
+### P3-002: Package description still mentions Gradio
+
+**Location:** `src/stroke_deepisles_demo/__init__.py:1`
+
+**Issue:** Says "Gradio visualization" but primary UI is now React SPA.
+
+**Fix:** Update description.
+
+---
+
+### P3-003: gradio_niivueviewer in extras but commented out in code
+
+**Location:** `pyproject.toml:46-50` + `src/stroke_deepisles_demo/ui/components.py:7-9`
+
+**Issue:** Extra maintenance surface for unused component.
+
+**Fix:** Remove from extras if truly deprecated, or document scope.
+
+---
+
+### P3-004: Docs reference non-existent spec files
+
+**Location:** Multiple (`deepisles.py:9`, `direct.py:15`, `viewer.py:8-9`)
+
+**Issue:** References to `docs/specs/07-hf-spaces-deployment.md` and `docs/specs/19-perf-base64-to-file-urls.md` which don't exist (may have been archived).
+
+**Fix:** Update doc references or point to archive location.
+
+---
+
+## P4 - Nitpicks (Optional Cleanup)
+
+### P4-001: app.py doesn't pass gradio_show_error
+
+**Location:** `app.py:32-38`
+
+**Issue:** Root app.py doesn't pass `show_error=settings.gradio_show_error` like ui/app.py does.
+
+**Fix:** Pass consistently.
+
+---
+
+### P4-002: "json" log format is not valid JSON
+
+**Location:** `src/stroke_deepisles_demo/core/logging.py:30`
+
+**Issue:** JSON format doesn't escape message content, breaks if messages contain quotes/newlines.
+
+**Fix:** Use proper JSON formatter (e.g., `python-json-logger`).
+
+---
+
+### P4-003: create_staging_directory is unused
+
+**Location:** `src/stroke_deepisles_demo/data/staging.py:93`
+
+**Issue:** Dead code surface.
+
+**Fix:** Remove or integrate via temp_dir setting.
+
+---
+
+### P4-004: DatasetInfo class is unused
+
+**Location:** `src/stroke_deepisles_demo/data/loader.py:45`
+
+**Issue:** Defined but never instantiated.
+
+**Fix:** Remove or wire into API responses.
+
+---
+
+### P4-005: HEAD method comment is incorrect
+
+**Location:** `src/stroke_deepisles_demo/api/main.py:108-109`
+
+**Issue:** Comment says "HEAD for preflight checks" but CORS preflight uses OPTIONS.
+
+**Fix:** Fix comment.
+
+---
+
+## Already Fixed (PR #44) - Confirmed
+
+These issues from the audit were **already addressed**:
+
+| Issue | Status | Evidence |
+|-------|--------|----------|
+| Docker build missing `--extra api` | FIXED | Dockerfile:44 |
+| hf_dataset_id not wired | FIXED | loader.py:217 |
+| hf_token not wired | FIXED | loader.py:218-224 |
+| deepisles_docker_image not wired | FIXED | deepisles.py:153-155 |
+| deepisles_timeout_seconds not wired | FIXED | pipeline.py:93-95 |
+| deepisles_use_gpu not wired | FIXED | pipeline.py:91-93 |
+| TOCTOU race in concurrency | FIXED | routes.py:107-110 (atomic create_job_if_under_limit) |
+| File extension allowlist | FIXED | files.py:28 |
+| Path traversal in subject_id | FIXED | loader.py:111-115 |
+| Stale StaticFiles comment | FIXED | Dockerfile:70 |
+
+---
+
+## Intentional / Non-Issues
+
+| Claim | Verdict | Reason |
+|-------|---------|--------|
+| No auth/rate limiting | NON-ISSUE | Intentional for public demo |
+| Dataset reload per request | ACCEPTABLE | Demo scale (149 cases), adds negligible latency |
+| Docker-mode file URL mismatch | NON-ISSUE | `find_prediction_mask()` returns actual path, pipeline copies to `results_dir/{case_id}/` correctly |
+
+---
+
+## Fix Order
+
+1. **P1-001**: max_concurrent_jobs default (safety)
+2. **P1-002**: Timeout propagation to direct invocation
+3. **P2-004**: Reorder concurrency check before validation
+4. **P2-001, P2-002, P2-003**: Wire in remaining dead settings
+5. **P2-005, P2-006**: Logging fixes
+6. **P3-***: Documentation cleanup
+7. **P4-***: Nitpicks (time permitting)
+
+---
+
+**Auditor:** Claude Code
+**Date:** 2024-12-13
+**Target Branch:** `fix/remaining-audit-issues`

docs/guides/configuration.md

@@ -1,25 +1,58 @@
 # Configuration
 
-All settings can be configured via environment variables.
+All settings can be configured via environment variables with the `STROKE_DEMO_` prefix.
 
 ## Environment Variables
 
+### Logging
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `STROKE_DEMO_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
 | `STROKE_DEMO_LOG_FORMAT` | `simple` | Log format (simple, detailed, json) |
-| `STROKE_DEMO_HF_DATASET_ID` | `YongchengYAO/ISLES24-MR-Lite` | HuggingFace dataset ID |
-| `STROKE_DEMO_HF_CACHE_DIR` | `None` | Custom HF cache directory |
-| `STROKE_DEMO_HF_TOKEN` | `None` | HuggingFace API token (for private datasets) |
+
+### HuggingFace
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STROKE_DEMO_HF_DATASET_ID` | `hugging-science/isles24-stroke` | HuggingFace dataset ID |
+| `STROKE_DEMO_HF_TOKEN` | `None` | HuggingFace API token (for private/gated datasets) |
+
+> **Note:** To control HF cache location, use the native `HF_HOME` env var (already set in Dockerfile).
+
+### DeepISLES Inference
+
+| Variable | Default | Description |
+|----------|---------|-------------|
 | `STROKE_DEMO_DEEPISLES_DOCKER_IMAGE` | `isleschallenge/deepisles` | DeepISLES Docker image |
-| `STROKE_DEMO_DEEPISLES_FAST_MODE` | `true` | Use single-model mode |
-| `STROKE_DEMO_DEEPISLES_TIMEOUT_SECONDS` | `1800` | Inference timeout |
-| `STROKE_DEMO_DEEPISLES_USE_GPU` | `true` | Use GPU acceleration |
-| `STROKE_DEMO_TEMP_DIR` | `None` | Scratch directory for intermediate files |
-| `STROKE_DEMO_RESULTS_DIR` | `./results` | Directory for output files |
+| `STROKE_DEMO_DEEPISLES_FAST_MODE` | `true` | Use SEALS-only mode (faster, no FLAIR needed) |
+| `STROKE_DEMO_DEEPISLES_TIMEOUT_SECONDS` | `1800` | Inference timeout (30 minutes) |
+| `STROKE_DEMO_DEEPISLES_USE_GPU` | `true` | Use GPU acceleration (Docker mode only) |
+
+### Paths
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STROKE_DEMO_RESULTS_DIR` | `/tmp/stroke-results` | Directory for job result files |
+
+> **Note:** To control temp file location, use the native `TMPDIR` env var (Python's tempfile module respects it).
+
+### API Settings
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STROKE_DEMO_MAX_CONCURRENT_JOBS` | `1` | Max concurrent inference jobs (increase for multi-GPU) |
+| `STROKE_DEMO_FRONTEND_ORIGINS` | `["http://localhost:5173", "http://localhost:3000"]` | CORS allowed origins |
+| `STROKE_DEMO_BACKEND_PUBLIC_URL` | `None` | Public URL for file links (auto-detected if not set) |
+
+### Gradio UI (Legacy)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
 | `STROKE_DEMO_GRADIO_SERVER_NAME` | `0.0.0.0` | Gradio server host |
 | `STROKE_DEMO_GRADIO_SERVER_PORT` | `7860` | Gradio server port |
 | `STROKE_DEMO_GRADIO_SHARE` | `false` | Create public Gradio link |
+| `STROKE_DEMO_GRADIO_SHOW_ERROR` | `false` | Show full tracebacks (security: keep false in prod) |
 
 ## Using .env File
 
@@ -28,7 +61,7 @@ Create a `.env` file in the project root:
 ```bash
 STROKE_DEMO_LOG_LEVEL=DEBUG
 STROKE_DEMO_DEEPISLES_USE_GPU=false
-STROKE_DEMO_RESULTS_DIR=/data/results
+STROKE_DEMO_MAX_CONCURRENT_JOBS=2
 ```
 
 ## Programmatic Configuration

docs/guides/deployment.md

@@ -1,39 +1,125 @@
 # Deployment
 
-The demo is designed to be deployed on Hugging Face Spaces.
+The demo consists of two components deployed to Hugging Face Spaces:
+1. **Backend (FastAPI)**: Docker SDK Space running DeepISLES inference
+2. **Frontend (React SPA)**: Static SDK Space hosting the viewer UI
 
-## Hugging Face Spaces
+## Architecture
 
-1.  **Create a Space**: Go to [huggingface.co/spaces](https://huggingface.co/spaces) and create a new Space.
-    *   **SDK**: Docker (Recommended for custom dependencies) or Gradio
-    *   **Hardware**: GPU is recommended for DeepISLES inference.
+```
+┌──────────────────────────┐     ┌──────────────────────────┐
+│  Frontend HF Space       │     │  Backend HF Space        │
+│  (Static SDK)            │────▶│  (Docker SDK + GPU)      │
+│  React + NiiVue          │     │  FastAPI + DeepISLES     │
+└──────────────────────────┘     └──────────────────────────┘
+```
 
-2.  **Configure Dockerfile (if using Docker SDK)**:
-    Ensure the Dockerfile installs Python 3.11, uv, and pulls the DeepISLES image (or handles it appropriately, though Spaces might restrict running Docker-in-Docker).
+## Backend: HuggingFace Spaces (Docker SDK)
 
-    *Note*: Since DeepISLES runs as a Docker container, running it inside a HF Space (which is a container) requires Docker-in-Docker (DinD) or a compatible runtime. If DinD is not supported, you might need to adapt the inference to run directly in the python environment if possible (DeepISLES source code integration instead of Docker wrapper), but this project wraps the Docker image.
+### Prerequisites
+- HuggingFace account
+- Space with GPU allocation (T4-small minimum for inference)
 
-    **Standard Deployment (Gradio SDK)**:
-    The project includes `app.py` at the root for standard Gradio deployment. However, checking `requirements.txt` or `pyproject.toml` is needed.
+### Steps
 
-    For standard Gradio Spaces, you need to ensure `docker` command is available if you stick to the current architecture. Most HF Spaces do not support running `docker run`.
+1. **Create a Docker SDK Space**:
+   - Go to [huggingface.co/spaces](https://huggingface.co/spaces)
+   - SDK: **Docker** (required for custom dependencies)
+   - Hardware: **T4-small** or better (DeepISLES requires GPU)
 
-    **Alternative**: Use a VM (AWS/GCP/Azure) with Docker installed.
+2. **Push your code**:
+   ```bash
+   git remote add hf https://huggingface.co/spaces/YOUR_ORG/YOUR_SPACE
+   git push hf main
+   ```
 
-## Local Deployment
+3. **Configure Secrets** (Settings → Secrets):
+   - `HF_TOKEN`: Read-only token for gated datasets (optional)
+   - `STROKE_DEMO_FRONTEND_ORIGINS`: JSON array of allowed frontend origins
 
-1.  **Build/Pull**:
-    ```bash
-    docker pull isleschallenge/deepisles
-    ```
+### How It Works
 
-2.  **Run App**:
-    ```bash
-    uv run python -m stroke_deepisles_demo.ui.app
-    ```
+The Dockerfile:
+- Uses `isleschallenge/deepisles` as base (includes nnU-Net, SEALS, weights)
+- Installs demo package in `/home/user/demo` (avoids overwriting DeepISLES at `/app`)
+- Runs FastAPI on port 7860 (HF Spaces default)
+- Uses **direct invocation** (subprocess to conda env) instead of Docker-in-Docker
 
-## Environment Variables
+### Environment Variables
 
-Configure the deployment using environment variables (Secrets in HF Spaces):
--   `STROKE_DEMO_HF_TOKEN`: Read-only token for accessing datasets if private.
--   `STROKE_DEMO_DEEPISLES_USE_GPU`: Set to `false` if deploying on CPU-only instance.
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HF_SPACES` | `1` | Set by Dockerfile; triggers direct invocation mode |
+| `DEEPISLES_DIRECT_INVOCATION` | `1` | Set by Dockerfile; forces subprocess mode |
+| `STROKE_DEMO_FRONTEND_ORIGINS` | `[]` | JSON array of CORS-allowed origins |
+| `HF_TOKEN` | (none) | For gated datasets |
+
+Note: HuggingFace sets `SPACE_ID` automatically, but our detection uses `HF_SPACES` which we set explicitly in the Dockerfile for clarity.
+
+## Frontend: HuggingFace Spaces (Static SDK)
+
+### Steps
+
+1. **Create a Static SDK Space**:
+   - SDK: **Static**
+   - No hardware needed (static files only)
+
+2. **Build and deploy**:
+   ```bash
+   cd frontend
+   npm install
+   VITE_API_URL=https://your-backend.hf.space npm run build
+   # Copy dist/* to your Static Space
+   ```
+
+3. **Configure API URL**:
+   Set `VITE_API_URL` at build time to point to your backend Space.
+
+## Local Development
+
+### Backend Only
+```bash
+docker pull isleschallenge/deepisles
+uv sync --extra api
+uv run uvicorn stroke_deepisles_demo.api.main:app --reload --port 7860
+```
+
+### Frontend Only
+```bash
+cd frontend
+npm install
+VITE_API_URL=http://localhost:7860 npm run dev
+```
+
+### Full Stack
+```bash
+# Terminal 1: Backend
+uv run uvicorn stroke_deepisles_demo.api.main:app --reload --port 7860
+
+# Terminal 2: Frontend
+cd frontend && npm run dev
+```
+
+## Legacy: Gradio UI
+
+The project includes a legacy Gradio interface at `app.py`:
+```bash
+uv run python -m stroke_deepisles_demo.ui.app
+```
+
+This is provided for backwards compatibility but is not the primary deployment target.
+The Gradio UI connects directly to DeepISLES without the job queue.
+
+## Troubleshooting
+
+### "GPU not available" warning
+- Ensure your Space has GPU hardware allocated (T4-small minimum)
+- Check Space settings → Hardware
+
+### CORS errors in browser
+- Set `STROKE_DEMO_FRONTEND_ORIGINS` to include your frontend URL
+- Format: `'["https://your-frontend.hf.space"]'`
+
+### Inference timeouts
+- Default timeout is 30 minutes (`STROKE_DEMO_DEEPISLES_TIMEOUT_SECONDS`)
+- T4-small handles most cases; larger volumes may need more GPU memory

docs/guides/quickstart.md

@@ -6,6 +6,7 @@ Get started with stroke-deepisles-demo in 5 minutes.
 
 - Python 3.11+
 - Docker (for DeepISLES inference)
+- Node.js 18+ (for frontend development)
 - ~10GB disk space (for Docker image and datasets)
 
 ## Installation
@@ -15,8 +16,8 @@ Get started with stroke-deepisles-demo in 5 minutes.
 git clone https://github.com/The-Obstacle-Is-The-Way/stroke-deepisles-demo.git
 cd stroke-deepisles-demo
 
-# Install
-uv sync
+# Install Python dependencies (includes FastAPI for backend)
+uv sync --extra api
 ```
 
 ## Pull DeepISLES Docker Image
@@ -27,11 +28,19 @@ docker pull isleschallenge/deepisles
 
 ## Run Locally
 
-### Option 1: Gradio UI
+### Option 1: React SPA + FastAPI (Recommended)
+
+Full-featured web interface with 3D NIfTI visualization via NiiVue.
 
 ```bash
-uv run python -m stroke_deepisles_demo.ui.app
-# Open http://localhost:7860
+# Terminal 1: Start FastAPI backend
+uv run uvicorn stroke_deepisles_demo.api.main:app --reload --port 7860
+
+# Terminal 2: Start React frontend
+cd frontend
+npm install
+npm run dev
+# Open http://localhost:5173
 ```
 
 ### Option 2: CLI
@@ -54,6 +63,20 @@ print(f"Dice score: {result.dice_score:.3f}")
 print(f"Prediction: {result.prediction_mask}")
 ```
 
+### Option 4: Legacy Gradio UI
+
+The original Gradio interface is still available for backwards compatibility:
+
+```bash
+# Install Gradio extra (not included by default)
+uv sync --extra gradio
+
+uv run python -m stroke_deepisles_demo.ui.app
+# Open http://localhost:7860
+```
+
+Note: The Gradio UI does not support the async job queue or progress tracking.
+
 ## Configuration
 
 Set environment variables or create a `.env` file:

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

@@ -23,6 +23,7 @@ vi.mock("@niivue/niivue", () => ({
 }));
 
 describe("NiiVueViewer", () => {
+  // Note: URLs are simplified for component testing (actual API uses /files/{jobId}/{caseId}/)
   const defaultProps = {
     backgroundUrl: "http://localhost:7860/files/dwi.nii.gz",
   };

frontend/src/test/fixtures.ts

@@ -11,8 +11,9 @@ export const mockCasesResponse: CasesResponse = {
 };
 
 export const mockSegmentationResult: SegmentationResult = {
-  dwiUrl: "http://localhost:7860/files/dwi.nii.gz",
-  predictionUrl: "http://localhost:7860/files/prediction.nii.gz",
+  // URLs match actual API contract: /files/{jobId}/{caseId}/{filename}
+  dwiUrl: "http://localhost:7860/files/test-job-123/sub-stroke0001/dwi.nii.gz",
+  predictionUrl: "http://localhost:7860/files/test-job-123/sub-stroke0001/prediction.nii.gz",
   metrics: {
     caseId: "sub-stroke0001",
     diceScore: 0.847,

src/stroke_deepisles_demo/__init__.py

@@ -1,4 +1,4 @@
-"""stroke-deepisles-demo: HF datasets + DeepISLES + Gradio visualization."""
+"""stroke-deepisles-demo: DeepISLES stroke segmentation with React SPA + FastAPI backend."""
 
 __version__ = "0.1.0"
 

src/stroke_deepisles_demo/api/main.py

@@ -25,7 +25,7 @@ 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.config import get_settings
-from stroke_deepisles_demo.core.logging import get_logger
+from stroke_deepisles_demo.core.logging import get_logger, setup_logging
 
 logger = get_logger(__name__)
 
@@ -42,12 +42,16 @@ async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
     - Stop cleanup scheduler
     """
     # Startup
-    logger.info("Starting stroke segmentation API...")
     settings = get_settings()
 
+    # Apply log settings from environment (STROKE_DEMO_LOG_LEVEL, STROKE_DEMO_LOG_FORMAT)
+    setup_logging(settings.log_level, format_style=settings.log_format)
+
+    logger.info("Starting stroke segmentation API...")
+
     # Check for GPU availability (DeepISLES requires GPU)
     try:
-        import torch  # type: ignore[import-not-found]
+        import torch  # type: ignore[import-not-found,unused-ignore]
 
         if not torch.cuda.is_available():
             logger.warning(
@@ -105,7 +109,7 @@ app.add_middleware(
     CORSMiddleware,
     allow_origins=get_settings().frontend_origins,
     allow_credentials=False,  # Not needed - no cookies/auth
-    allow_methods=["GET", "POST", "HEAD"],  # HEAD for preflight checks
+    allow_methods=["GET", "POST", "OPTIONS"],  # OPTIONS for CORS preflight
     allow_headers=["Content-Type", "Range"],  # Range needed for partial content requests
     expose_headers=["Content-Range", "Content-Length", "Accept-Ranges"],  # NiiVue needs these
 )

src/stroke_deepisles_demo/api/routes.py

@@ -92,7 +92,15 @@ def create_segment_job(
         store = get_job_store()
         settings = get_settings()
 
-        # Validate case_id exists before creating job
+        # Pre-check concurrency limit before expensive validation
+        # This is a cheap check; the actual limit is enforced atomically below
+        if store.get_active_job_count() >= settings.max_concurrent_jobs:
+            raise HTTPException(
+                status_code=503,
+                detail="Server busy: too many active jobs. Please try again later.",
+            )
+
+        # Validate case_id exists (only after passing concurrency pre-check)
         valid_cases = list_case_ids()
         if body.case_id not in valid_cases:
             raise HTTPException(
@@ -105,6 +113,7 @@ def create_segment_job(
         backend_url = get_backend_base_url(request)
 
         # Atomic concurrency limit + job creation (prevents TOCTOU race)
+        # The pre-check above is just an optimization; this is the authoritative check
         job = store.create_job_if_under_limit(
             job_id, body.case_id, body.fast_mode, settings.max_concurrent_jobs
         )

src/stroke_deepisles_demo/cli.py

@@ -20,7 +20,7 @@ def main(argv: list[str] | None = None) -> int:
 
     # List command
     list_parser = subparsers.add_parser("list", help="List available cases")
-    list_parser.add_argument("--dataset", default=None, help="HF dataset ID (not used yet)")
+    list_parser.add_argument("--dataset", default=None, help="HF dataset ID or local path")
 
     # Run command
     run_parser = subparsers.add_parser("run", help="Run segmentation")
@@ -44,10 +44,10 @@ def main(argv: list[str] | None = None) -> int:
     return 0
 
 
-def cmd_list(args: argparse.Namespace) -> int:  # noqa: ARG001
+def cmd_list(args: argparse.Namespace) -> int:
     """Handle 'list' command."""
     try:
-        case_ids = list_case_ids()
+        case_ids = list_case_ids(source=args.dataset)
         print(f"Found {len(case_ids)} cases:")
         for i, cid in enumerate(case_ids):
             print(f"[{i}] {cid}")

src/stroke_deepisles_demo/core/config.py

@@ -76,8 +76,8 @@ class Settings(BaseSettings):
     log_format: Literal["simple", "detailed", "json"] = "simple"
 
     # HuggingFace
+    # Note: To control HF cache location, use HF_HOME env var (set in Dockerfile)
     hf_dataset_id: str = "hugging-science/isles24-stroke"
-    hf_cache_dir: Path | None = None
     hf_token: str | None = Field(default=None, repr=False)  # Hidden from logs
 
     # DeepISLES
@@ -85,17 +85,16 @@ class Settings(BaseSettings):
     deepisles_fast_mode: bool = True  # SEALS-only (ISLES'22 winner, no FLAIR needed)
     deepisles_timeout_seconds: int = 1800  # 30 minutes
     deepisles_use_gpu: bool = True
-    # Path to DeepISLES repo (for direct invocation mode)
-    deepisles_repo_path: Path | None = None
 
     # Paths
-    temp_dir: Path | None = None
+    # Note: To control temp location, use TMPDIR env var (Python tempfile respects it)
     # Results directory - MUST be /tmp for HF Spaces (only /tmp is writable)
     results_dir: Path = Path("/tmp/stroke-results")
 
     # API Settings
-    # Concurrency control
-    max_concurrent_jobs: int = 10
+    # Concurrency control - default to 1 for single-GPU safety (T4 has 16GB VRAM)
+    # Increase via STROKE_DEMO_MAX_CONCURRENT_JOBS if you have multiple GPUs
+    max_concurrent_jobs: int = 1
 
     # CORS - frontend origins allowed to call this API
     frontend_origins: list[str] = Field(default=["http://localhost:5173", "http://localhost:3000"])

src/stroke_deepisles_demo/data/__init__.py

@@ -31,11 +31,14 @@ def get_case(case_id: str | int) -> CaseFiles:
         return dataset.get_case(case_id)
 
 
-def list_case_ids() -> list[str]:
+def list_case_ids(source: str | None = None) -> list[str]:
     """List all available case IDs.
 
+    Args:
+        source: HuggingFace dataset ID or local path. If None, uses default from settings.
+
     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:
+    with load_isles_dataset(source=source) as dataset:
         return dataset.list_case_ids()

src/stroke_deepisles_demo/inference/deepisles.py

@@ -12,6 +12,7 @@ See:
 
 from __future__ import annotations
 
+import shutil
 import time
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
@@ -205,6 +206,24 @@ def _run_via_docker(
     # Find the prediction mask
     prediction_path = find_prediction_mask(output_dir)
 
+    # BUG-FIX: Ensure prediction is at expected URL location
+    # DeepISLES may write to a results/ subdirectory, but the API URL contract
+    # expects files directly in output_dir. Copy to expected location if needed.
+    if prediction_path.parent != output_dir and prediction_path.exists():
+        expected_path = output_dir / prediction_path.name
+        logger.debug(
+            "Copying prediction from %s to %s (URL path fix)",
+            prediction_path,
+            expected_path,
+        )
+        try:
+            shutil.copy2(prediction_path, expected_path)
+            prediction_path = expected_path
+        except OSError as e:
+            raise DeepISLESError(
+                f"Failed to copy prediction from {prediction_path} to {expected_path}: {e}"
+            ) from e
+
     elapsed = time.time() - start_time
 
     return DeepISLESResult(
@@ -220,6 +239,7 @@ def _run_via_direct_invocation(
     *,
     flair_path: Path | None,
     fast: bool,
+    timeout: float,
 ) -> DeepISLESResult:
     """
     Run DeepISLES via direct Python invocation.
@@ -234,9 +254,10 @@ def _run_via_direct_invocation(
     adc_path = input_dir / "adc.nii.gz"
 
     logger.info(
-        "Running DeepISLES via direct invocation: input=%s, fast=%s",
+        "Running DeepISLES via direct invocation: input=%s, fast=%s, timeout=%s",
         input_dir,
         fast,
+        timeout,
     )
 
     result = run_deepisles_direct(
@@ -245,6 +266,7 @@ def _run_via_direct_invocation(
         output_dir=output_dir,
         flair_path=flair_path,
         fast=fast,
+        timeout=timeout,
     )
 
     return DeepISLESResult(
@@ -275,7 +297,8 @@ def run_deepisles_on_folder(
         output_dir: Where to write results (default: input_dir/results)
         fast: If True, use single-model mode (faster, slightly less accurate)
         gpu: If True, use GPU acceleration (only affects Docker mode)
-        timeout: Maximum seconds to wait for inference (only affects Docker mode)
+        timeout: Maximum seconds to wait for inference (default: 1800, i.e. 30 min).
+            Docker mode accepts None for no timeout; direct mode converts None to 1800.
 
     Returns:
         DeepISLESResult with path to prediction mask
@@ -312,6 +335,7 @@ def run_deepisles_on_folder(
             output_dir=output_dir,
             flair_path=flair_path,
             fast=fast,
+            timeout=timeout if timeout is not None else 1800,
         )
     else:
         logger.info("Using Docker-based DeepISLES invocation")

src/stroke_deepisles_demo/inference/direct.py

@@ -3,7 +3,7 @@
 This module provides subprocess-based invocation of DeepISLES when running
 on HF Spaces. We use subprocess because:
 - DeepISLES runs in a conda env with Python 3.8
-- Our Gradio app requires Python 3.10+ for modern dependencies
+- Our FastAPI backend requires Python 3.11+ for modern dependencies
 - The two environments are incompatible, so we bridge via subprocess
 
 Usage:
@@ -155,7 +155,8 @@ def run_deepisles_direct(
     # Create output directory
     output_dir.mkdir(parents=True, exist_ok=True)
 
-    logger.info(
+    # Log paths at DEBUG to avoid exposing potentially sensitive path info at INFO
+    logger.debug(
         "Running DeepISLES via subprocess: dwi=%s, adc=%s, flair=%s, fast=%s",
         dwi_path,
         adc_path,
@@ -186,7 +187,7 @@ def run_deepisles_direct(
     if fast:
         cmd.append("--fast")
 
-    logger.info("Subprocess command: %s", " ".join(cmd))
+    logger.debug("Subprocess command: %s", " ".join(cmd))
 
     try:
         result = subprocess.run(
@@ -197,11 +198,13 @@ def run_deepisles_direct(
             cwd="/app",  # Run from DeepISLES directory
         )
 
-        # Log output
+        # Log verbose output at DEBUG to avoid log explosion
+        # DeepISLES produces extensive stdout/stderr that would overwhelm INFO logs
         if result.stdout:
-            logger.info("DeepISLES stdout:\n%s", result.stdout)
+            logger.debug("DeepISLES stdout:\n%s", result.stdout)
         if result.stderr:
-            logger.warning("DeepISLES stderr:\n%s", result.stderr)
+            # Log stderr at DEBUG unless it's a failure (handled below)
+            logger.debug("DeepISLES stderr:\n%s", result.stderr)
 
         # Check for failure
         if result.returncode != 0: