Skip to content

feat: show selected-versus-running version skew in kirocrew status - #31331

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/13086-version-skew-status
Nov 7, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/13086-version-skew-status

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: kirocrew status tells an operator whether the running gateway serves the package selected to run, and if not, which two versions differ and for how long.

A gateway can keep serving an earlier package after a newer one is selected: an in-place upgrade under a running gateway, a desktop update that has not restarted it, or a Dev Fleet cutover not yet restarted into. The gateway still answers, so kirocrew status looks the same in both states. kirocrew doctor's running: row already compared the gateway with the code the doctor itself imported, but the reporter of #13086 read the status surface and needed a manual process census to see the mismatch.

Builds on #17746 by @chenmingwei23.

Why it matters

The two states need different action. When the gateway runs the selected package there is nothing to do; when it does not, the operator has to finish the update or restart the gateway before blaming the selected build for anything they see. Without a signal they cannot tell a finished update from a half-applied one.

Not a goal

  • No rows for the desktop app, a gateway daemon or sidecars: none of them publishes a running version kirocrew status can read today.
  • No diagnostics-bundle row. Inside the gateway the selected package of a side-by-side install (a versioned venv or desktop directory behind a current-version link) cannot be read from the gateway's own files, and a bundle collected by kirocrew doctor --bundle has no running gateway version. Both need their own design, so this PR is Part of Surface selected-versus-running component version skew #13086, not its close.
  • No warning threshold: skew is reported as soon as the versions differ, with its age, as the reporter proposed. A threshold is a later change.
  • No change to update, ownership, restart or recovery behaviour, or to service.version.
  • Not the dashboard, the diagnostic snapshot or OpenTelemetry attributes.

What changed (motivation → approach → change)

kirocrew status ends with a new Version: line:

State Line
gateway runs the selected build aligned (0.13.0)
it runs another build version_skew for at least 2h 0m: the gateway runs 0.13.0.1, 0.13.0.2 is selected; restart the gateway to run it
the gateway gave no version unknown (the gateway did not report its version; try `kirocrew doctor`)
the selected version is unreadable unknown (could not read the selected package's version; check the install)

The identity is the string kirocrew --version prints, __version__ plus any BUILD_VERSION stamp, as the reporter proposed: it separates two builds of one release, and it reads the same way in packaged and source installs. Two source checkouts at one version read as aligned; that is the accepted tradeoff.

The running side is /api/status's version. When token auth answers that request with 401 or 403, the line still prints: it reads the token-exempt /api/health version that kirocrew doctor reads, through the proxy-free loopback_urlopen (so a configured http_proxy cannot divert it, for either command), with no age, because that reply carries no start_time. No token is read or sent. The selected side comes from a new live_target.selected_version() in service/live_target.py: the pinned Dev Fleet checkout when one is set, else the package this kirocrew runs. Either way it is read from disk, not taken from the process's own __version__, so an in-place upgrade under a running gateway shows. The age counts from the later of the gateway's start and the newest change time of the pointer and the version files, so it is a lower bound and never overstates. One known limit, written into the spec: after a git auto-update the gateway re-imports its package, so until its restart lands it reports the new version and the line reads aligned.

kirocrew doctor's running: row now reads the same selected_version() instead of the version the doctor imported, so the two commands share one definition of "selected" and cannot disagree; before, a pinned checkout at another version made doctor say restart needed while the gateway already ran the pin. An unreadable selected version prints on disk unknown and is not an issue.

cli_server.py prints the line, doctor_checks/services.py reads the shared value, and docs/system-specs/modules/cli.md documents both.

Backwards compatibility

Compatible: kirocrew status gains one line at the end; no existing line, key or exit code changes. kirocrew doctor's running: row keeps its wording; with a Dev Fleet checkout pinned it now compares against the pin, so it no longer reports a restart that would change nothing.

Removes nothing: the diff only adds output.

Tests

test/test_cli_server_version_alignment.py:

  • selected_version() reads a pinned checkout's literal plus its BUILD_VERSION stamp; unpinned, it reads the installed package's file rather than the imported __version__; it returns (None, None) for a checkout with no version literal; and an unpin moves its change time.
  • kirocrew status prints aligned (0.13.0) when the gateway runs the selected build.
  • Two builds of one release (0.13.0.1 running, 0.13.0.2 selected) print version_skew naming both, aged from the selection's change (persistent skew).
  • A gateway that started after the selection changed is aged from its own start (transient skew).
  • An unreadable running or selected version prints unknown, never aligned.
  • _running_gateway_version reaches a real loopback gateway with http_proxy set and no_proxy=localhost, and the proxy sees no request (10/10 repeats).
  • Each unknown line names the side that could not be read.
  • Under token auth (a 403 from /api/status), kirocrew status still prints the Version: line from /api/health, skew or aligned, with no age.
  • kirocrew doctor reads the pinned checkout's version, the same value status compares, and reports no restart for a gateway that runs it (red on the parent, which compared the imported __version__); an unreadable selected version prints on disk unknown with no issue.
  • test/test_cli_doctor_gateway_row.py and the frozen report in test/test_cli_doctor_refactor_report.py pin selected_version() instead of _mc_version.

Determinism: 20/20 runs at -n0; 10/10 at -n 4 --dist loadgroup --max-worker-restart=2 with test/test_live_target.py and test/test_live_target_pointer_visibility.py as co-tenants; a shuffled order (seed 20465) green. The age assertions leave a 60-second margin, and the unpin test stamps the pointer an hour ahead with os.utime rather than racing the filesystem clock.

Manual verification

Ran cli_server._status from this branch on an isolated data home with the real selected_version() and a stubbed /api/status payload. A gateway reporting the installed 0.13.0 printed Version: aligned (0.13.0); one reporting 0.12.0 printed Version: version_skew for at least 1h 18m: the gateway runs 0.12.0, 0.13.0 is selected; restart the gateway to run it (the age is the checkout's own __init__.py change time). No live gateway was started.

Screenshots / video

N/A — no frontend change; the CLI output is shown above.

Related Issues

Part of #13086

Sibling sweep

N/A — not a fix PR.

Pattern harvest

N/A — not a fix PR.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 10:13
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 10:13
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision e33ec9055cb074754b4337d57fdfdd19683c189c touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of e33ec9055cb074754b4337d57fdfdd19683c189c — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Every item traces to #13086 or to a test that fails on base. The doctor-row and proxy changes ride along but are declared, and the status fallback needs them.

What this change ships

Inventory (7 items) — 7 justified

Intent: let an operator see from kirocrew status whether the running gateway serves the selected package, and if not, which versions differ and for how long. ADDITION.

  1. kirocrew status ends with a new Version: line showing aligned (<v>) or version_skew naming both versions — justified
  2. The skew line gives a lower-bound age ("for at least Xh Ym") — justified
  3. unknown (...) names which side, gateway or selected package, could not be read — justified
  4. With token auth on (401/403), status still prints Version:, read from token-exempt /api/health, with no age — justified
  5. kirocrew doctor's running: row now compares against the pinned Dev Fleet checkout instead of the imported version, so it no longer says "restart needed" for a gateway already running the pin — justified
  6. The doctor health probe ignores a configured http_proxy (loopback_urlopen) — justified
  7. New live_target.selected_version() reads version and change time from disk; 3 call sites (grepped selected_version), and no existing reader of a checkout's version (grepped ast.parse|__version__ =|_apply_build_version_file) — justified

[FIRST-PRINCIPLES-REVIEWED] e33ec90

Description read

[DESCRIPTION-READ] 22c425b847ce3f5798f6da679f01285d6f1bb0dd7e60c2277b398636629dbaa0

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of e33ec9055cb074754b4337d57fdfdd19683c189c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the version check is additive, status and doctor now read "selected" from the same function, and the known blind spots are written down.

Notes

  • With a Dev Fleet checkout pinned, doctor's Runtime kiro_crew: row still prints the imported _mc_version, while the running: row now compares against the pin. The same report can then show two different "on disk" versions. Labelling one of them, or reading both from selected_version(), would stop operators from asking which one is right.
  • cli_server._status now imports _running_gateway_version from doctor_checks.services to read the version. Since both commands now use it, the probe would sit better in a shared owner such as loopback_http or service/ than inside a doctor check.

[DESIGN-REVIEWED] e33ec90

Description read

[DESCRIPTION-READ] f0824fe382920cc86da441fc79f7c8d1e682d56fded249b91aa46612ad257be8

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed e33ec9055cb074754b4337d57fdfdd19683c189c — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] e33ec90

Verdict parsed from the review's SHA-scoped output markers for commit e33ec9055cb074754b4337d57fdfdd19683c189c.

False positive or not applicable? A repository writer can comment:
/ai-review override fable e33ec9055cb074754b4337d57fdfdd19683c189c false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of e33ec9055cb074754b4337d57fdfdd19683c189c and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e33ec90

False positive or not applicable? A repository writer can comment:
/ai-review override gpt e33ec9055cb074754b4337d57fdfdd19683c189c false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 10:43
@bolichen97
bolichen97 force-pushed the fix/13086-version-skew-status branch from 3ff7fde to 72aba5e Compare November 6, 2026 15:05
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 6, 2026
@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: one shared selected_version() reading for status and doctor

  • Second version-alignment check beside doctor's span=7838b474f33e

fixed in 72aba5e: kirocrew doctor's running: row now reads live_target.selected_version(), the same value the status Version: line compares, instead of the imported __version__.
Only one function now decides what "selected" means, so the two commands cannot disagree; with a pinned checkout, doctor no longer reports a restart that would change nothing.
Red/green: test_doctor_reads_the_same_selected_version_as_status pins a checkout at another version than the import and fails on the parent.
The PR description now names the existing doctor row (the Notes bullet).

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 6, 2026
@bolichen97
bolichen97 force-pushed the fix/13086-version-skew-status branch from 72aba5e to 75965ad Compare November 6, 2026 16:05
@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: token-auth branch prints Version from token-exempt /api/health

  • Version comparison is unreachable against a normal gateway span=36879ba7cb57

fixed in 75965ad: when /api/status answers 401/403, kirocrew status still prints the Version: line, reading the running version from token-exempt /api/health through the helper kirocrew doctor already uses (doctor_checks.services._running_gateway_version).
No token is read or sent and no endpoint's auth changes; that reply has no start_time, so the line carries no age there.
Red/green: test_token_auth_status_prints_version_without_age (skew and aligned) fails on the parent, which returned before the line.

@bolichen97
bolichen97 force-pushed the fix/13086-version-skew-status branch from 75965ad to 45a0f8a Compare November 6, 2026 18:20
@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: /api/health probe through loopback_urlopen

  • health probe obeys proxy settings span=0d7313f2195d

fixed in 45a0f8a: _running_gateway_version reads /api/health through loopback_http.loopback_urlopen, which ignores any configured proxy, so kirocrew status (token-auth branch) and doctor's running: row both reach the local gateway with http_proxy set and no_proxy=localhost.
Red/green: test_running_version_ignores_a_configured_proxy runs a real loopback gateway and a real proxy; on the parent the proxy receives the health request.

@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: unknown line names the unreadable side

  • unknown line doesn't say which version is missing span=d22f471958b4

fixed in 45a0f8a: the line names the side that failed, each with a next step: unknown (the gateway did not report its version; try `kirocrew doctor`) or unknown (could not read the selected package's version; check the install).
Both still start with unknown (, so neither case can read as aligned; test_an_unreadable_version_is_unknown_and_names_the_side fails on the parent.
The aligned / version_skew words stay: the linked issue asks for those exact states.

@bolichen97
bolichen97 force-pushed the fix/13086-version-skew-status branch from 45a0f8a to db62a79 Compare November 6, 2026 21:15
A gateway can keep serving an earlier package after a newer one is
selected (an in-place upgrade, a desktop update, a Dev Fleet cutover
not yet restarted into), and kirocrew status looked the same either way.

status now ends with a Version line comparing the gateway's reported
version with the selected package's version read from disk: aligned,
or version_skew with both strings and a lower bound on how long they
have differed.
@bolichen97
bolichen97 force-pushed the fix/13086-version-skew-status branch from db62a79 to e33ec90 Compare November 6, 2026 22:45
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved for the on-call. Review lanes pass on e33ec90, no conflict, no open change request.

@KiroCrewCaptain
KiroCrewCaptain merged commit bd3ad8d into main Nov 7, 2026
97 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/13086-version-skew-status branch November 7, 2026 00:46
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 2026
bolichen97 added a commit that referenced this pull request Nov 9, 2026
/api/status accepts only a dashboard token, and kirocrew status sent
none, so on a default gateway it never printed its stats or the Memory
line. On a 401/403 it now mints a one-minute owner token from
/api/token/local, as kirocrew token does, and reads /api/status with
it, both through the peer-proven transport. When that sign-in is
refused it prints the existing token-auth line.

Backport note: release's kirocrew status has no Version line (#31331,
not on release), so the owner read and _owner_status are added without
it: a refused sign-in prints release's two token-auth lines and returns.
cli.md takes the new sign-in paragraph without its Version wording and
leaves out the Version paragraph edit.

(cherry picked from commit 3f3f80f)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants