feat: enhance Docker debugging setup with readiness checks and improved cleanup in entrypoint script

Author: devlux76

CORTEX-DESIGN-PLAN-TODO.md

@@ -94,12 +94,28 @@ Legend: `Implemented`, `Partial`, `Missing`
 | Storage contracts and persistence schema | Implemented | `core/types.ts`, `storage/OPFSVectorStore.ts`, `storage/IndexedDbMetadataStore.ts`, `tests/Persistence.test.ts` | Current tests are Node-lane with mocked browser APIs. |
 | Model-derived numeric governance | Implemented | `core/ModelProfile.ts`, `core/ModelDefaults.ts`, `core/ModelProfileResolver.ts`, `Policy.ts`, `scripts/guard-model-derived.mjs` | Guard command enforced by `npm run guard:model-derived`. |
 | Adaptive provider resolver infrastructure | Partial | `embeddings/ProviderResolver.ts`, `embeddings/EmbeddingRunner.ts` | Real providers not yet wired; dummy provider baseline exists. |
-| Browser/Electron runtime-realism lanes | Partial | `playwright.config.mjs`, `runtime/harness/index.html`, `tests/runtime/browser-harness.spec.mjs`, `tests/runtime/electron-harness.spec.mjs`, `.vscode/launch.json`, `.vscode/tasks.json`, `docker/electron-debug/Dockerfile`, `docker-compose.electron-debug.yml` | Browser lane passes; Electron host-shell runs can `SIGSEGV` in constrained contexts. Dockerized attach flow is now available, but CI/runtime-context policy is still pending. |
+| Browser/Electron runtime-realism lanes | Partial | `playwright.config.mjs`, `runtime/harness/index.html`, `tests/runtime/browser-harness.spec.mjs`, `tests/runtime/electron-harness.spec.mjs`, `.vscode/launch.json`, `.vscode/tasks.json`, `docker/electron-debug/Dockerfile`, `docker-compose.electron-debug.yml` | Browser lane passes; Electron host-shell runs can `SIGSEGV` in constrained contexts. Dockerized attach flow is validated for sandbox-isolated debugging, while CI/runtime-context policy is still pending. |
 | Hippocampus ingest orchestrator | Missing | (planned module) | No text chunking -> embed -> persist orchestration path yet. |
 | Cortex retrieval and coherence path | Missing | (planned module) | Ranking stack and open-path solver not yet implemented. |
 | Daydreamer consolidation loop | Missing | (planned module) | Idle scheduling and recalc loop not yet implemented. |
 | Crypto signing and verification helpers | Missing | (planned module `core/crypto`) | Entity fields exist in `core/types.ts`, helper module pending. |
 
+### 0.6 Night Handoff (2026-03-12)
+
+Where we are now:
+1. Browser runtime lane is passing.
+2. Dockerized Electron attach lane is validated for sandbox-isolated debugging.
+3. Host-shell Electron remains context-sensitive and can still fail with `SIGSEGV` in constrained shells.
+4. Docker lane currently runs software rendering and is not the final GPU-realism gate.
+
+Tomorrow's code-first sequence:
+1. Implement `embeddings/TransformersEmbeddingBackend.ts` for `webnn/webgpu/wasm`.
+2. Implement `embeddings/OrtWebglEmbeddingBackend.ts` for explicit `webgl` fallback.
+3. Expand resolver wiring in `embeddings/ProviderResolver.ts` so real providers participate in capability + benchmark selection.
+4. Add strict Red -> Green tests for new provider registration and selection behavior under capability constraints.
+5. Implement first `hippocampus` ingest orchestration entry point using resolved `ModelProfile` values.
+6. Implement first `cortex` retrieval orchestration entry point with deterministic baseline ordering.
+
 ## 1. Design
 
 ### 1.1 Product contract

PROJECT-EXECUTION-PLAN.md

@@ -90,14 +90,41 @@ Completed in this pass:
    - short `docker compose ... up` smoke with forced recreate + teardown
    - ready markers observed (`harness ready`, main inspector `9230`, renderer debugger `9222`)
    - no `SIGSEGV` observed inside container during smoke window
+23. Host-side VS Code attach behavior is now validated for the Docker lane:
+   - user desktop debug run showed both endpoints active
+   - `Debugger attached.` observed for attach sessions during `Electron: Docker Main + Renderer`
+24. Hardened Docker startup sequencing to avoid attach races:
+   - `docker/electron-debug/entrypoint.sh` now waits for live debugger endpoints before emitting ready markers
+   - `docker/electron-debug/Dockerfile` now includes `curl` for readiness probes
 
 Open items carried to next pass:
 1. Wire resolved `ModelProfile` into first concrete ingest/query orchestrator path.
 2. Add real embedding providers (ONNX/Transformers/WebNN/WebGPU/WebGL/WASM) as candidates for the resolver.
-3. Validate full VS Code host attach cycle against the Docker lane (`Electron: Docker Main + Renderer`) and codify it as the runtime-electron context contract when host-shell runs are unstable.
+3. Codify Docker lane as the default sandbox-isolated Electron debugging contract and document when host-shell Electron is still required.
 4. Define CI prerequisites for the chosen runtime-electron context (binary + graphics/runtime assumptions) and enforce one canonical gate.
 5. Implement first Hippocampus/Cortex vertical slice on top of runtime harness lanes.
 
+### Night Handoff Note (2026-03-12)
+
+Where we are now:
+1. Docker Electron debug lane is stable for sandbox-isolated debugging and VS Code attach.
+2. Host-shell Electron remains environment-sensitive and can still fail with `SIGSEGV` in constrained contexts.
+3. Browser runtime lane is validated and should remain part of the merge confidence path.
+4. Docker lane runs software rendering, so it is a debugger-stability lane rather than final GPU-realism proof.
+
+Tomorrow's first coding steps:
+1. Add failing tests for real-provider registration + capability-driven selection in embeddings runtime.
+2. Implement `embeddings/TransformersEmbeddingBackend.ts` and wire it into resolver candidates.
+3. Implement `embeddings/OrtWebglEmbeddingBackend.ts` and wire explicit `webgl` fallback path.
+4. Implement first `Hippocampus` ingest entry point with profile-derived defaults.
+5. Implement first `Cortex` retrieval entry point with deterministic baseline ordering.
+
+Tomorrow startup commands:
+1. `npm run test:unit`
+2. `npm run test:browser`
+3. `npm run docker:electron:up`
+4. VS Code debug: `Electron: Docker Main + Renderer`
+
 ### Documentation Synchronization Protocol (Required)
 
 At the end of every implementation pass, update docs in this order:
@@ -265,10 +292,10 @@ Planned commands to add in later passes:
 
 1. Blocker A - File path: `scripts/electron-harness-main.mjs`, `.vscode/launch.json`, `scripts/run-electron-runtime-smoke.mjs`
 2. Blocker A - Failure symptom: Electron exits with `SIGSEGV` (`139`) in this tool-executed terminal context for both desktop-style and headless/software-style launches, despite Electron being installed and harness server reachability.
-3. Blocker A - Next action: run the containerized attach flow (`npm run docker:electron:up` + `Electron: Docker Main + Renderer`) and treat host-shell crashes as environment-limited unless reproducible in the Docker lane.
-4. Blocker B - File path: `.vscode/launch.json`, `.vscode/tasks.json`, `docker-compose.electron-debug.yml`
-5. Blocker B - Failure symptom: Docker lane now builds and starts cleanly, but host-side VS Code attach/breakpoint workflow against that lane has not yet been validated in-session.
-6. Blocker B - Next action: run `Electron: Docker Main + Renderer` from VS Code, verify main + renderer breakpoint binding, then lock CI/runtime-electron contract to that validated context.
+3. Blocker A - Next action: use the Docker attach flow (`Electron: Docker Main + Renderer`) as the default debugging lane and treat host-shell crashes as environment-limited unless reproducible in Docker.
+4. Blocker B - File path: `docker/electron-debug/Dockerfile`, `docker/electron-debug/entrypoint.sh`, runtime lane policy docs
+5. Blocker B - Failure symptom: Docker lane runs under software rendering (`webgpu`/`webgl` unavailable or blocklisted), so it is strong for debugger stability but not a full GPU-realism proxy.
+6. Blocker B - Next action: keep Docker as debug isolation lane and define a separate GPU-capable runtime-electron gate context for realism-sensitive verification.
 
 ## Known Hardcoded Hotspots To Clean First
 

README.md

@@ -18,7 +18,7 @@ Current implementation snapshot:
 2. Model-profile-driven numeric ownership is implemented and guarded by `npm run guard:model-derived`.
 3. Adaptive embedding resolver infrastructure exists, but real providers are still being wired.
 4. Runtime harness and browser lane are implemented (`npm run dev:harness`, `npm run test:browser`).
-5. Electron lane is wired but runtime-context-sensitive on host shells; a containerized debug lane is now available to isolate from editor/runtime sandbox effects (`npm run docker:electron:up`, then attach with `Electron: Docker Main + Renderer`).
+5. Electron lane is runtime-context-sensitive on host shells; the containerized debug lane is now validated as the preferred sandbox-isolated debugging path (`Electron: Docker Main + Renderer`).
 6. Hippocampus/Cortex/Daydreamer orchestration layers remain the primary vertical-slice gap.
 
 Current delivery priorities (P0):
@@ -50,6 +50,20 @@ Docker debug quick start:
 1. In VS Code Run and Debug, launch `Electron: Docker Main + Renderer` (this auto-runs `docker:electron:up`).
 2. If you need manual control, start the lane with `npm run docker:electron:up` and stop it with `npm run docker:electron:down`.
 
+Expected container log noise (non-fatal):
+1. `dbus/bus.cc` connection warnings are expected in slim container environments without a system DBus daemon.
+2. `WebGL2 blocklisted` is expected with software rendering in Xvfb; this does not imply Electron main-process crash.
+
+Night handoff note (2026-03-12):
+1. Runtime debugging status: `Electron: Docker Main + Renderer` is the validated sandbox-isolated debug path.
+2. Host-shell context status: local host-shell Electron runs can still fail with `SIGSEGV`; treat Docker attach as source of truth for debugger stability.
+3. Runtime realism status: Docker lane is software-rendered and is not the final GPU-realism gate.
+4. Tomorrow kickoff step 1: add real provider adapters in embeddings runtime (`Transformers` path for `webnn/webgpu/wasm`, explicit ORT path for `webgl`).
+5. Tomorrow kickoff step 2: add failing-first tests for provider registration and selection behavior, then implement to green.
+6. Tomorrow kickoff step 3: build first `Hippocampus` ingest slice with resolved model profile values.
+7. Tomorrow kickoff step 4: build first `Cortex` retrieval slice with deterministic baseline ordering.
+8. First commands for tomorrow: `npm run test:unit`, `npm run test:browser`, then `npm run docker:electron:up` with VS Code debug `Electron: Docker Main + Renderer`.
+
 Docs note:
 1. Numeric examples in design docs are illustrative unless explicitly sourced from model metadata.
 2. Legacy sketch docs were retired; canonical architecture lives in `CORTEX-DESIGN-PLAN-TODO.md` and execution sequencing lives in `PROJECT-EXECUTION-PLAN.md`.

docker/electron-debug/Dockerfile

@@ -4,6 +4,7 @@ ENV DEBIAN_FRONTEND=noninteractive
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
     ca-certificates \
+    curl \
     fonts-liberation \
     libasound2 \
     libatk-bridge2.0-0 \

docker/electron-debug/entrypoint.sh

@@ -9,6 +9,11 @@ MAIN_INSPECT_PORT="${CORTEX_DOCKER_MAIN_INSPECT_PORT:-9230}"
 RENDERER_DEBUG_PORT="${CORTEX_DOCKER_RENDERER_DEBUG_PORT:-9222}"
 
 cleanup() {
+  if [[ -n "${ELECTRON_PID:-}" ]] && kill -0 "${ELECTRON_PID}" 2>/dev/null; then
+    kill "${ELECTRON_PID}" >/dev/null 2>&1 || true
+    wait "${ELECTRON_PID}" 2>/dev/null || true
+  fi
+
   if [[ -n "${HARNESS_PID:-}" ]] && kill -0 "${HARNESS_PID}" 2>/dev/null; then
     kill "${HARNESS_PID}" >/dev/null 2>&1 || true
     wait "${HARNESS_PID}" 2>/dev/null || true
@@ -37,8 +42,29 @@ if [[ "${ready}" -ne 1 ]]; then
 fi
 
 echo "[docker-electron] harness ready at ${HARNESS_URL}"
-echo "[docker-electron] main inspector: 0.0.0.0:${MAIN_INSPECT_PORT}"
-echo "[docker-electron] renderer debugger: 0.0.0.0:${RENDERER_DEBUG_PORT}"
+
+wait_for_main_debugger() {
+  for _attempt in $(seq 1 200); do
+    if curl -fsS "http://127.0.0.1:${MAIN_INSPECT_PORT}/json/version" >/dev/null 2>&1; then
+      return 0
+    fi
+    sleep 0.1
+  done
+  return 1
+}
+
+wait_for_renderer_debugger() {
+  for _attempt in $(seq 1 200); do
+    if curl -fsS "http://127.0.0.1:${RENDERER_DEBUG_PORT}/json/version" >/dev/null 2>&1; then
+      return 0
+    fi
+    if curl -fsS "http://127.0.0.1:${RENDERER_DEBUG_PORT}/json/list" >/dev/null 2>&1; then
+      return 0
+    fi
+    sleep 0.1
+  done
+  return 1
+}
 
 env \
   HARNESS_URL="${HARNESS_URL}" \
@@ -54,4 +80,21 @@ env \
     --inspect="0.0.0.0:${MAIN_INSPECT_PORT}" \
     --remote-debugging-address=0.0.0.0 \
     --remote-debugging-port="${RENDERER_DEBUG_PORT}" \
-    "${ROOT_DIR}/scripts/electron-harness-main.mjs"
+    "${ROOT_DIR}/scripts/electron-harness-main.mjs" &
+
+ELECTRON_PID=$!
+
+if ! wait_for_main_debugger; then
+  echo "[docker-electron] main inspector failed to become ready on 0.0.0.0:${MAIN_INSPECT_PORT}"
+  exit 1
+fi
+
+if ! wait_for_renderer_debugger; then
+  echo "[docker-electron] renderer debugger failed to become ready on 0.0.0.0:${RENDERER_DEBUG_PORT}"
+  exit 1
+fi
+
+echo "[docker-electron] main inspector: 0.0.0.0:${MAIN_INSPECT_PORT}"
+echo "[docker-electron] renderer debugger: 0.0.0.0:${RENDERER_DEBUG_PORT}"
+
+wait "${ELECTRON_PID}"