fix: add dry-run discoverability safe repair

[ai-ag2026]

Thinking Path

The discoverability audit is intentionally read-only, but its findings identified two deterministic cleanup classes: stale persisted WebUI-as-CLI flags and WebUI-origin state.db rows with messages but no sidecar/index entry. Operators need a safe routine that plans those repairs by default and only mutates state with an explicit backup directory.

What Changed

• Adds repair_session_discoverability() with default dry-run behavior.
• Plans deterministic repairs from the existing audit findings.
• Requires backup_dir for apply mode.
• Clears stale is_cli_session=true from WebUI sidecars and _index.json entries.
• Materializes messageful WebUI state.db rows into sidecars and index metadata using the existing state-db sidecar conversion path.
• Adds python -m api.session_discoverability --repair-safe as a dry-run CLI; --apply --backup-dir <dir> is required for mutation.
• Adds regression coverage for dry-run no-mutation, backup-required apply, backup-backed apply, and CLI dry-run behavior.
• Updates the changelog.

Why It Matters

This turns the audit's actionable but operator-heavy follow-up into a controlled routine. It still defaults to no mutation, so users can inspect the plan before touching session files or state.db-derived recovery state.

Contract Routing

Task type: runtime/session metadata repair tooling.
Touched areas: api.session_discoverability, session sidecars, _index.json, state-db-derived sidecar materialization.
Relevant public docs:

• AGENTS.md
• CONTRIBUTING.md
• docs/CONTRACTS.md
• docs/rfcs/webui-run-state-consistency-contract.md
  Scope boundaries: no live repair route, no automatic startup repair, no deletion/archive of unsafe rows, no service restart.
  Evidence needed before claiming done: regression tests for dry-run/apply gates plus adjacent recovery/discoverability tests.

Verification

• python3 -m pytest tests/test_session_discoverability_repair.py -q
• python3 -m pytest tests/test_session_discoverability_repair.py tests/test_session_discoverability_audit.py tests/test_session_recovery_api.py -q
• python3 -m pytest tests/test_session_discoverability_repair.py tests/test_session_discoverability_audit.py tests/test_session_recovery_api.py tests/test_session_db_sidecar_reconciliation.py -q
• python3 -m py_compile api/session_discoverability.py api/session_recovery.py
• Added-line public marker scan: 0 hits

Risks / Follow-ups

• The routine can mutate session sidecars/index files only in --apply mode and only with backups.
• state_db_messageful_missing_sidecar materialization is intentionally limited to WebUI-origin rows with messages; empty/orphan rows remain manual-review territory.
• Live use should still be operator-triggered after inspecting dry-run output and choosing a backup directory.

Model Used

AI-assisted by OpenAI Codex GPT-5.5 via Hermes/TARS, using local tests and git/GitHub CLI tooling.

[nesquena-hermes]

Shipped in v0.51.154 / Release DZ (stage-batch36, commit 6267716). Thanks for the contribution!