fix(control-plane): @mention re-reviews must always create a task (#137)

[stephane-segning]

1. Summary

This PR changes:

• Adds create_explicit_task in db.rs — an always-lands-a-row, race-free insert for the @mention path that folds the next run_epoch into the INSERT (COALESCE(MAX(run_epoch), -1) + 1 over the same columns as the idempotency unique index, using the REAL command_text).
• Changes handle_issue_comment (webhook.rs) to parse the instruction once and use create_explicit_task; drops the buggy next_run_epoch(…, "review", …) call from this path.
• Removes the now-unused next_run_epoch and its test; adds two #[sqlx::test] regression tests.

It solves:

• A confirmed prod bug for source-of-truth ticket [Epic]: Trustworthy review agent v2 — native loop, richer findings, conversational commands, observability & feedback #137 : explicit @lightbridge-assistant review re-requests were silently dropped.

---

2. Intent

The intent of this PR is:

An @mention is an explicit human command — it must ALWAYS create a task. The old code computed run_epoch with the hardcoded literal "review" but created the task with the REAL command_text (e.g. "review this"). The idempotency unique index keys on the real command_text, so the epoch was computed against the wrong group, returned the same value every time, and a repeated identical mention on an unchanged head collided → create_task returned Ok(None) → logged "review task already exists; skipping (idempotent)" → no task, no review. Varying the wording sidestepped it (different command_text), which is why it was intermittent. There was ALSO a non-atomic TOCTOU race: next_run_epoch then create_task were separate statements, so two near-simultaneous deliveries could compute the same epoch and one was dropped. True webhook redeliveries are already deduped upstream by the github_deliveries delivery-id PRIMARY KEY, so content-idempotency on the comment path adds nothing and only causes this bug.

Prod evidence: the "review task already exists; skipping (idempotent)" log on a legitimate re-request, observed on PR izhub#198.

---

3. Scope

In Scope

• services/control-plane/src/db.rs — new create_explicit_task; remove next_run_epoch + its test; add regression tests.
• services/control-plane/src/http/webhook.rs — comment/@mention path uses the new explicit insert.

Out of Scope

• The auto pull_request (opened) path is unchanged — it keeps content-idempotency via create_task so GitHub's duplicate opened+synchronize deliveries for one head still collapse to a single review.
• agent-runner, internal.rs status/detail handling, migrations, and web (separate concurrent PRs); deployment / ai-helm.

---

4. Verification

I verified this change by:

• Running automated tests
• Running manual tests
• Checking logs
• Checking metrics
• Testing error cases
• Testing permissions/security behavior
• Testing rollback or failure behavior, if relevant

Commands run:

cargo fmt -p control-plane -- --check
cargo clippy -p control-plane --all-targets -- -D warnings
DATABASE_URL=postgresql://lightbridge:lightbridge@localhost:5432/lightbridge cargo test -p control-plane

Results:

$ cargo fmt -p control-plane -- --check
(no output — formatting OK)

$ cargo clippy -p control-plane --all-targets -- -D warnings
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.38s   (no warnings)

$ cargo test -p control-plane
test db::tests::explicit_mention_always_creates_a_task_at_the_next_epoch ... ok
test db::tests::auto_review_collapses_duplicate_opened_and_synchronize ... ok
test result: ok. 61 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out; finished in 6.10s

The DB tests ran against a local pgvector at postgresql://lightbridge:lightbridge@localhost:5432/lightbridge (the repo CI DB).

---

5. Screenshots / Evidence

Add evidence here:

• Logs: prod log line "review task already exists; skipping (idempotent)" on a legitimate re-request (PR izhub#198).
• New regression test explicit_mention_always_creates_a_task_at_the_next_epoch proves two identical "review this" mentions on the same (repo, target, head) now create TWO tasks at epochs N and N+1.
• New regression test auto_review_collapses_duplicate_opened_and_synchronize proves the auto path still collapses a duplicate to ONE task.

---

6. Risk Assessment

Risk level:

• Low
• Medium
• High

Potential risks:

• The comment path no longer content-dedupes. This is intentional: redeliveries are deduped upstream by the github_deliveries PK, so a genuine re-request now always lands.

Mitigation:

• Auto opened path is untouched and still deduped; new tests cover both paths.

---

7. AI Usage Declaration

AI was used for:

• Understanding existing code
• Generating code
• Generating tests
• Reviewing the diff
• Not used

Human verification:

• I understand every meaningful change in this PR
• I checked generated code manually
• I checked generated tests manually
• I removed unsupported AI assumptions
• I accept responsibility for this PR

---

8. Reviewer Focus

Please focus your review on:

• Correctness
• Architecture
• Security
• Performance
• Tests
• Maintainability
• Product intent
• Edge cases

🤖 Generated with 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.

[github-actions]

✅ AI Governance check passed

This PR declares AI usage, references a source of truth, and provides verification evidence. Thank you.

[gemini-code-assist]

Code Review

This pull request introduces a dedicated path for explicit @mention commands (create_explicit_task) to prevent them from being content-deduplicated, ensuring manual re-requests are always processed. It replaces the separate next_run_epoch query with an atomic subquery inside the INSERT statement. The review feedback identifies a potential concurrency race condition in create_explicit_task under the default READ COMMITTED isolation level, where concurrent inserts could compute the same run_epoch and trigger a unique constraint violation. A retry mechanism is suggested to handle this scenario robustly.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[lightbridge-assistant]

Lightbridge review

The change correctly implements the core intent — explicit @mention tasks always land a row, never silently dropped by content-idempotency — and the SQL subquery is a clean design for atomic epoch computation. The test coverage is good. However, there is a P0 concurrency bug: two simultaneous create_explicit_task calls for the same natural key can compute the same epoch and either collide on a unique constraint (losing one task with an error) or silently produce duplicate epochs, contradicting the "no TOCTOU window" claim. This needs a retry loop or advisory lock. There are also P1 issues with a reused github_delivery_id in the test (may hit a UK) and silently swallowed errors in create_explicit_review_task.

---

🤖 AI-generated review — treat it as untrusted, verify before acting; a human owns the final decision (AI governance).