feat(#846): cache the LSP index + enforce the 30s cold-start SLA with auto-skip (clean redo of #860)

[don-petry]

Closes #846. Clean redo of #860, which went off the rails (377 commits, net −982 lines) and deleted unrelated/merged work; see the close note on #860.

Why a fresh PR

#860 was supposed to be a small, additive caching + SLA story but had drifted into deleting story #843's already-merged finding-verification step (scripts/lib/lsp-verification.sh + tests + the lsp_verification prompt wiring) and an unrelated 317-line script (scripts/dev-lead-fix-reviews.sh), carrying an ack-test-deletion label. Rather than untangle 377 commits, this re-implements only the in-scope #846 work on a fresh branch off current main.

What this does (additive only — 157 insertions, 5 deletions, 4 files)

File	Change
scripts/lib/token-metrics.sh	emit_lsp_coldstart_record — a discriminated kind:"lsp_cold_start" JSONL record (cold_start_ms, cache, skipped, sla_ms, reason) on the Token Cost Observatory channel so #844 can compute cold-start P50/P95. AC #2
scripts/setup-lsp-pilot.sh	Time the toolchain bring-up, normalize the actions/cache outcome to hit/miss/unknown, emit the record, and auto-skip wiring the MCP knobs when cold-start > LSP_COLD_START_SLA_MS (default 30000) via the existing "warn, don't fail" contract. Pure helpers (_lsp_sla_exceeded, _lsp_cache_status, _lsp_elapsed_ms, _lsp_now_ms); dispatcher source-guarded for unit testing. AC #2/#3
.github/workflows/pr-review.yml	SHA-pinned actions/cache (reusing the vetted v5.0.5 SHA) for ~/.local, keyed on OS + candidate + pinned tool versions + hashFiles of the Shell sources; threads cache-hit into the setup step. Opt-in behind LSP_PILOT_ENABLED. AC #1
tests/dev-lead/unit/test_lsp_coldstart_sla.bats	New 12-case suite: SLA decision, cache-status, elapsed clamp, metric record + no-op, end-to-end warm/auto-skip/degraded paths, workflow cache wiring.

Scope guarantees

• No deletions of [Phase 2] Add the LSP finding-verification step to the deep/audit pr-review tiers #843 or anything unrelated — lsp-verification.sh, its tests, and dev-lead-fix-reviews.sh are untouched. No ack-test-deletion needed.
• Off-pilot = byte-for-byte unchanged: the cache step + setup are gated behind LSP_PILOT_ENABLED, and token_report.sh already filters to (.kind // "token_usage") == "token_usage", so the new record is excluded from cost aggregation with no change to token_report.sh.
• Cold-start = toolchain bring-up (install / cache-restore → ready) — the honest shell-observable proxy (first-query indexing happens inside the claude subprocess); it's exactly what the index cache eliminates. Documented inline.

Tests

• tests/dev-lead/unit/test_lsp_coldstart_sla.bats — 12/12 green.
• Regression: test_lsp_pilot.bats ([Phase 2] Wire candidate LSP-MCP server(s) into the pr-review runtime — config, install, tier gating #842) 14/14, test_token_metrics.bats 42/42.
• shellcheck --severity=warning -x clean; pr-review.yml validates as YAML.

🤖 Generated with Claude Code

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

@don-petry, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 57 minutes and 42 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6c4d4fdf-9c8c-4304-970b-ac7cd28327e6

📥 Commits

Reviewing files that changed from the base of the PR and between 855dd11 and 0209227.

📒 Files selected for processing (4)

• .github/workflows/pr-review.yml
• scripts/lib/token-metrics.sh
• scripts/setup-lsp-pilot.sh
• tests/dev-lead/unit/test_lsp_coldstart_sla.bats

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/lsp-coldstart-sla-846

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-06-25T03:57:43Z.

[gemini-code-assist]

Code Review

This pull request implements LSP cold-start SLA tracking and index-cache wiring, adding helper functions to measure elapsed time, check SLA compliance, and log cold-start metrics, along with a comprehensive suite of unit tests. The review feedback suggests several robustness improvements: validating the number of positional parameters in emit_lsp_coldstart_record to prevent unbound variable crashes under set -u, using %.0f in awk to avoid integer overflow when formatting epoch milliseconds, and replacing a fragile integer validation check with a cleaner case statement pattern.

[don-petry]

Dev-Lead — waiting on PR blockers (intent: fix-reviews)

PR: #922
No changes were committed, but the PR still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews). The retry cron will re-attempt automatically. Next attempt after: 2026-06-25T03:37:53Z

[don-petry]

Dev-Lead — review-changes (no-changes)

No changes were needed for this PR.

[donpetry-bot]

Automated review — APPROVED ✓

Risk: MEDIUM
Reviewed commit: 173cac17b08a260de94f66a9c22a868e18121d1b
Review mode: triage-approved (single reviewer)

Summary

Additive Phase-2 LSP-pilot change (story #846, epic #839): adds index caching + a 30s cold-start SLA with graceful auto-skip. 4 files, +323/-5; the 5 deletions are just the dispatcher case being wrapped in a source-guard (no behavior removed). New work is a SHA-pinned actions/cache step (reusing the already-vetted 27d5ce7…v5.0.5 SHA also used at pr-review.yml:211), a set -u-safe emit_lsp_coldstart_record on the existing JSONL channel, pure timing/SLA helpers, and a 12+-case bats suite. Off-pilot runs are byte-for-byte unchanged (everything gated behind LSP_PILOT_ENABLED). Triage tier's low-risk assessment confirmed.

Linked issue analysis

Closes #846. Substantively addressed: AC #1 (pr-review.yml SHA-pinned actions/cache for ~/.local, keyed on OS+candidate+pinned tool versions+hashFiles, threads cache-hit into setup), AC #2 (discriminated kind:"lsp_cold_start" record so #844 can compute P50/P95; token_report.sh's (.kind // "token_usage")=="token_usage" filter excludes it from cost aggregation), AC #3 (over-SLA bring-up auto-skips LSP wiring via the existing warn-don't-fail contract, exit 0). Deliberately scoped clean of #860's accidental deletions — #843's verification step and dev-lead-fix-reviews.sh are untouched; no ack-test-deletion needed.

Findings

No blocking findings.

• Workflow security: new actions/cache is SHA-pinned to the same vetted SHA already in use at pr-review.yml:211 (not a guessed pin), gated behind LSP_PILOT_ENABLED, scoped to ~/.local. No untrusted action, no injection surface. GitHub cache scoping isolates per-branch caches, so cross-PR cache poisoning is mitigated.
• Robustness (advisory): all three gemini-code-assist comments are resolved in commit 8836b8e — awk %.0f avoids 32-bit epoch-ms overflow; emit_lsp_coldstart_record is set -u-safe (positional defaults rather than gemini's suggested arg-count guard — equivalent, matches emit_token_record house style); _lsp_sla_exceeded uses a clean case check. SonarCloud quality gate passed (0 new issues).
• Downstream: pr-review.yml is consumed by 5 repos, but the change is purely additive + opt-in, so consumers not setting LSP_PILOT_ENABLED=true are unaffected.
• Secret scan: run_secret_scanning MCP tool not available in this environment; gitleaks CI check passed. No secrets in diff.

CI status

All required checks green. Lint/ShellCheck/bats/unit-tests/CodeQL(actions,python)/SonarCloud/AgentShield/Holdout-Guard/Test-Deletion-Guard/Secret-scan(gitleaks) all SUCCESS; dependency-audit ecosystem jobs and dependabot SKIPPED (expected). Advisory bots: CodeRabbit APPROVED at head 173cac1; gemini comments addressed; Codex/CodeRabbit earlier rate-limit notices were on older SHAs. mergeStateStatus BLOCKED only due to the org-leads human-review gate (REVIEW_REQUIRED), not a failing check.

---

Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.

[don-petry]

Dev-Lead — waiting on PR blockers (intent: review-changes)

PR: #922
No changes were committed, but the PR still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews). The retry cron will re-attempt automatically. Next attempt after: 2026-06-25T06:23:41Z

[don-petry]

Note

@don-petry I reviewed this PR and no code changes were needed, but it still has blocking checks or reviews (failing or cancelled checks, or changes-requested reviews), so I cannot mark it done yet. I'll re-check automatically.
Next attempt after: 2026-06-25T06:23:41Z

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[donpetry-bot]

Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-06-25T06:57:58Z.