fix(witan): task_claim backs off between CAS retries, reports contention instead of raising raw

[blarghmatey]

What are the relevant tickets?

Fixes tk-task-claim-exhausts-its-3-attempt-no-backoff-cas-674414 (witan work-coordination graph).

Description (What does it do?)

Recent sessions were hitting a raw internal error when calling task_claim:

write authority 'table_head:node:Task' changed during preparation

task_claim's CAS retry loop (mcp/servers/witan/witan/server.py) fires a
conditional write and, on a surfaced OmnigraphConflict, re-reads to decide
whether a rival actually holds the task (lost_race) or the conflict was
unrelated (another write elsewhere on the graph). The bug was in the
"unrelated conflict" path:

• Only 3 attempts, fired back-to-back with no backoff.
• On the 3rd conflict it did a bare raise, letting the raw
  OmnigraphConflict — whose message is the "write authority ... changed
  during preparation" prose — escape straight through the @_tool wrapper
  (which does no exception handling) to the MCP client.

node:Task is one of the hottest tables in this graph (every
claim/update/close from every session writes it), and this repo's own
write-gate investigation (tk-the-write-gate-is-sized-against-a-3-45s-solo-wri-73fc2b)
already measured loaded writes taking 17-44s under contention — three
immediate, unbacked-off retries have no chance against that.

Changes:

• _CLAIM_MAX_ATTEMPTS: 3 → 5.
• New jittered backoff (_claim_backoff, 0.25s base, 3s cap) between retry
  attempts, so concurrent claimers on the same task/table don't collide in
  lockstep.
• On exhaustion, return a structured {"claimed": false, "reason": "contention", "remedy": ...} instead of letting the raw omnigraph
  exception escape. Logs witan.task_claim.contention_exhausted for
  observability.
• Docstring updated to document the new "contention" reason value.

This does not address the underlying multi-second write contention itself —
that's the scope of the write-gate/batching work already tracked separately.
This just stops task_claim from leaking internal transport errors to callers
when it hits that contention.

How can this be tested?

• New tests in mcp/servers/witan/tests/test_tasks.py:
  • test_claim_exhausted_conflicts_report_contention_not_raise — simulates
    every retry attempt hitting an unrelated OCC conflict (no rival ever
    holds the task) and asserts task_claim returns {"claimed": false, "reason": "contention"} rather than raising, and that the task is left
    untouched (status: "open").
  • test_claim_retries_back_off_between_attempts — asserts a sleep occurs
    between a conflicting attempt and its retry, with the expected backoff
    magnitude.
• Full suite run locally: mcp/servers/witan — 835 passed (0 failed, 0
  skipped beyond the pre-existing omnigraph-not-on-PATH skips).
• ruff check / ruff format: confirmed zero new lint debt against main
  (same 18 pre-existing rule violations, none introduced by this change);
  both changed files format-clean.

Additional Context

Filed and diagnosed after a direct report: "Recent Claude sessions are
hitting a witan error when interacting with the graph: write authority
'table_head:node:Task' changed during preparation". Root-caused by reading
the CAS classification path in witan_core/omnigraph.py (confirmed the
"write authority" prose is correctly classified as retryable — the defect is
entirely in task_claim's own retry budget, not the classifier) and cross-
referencing the write-gate/mutual-exclusion investigations already tracked
under wp-witan-multi-user-service-deployment-dcf6ee.

[Copilot]

Pull request overview

Improves task_claim conflict handling under graph contention.

Changes:

• Adds bounded jittered retry backoff.
• Returns structured contention responses instead of raw exceptions.
• Adds contention and backoff tests.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
mcp/servers/witan/witan/server.py	Implements retry backoff and contention reporting.
mcp/servers/witan/tests/test_tasks.py	Tests retry exhaustion and backoff behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[blarghmatey]

Addressed Copilot's review: both threads fixed in fb82673 (revalidate closed/blocked before retrying a CAS conflict; softened the exhausted-contention message to not overclaim the cause) and resolved. All checks green except witan-code (code graph), which is unrelated to this PR — its "Install omnigraph binary" step fails on a checksum mismatch for the pinned edge tag (upstream moved the tag), not on anything this diff touches. Reproduced the same failure against this branch's parent commit (before any task_claim changes), so it's pre-existing and would fail on any PR right now. Leaving it as-is rather than touching the pin in this PR — that's a separate, deliberate call (the install script explicitly refuses to proceed on a mismatch).