Warn when the Corgea webapp is older than this CLI requires

[Ibrahimrahhal]

What this does

Every authenticated command now reads GET /api/version right after verifying the token and, when the deployment is behind the CLI's minimum, prints a warning before running:

Warning: this Corgea CLI (v1.10.0) requires Corgea webapp v1.71.3 or newer, but
http://127.0.0.1:8123 is running v1.70.0. Commands may fail or return incomplete
results until the webapp is upgraded. Set CORGEA_SKIP_WEBAPP_VERSION_CHECK=1 to
silence this warning.

The floor lives in src/version_check.rs as MIN_WEBAPP_VERSION, defaulting to v1.71.3. Raise it whenever the CLI starts depending on a webapp change.

The endpoint is added by Corgea/doghouse#1860; this change works against webapps with and without it.

Comparing versions

Deployment versions are not plain semver. Releases ship as v1.71.3, while pre-release and per-customer builds add a suffix: v1.71.3-beta, v1.71.3-client-a. So only the leading major.minor.patch is compared, via an anchored ^v?(\d+)\.(\d+)(?:\.(\d+))?(?:$|[-+]). Two things follow from that:

• A suffixed build counts as the release it was cut from. Semver pre-release ordering would sort 1.71.3-beta below 1.71.3 and warn about a webapp that is in fact current.
• Anything that is not that shape is unknown rather than optimistically new. Matching a dotted number anywhere would read build-2026.08-v1.70.0 as 2026.8.0 and suppress a warning that should fire.

A missing patch reads as .0, so v1.71 and v1.71.0 compare equal.

Never blocks a command

The check is best effort and only ever adds a warning. Every one of these leaves the command running exactly as before, with nothing on stderr beyond a --debug line:

• the webapp answers 404 (it predates the endpoint)
• the webapp reports "version": null (it cannot determine its own version)
• the endpoint is unreachable, stalls, or answers 5xx
• the reported version is not a shape we recognize

Two details that make "never blocks" true rather than aspirational:

• The request carries its own 5s timeout instead of the shared client's 150s, so a deployment that serves /api/v1/verify but stalls this route cannot hold the user's command for two and a half minutes.
• It deliberately skips check_for_warnings, so a pre-flight can never be what terminates the process. The command's own requests still surface deprecation signals.

Why a 404 does not warn

Worth stating explicitly, because it looks like a missed case. The endpoint ships in a release above MIN_WEBAPP_VERSION — doghouse's current tag is v1.71.3 and #1860 is on top of it. So a 404 only narrows the webapp to "older than the release that added the route", a range that includes deployments running exactly v1.71.3, which satisfy the floor. Warning on 404 would tell correctly-configured customers to upgrade, which is worse than staying quiet. The reasoning is recorded in the code so it is not "fixed" later.

The consequence is that the warning is inert on old self-hosted deployments until they pick up the release carrying the endpoint, and it self-corrects from there. The clean way to close that gap later is a second constant recording the first webapp release that serves /api/version; once the floor is raised above it, a 404 does prove non-compliance and can warn.

Escape hatches

Variable	Effect
CORGEA_MIN_WEBAPP_VERSION	Overrides the floor without a rebuild
CORGEA_SKIP_WEBAPP_VERSION_CHECK=1	Skips the check, and the request, entirely

The second exists for anyone deliberately pinned to an older self-hosted webapp who does not want the warning on every command.

Testing

./harness check passes: clippy (strict), format, and 653 tests.

Unit tests in src/version_check.rs cover number extraction from plain and suffixed versions, a missing patch, decorated strings that must read as unknown (build-2026.08-v1.70.0, corgea 1.70.0, 1.71.3.4), whitespace tolerance, the comparison boundary, and the warning's contents. tests/cli_webapp_version.rs drives the real binary against a stubbed webapp for: an outdated webapp warning and still running the command, a current webapp staying silent, suffixed builds comparing on their numbers in both directions, a 404, a null version, a stalled endpoint, and the skip flag suppressing both the warning and the request.

The stall test asserts elapsed time, not just success, so it fails if the per-request timeout is ever dropped. Verified by temporarily reverting the fix: 150.02s without it, 5.02s with it.

The cloud contract tests in tests/cloud_commands_e2e/ pin the exact request sequence of each command, so they gained an explicit webapp_version_request() expectation after verify_request(). It answers with a null version, which keeps those contracts independent of the CLI's minimum-version floor.

Verified live against a real doghouse

The binary was pointed at a real doghouse dev server (Postgres, migrated, real token) running the Corgea/doghouse#1860 branch, restarting it for each case since the app caches its resolved version. Re-run after the anchoring change with identical results:

Version the webapp served	CLI warned
v1.70.0	yes
v1.71.3	no
v1.71.3-client-a	no
v1.71.2-beta	yes
v2.0.0	no
v1.69.0 (from the APP_VERSION fallback)	yes
null (webapp could not determine it)	no

The 404 path was checked the same way, by removing the route from the running app so it answers like a webapp released before the endpoint existed. Even with a baked version of v1.70.0 — behind the floor — the CLI stayed silent, saying only under CORGEA_DEBUG=1:

GET /api/version -> HTTP 404
Webapp does not serve /api/version
Webapp did not report a version; skipping compatibility check

  

[corgea-security]

Automated review risk: 4/5.

The advisory check can delay every authenticated command for 150 seconds and fails to warn the oldest unsupported deployments. Version parsing also accepts malformed values.

Critical or high-priority changes must be addressed.

Automatic approval was not submitted: automated review found critical or high-priority findings.

[cursor]

[P1] The documented rollout makes the default check unable to warn any normally-versioned outdated deployment. This code says /api/version first ships in a release above v1.71.3: therefore every real release below the v1.71.3 floor takes this 404 → Ok(None) path and stays silent, while every release new enough to have the endpoint is already above the floor and also stays silent. The passing outdated test only works by giving a server with the new endpoint the artificial older value v1.70.0, a state the stated release sequence does not produce. As shipped, the users this task targets still receive no warning. Preserve 404 as a distinct result and emit an accurately worded “compatibility could not be verified; this CLI requires v1.71.3+” warning (the existing skip variable can suppress it), or ensure the endpoint is deployed/backported at or below the minimum before enabling this floor.

[corgea-security]

I agree with this finding and think it should be addressed.

high: Default check cannot detect normally deployed outdated webapps

The endpoint first ships above v1.71.3, while v1.71.3 is the minimum. Thus every normal release below the minimum returns 404 and is treated as unknown, while releases exposing the endpoint are already above the minimum. The outdated test models an artificial v1.70.0 deployment that nevertheless exposes the newer endpoint. Delay enabling this floor until the endpoint release is at or below the minimum, or distinguish 404 and provide an accurate unverifiable-compatibility warning.

Proof or reproduction:

// Current behavior for every normally deployed version below v1.71.3:
if status == StatusCode::NOT_FOUND {
    return Ok(None);
}
// warn_if_webapp_outdated then returns without warning on Ok(None).

[corgea-security]

Automated review risk: 3/5.

The implementation is safe for commands but its default compatibility warning is effectively inert under the documented endpoint rollout.

Critical or high-priority changes must be addressed.

Automatic approval was not submitted: automated review found critical or high-priority findings.