[emupton]

Pairs with conduktor/console-plus#5920 (stale-while-revalidate permission graph) and its stacked header PR.

Why

Console's permission-graph cache is moving to stale-while-revalidate: after a permission write, a Console node that didn't process the write serves the previous graph for the duration of one background rebuild (seconds). A CLI chaining dependent applies — create a group, then create a child entity the new grant authorizes — can race that window when a load balancer routes consecutive requests to different Console nodes: the second call 403s, a retry succeeds.

Console closes this for clients that opt in: every API response carries X-Cdk-Graph-Version (a monotonic int64), and a request echoing a version makes the handling node catch its cache up before authorizing.

What changes

The shared resty client now:

• captures X-Cdk-Graph-Version from every response and keeps the max seen (atomic — apply --max-parallel runs goroutines against one client);
• sets the header with that max on every outgoing request.

In-process only: a fresh invocation starts clean and sends no header until the first response carries one. Missing or unparsable headers are ignored; older Console versions are unaffected. Hooked at the client level so every call site participates, including future ones.

What this deliberately does NOT do

There is no retry-on-403 here. The echo works by blocking, not failing: a request carrying a version makes the Console node wait for its cache to catch up before authorizing, so a version mismatch surfaces as a slightly slower response, never as a 403 — within the covered flow, retry logic would be dead code.

A 403 from graph staleness therefore remains possible only where no version has been seen yet:

• Cross-process chains — two separate conduktor invocations in a CI script: the second process starts clean and sends no header on its first call.
• Grants made outside the CLI — e.g. an operator grants in the UI and the CLI uses it immediately.
• Console older than the header — the CLI degrades to plain stale-while-revalidate behaviour.

These windows are seconds wide (one graph rebuild) and self-heal; scripts that chain separate invocations need their own retry for now. If that proves flaky in practice, the natural follow-up is a single bounded retry on 403 in the shared client — not persistence of the version to disk, which brings file-locking and parallel-CI problems.

Validation

go build ./..., full go test ./..., plus unit tests covering: capture, echo on next request, no regression on a lower version, no header when none seen, unparsable values ignored, concurrent-use safety.

🤖 Generated with Claude Code