fix(gui): harden NLX runtime env integrity + diagnose handling

[Doogie201]

Summary

Fixes GUI/runtime breakage caused by metadata contamination in generated environments and tightens NLX diagnose response handling so degraded health is surfaced correctly instead of EXEC_ERROR.

Root Cause (Evidence-backed)

1. AppleDouble sidecar files (._*) polluted generated paths on external-drive workflows, breaking env/runtime assumptions.
2. /api/nlx/run diagnose path treated valid nonzero health output as execution failure.
3. Local pre-commit ShellCheck hook in baseline config was non-functional in this worktree context (openBinaryFile), blocking safe commits.

What Changed (minimal scope)

• Added scripts/env-integrity.sh (check|scrub) for AppleDouble detection/scrubbing in generated dirs and source-scope guard.
• Hardened scripts/dev-setup.sh with:
  • --repair-env
  • pre/post metadata scrub
  • deterministic env integrity checks
  • auto-rebuild trigger for contaminated/invalid .venv
• Updated GUI sanitizer canonical fix command to bash scripts/dev-setup.sh --repair-env.
• Updated NLX service diagnose handling to coerce valid health-output nonzero diagnose into structured success (errorType=none) while preserving parse failure handling.
• Added/updated tests:
  • dashboard/src/engine/__tests__/nlxService.test.ts (new)
  • dashboard/src/engine/__tests__/nlxErrorSanitizer.test.ts
• Fixed pre-commit root cause:
  • switched ShellCheck hook to local system hook in .pre-commit-config.yaml
  • addressed ShellCheck findings in scripts/env-integrity.sh

Downstream Impact / Dependency Analysis

• Python/Poetry runtime: guarded by poetry run python -I -W ignore -c 'import pydantic, typer' in env-integrity checks.
• Dashboard runtime: build/test unchanged semantically; new robustness around diagnose envelope interpretation.
• Pre-commit reliability: ShellCheck now executes in this environment without path-resolution failures.
• CI compatibility: no secrets, no hard-coded mount paths, no endpoint additions.

Verification (Operator-grade receipts)

Local receipt bundle: /tmp/nlx-pr-closeout-20260302-041533

Key receipts:

• 06_local_verification_and_migration_sim.txt
  • bash scripts/dev-setup.sh ✅
  • bash scripts/env-integrity.sh check ✅
  • poetry run nlx list-tasks ✅
  • poetry run nlx diagnose (degraded health line; exit 1 expected) ✅
  • npm --prefix dashboard run -s build ✅
  • npm --prefix dashboard run -s test ✅ (200 tests)
  • migration simulation from /tmp ✅
• 07b_dashboard_api_runtime_probe_repeat.txt
  • /api/nlx/run diagnose returns ok:true, badge:DEGRADED, errorType:none ✅
  • /api/nlx/run listTasks returns success ✅
• 08b_shellcheck_repro_exact.txt + 08c_precommit_root_cause_fix_validation.txt
  • pre-fix hook failure reproduced
  • post-fix ShellCheck/shfmt pass ✅

Risk

• risk:med
• Surface touched: dashboard NLX command envelope + dev/setup guardrails + pre-commit shell lint execution.

Security / Compliance

• No secrets added.
• No force-merge behavior.
• No destructive cleanup operations introduced.
• No hard-coded mount-specific paths added.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 32261ca95a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Fail fast when metadata scan command errors

Both check_repo_metadata and scrub_repo_metadata treat any rg failure as “no matches” by resetting the captured output to empty, so if rg is missing or errors, the script reports the source scope as clean and exits successfully. In that environment bash scripts/env-integrity.sh check|scrub (and therefore dev-setup.sh) silently disables the AppleDouble guardrail instead of failing, which defeats the integrity check it was added to enforce.

Useful? React with 👍 / 👎.