Repository navigation
feat: record gateway version alignment in the diagnostics bundle - #36440
Conversation
Code change approver recommendation: ApproveWhy: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes. This adds a version_alignment: line to the bundle's versions.txt. kirocrew doctor --bundle compares the version on the gateway's token-exempt /api/health, on the port resolve_client_port finds, with live_target.selected_version(). The dashboard collector passes nothing in and records 'not checked'. Both readings are guarded (port resolution and selected_version catch their own errors, and _running_gateway_version turns any failure into None), so bundle mode cannot crash on this path. The line forms match cli_server._format_version_line, minus the age and restart hint. The family import happens inside the bundle branch, so the tests that check importing the CLI loads no doctor_checks family still pass. collect_bundle only gains an optional keyword, so the dashboard handler and existing tests are unaffected. New tests cover the aligned, skew, no-gateway and unreadable cases, plus the CLI-to-collector handoff and the dashboard default. The spec and docstrings were updated. CI failures are rate-limit infrastructure failures, not verdicts on the code. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the bundle reuses the Notes
[DESIGN-REVIEWED] d99a457 Description read[DESCRIPTION-READ] 8883ee23f528f9df72da4dcbe2995ab96e1cf5921285e8aeffbd71e57cf5a5d1 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: the change adds one private bundle line built from the What this change shipsInventory (4 items) — 4 justifiedIntent: let a maintainer reading a user's diagnostics bundle see whether the running gateway serves the selected package, and which two versions differ when it does not. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] d99a457 Description read[DESCRIPTION-READ] 778d64212202ab1726790cc69dfca5395f9aab133e40009b19977d54ff794ecf That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
2beddb0 to
47b0ec3
Compare
|
|
Rebased: main moved in docs/system-specs/modules/cli.md, src/kiro_crew/cli_doctor.py, src/kiro_crew/diagnostics.py, src/kiro_crew/doctor_checks/init.py, src/kiro_crew/doctor_checks/services.py, test/test_cli_doctor_refactor_report.py and test/test_diagnostics.py since this head went green (f9788c5 -> 599c87f); CI re-running. The one conflict, in [operator: bolichen97] |
47b0ec3 to
3bbbd58
Compare
A bundle collected by `kirocrew doctor --bundle` carried no comparison of the running gateway with the selected package, so a maintainer reading a report could not tell a finished update from a half-applied one. Its private versions.txt now carries a version_alignment line: the running gateway's version from token-exempt /api/health against live_target.selected_version(), worded by the formatter behind `kirocrew status`'s Version line, with no age because /api/health has no start time. A bundle the dashboard collects runs inside the gateway, whose own files are not the selected package of a side-by-side install, so it records the comparison as not checked instead of a false "aligned". Part of #13086
|
Rebased: main moved in test/conftest_resets.py, src/kiro_crew/cli_server.py, test/test_member_memory_upgrade.py, src/kiro_crew/sel.py, src/kiro_crew/memory_stores.py, src/kiro_crew/change_card_catalog_kinds.py, src/kiro_crew/tool_call_title.py, src/kiro_crew/worker_grill_preview.py and thirteen module specs beside docs/system-specs/modules/cli.md since this head's CI ran (599c87f -> fd8955a); CI re-running. The rebase was clean and the change itself is the same. The new base carries #39479, which fixes [operator: bolichen97] |
3bbbd58 to
d99a457
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
I reviewed head d99a457. The new version_alignment line in versions.txt holds only the running gateway's version, the selected package's validated version string, and the fixed wording kirocrew status already prints. It is built before the existing redaction pass over versions.txt, so no token, path or user name is added to the bundle. The dashboard collector writes a fixed 'not checked' value and passes no request input into that line. Every read along the path fails soft, so bundle mode cannot crash on it. The changed test files pass on this head, and the new cases check the exact text for the aligned, skew, no-gateway and unreadable cases.
Problem / Motivation
Goal: a diagnostics bundle from
kirocrew doctor --bundlesays whether the running gateway serves the selected package, and which two versions differ when it does not.A gateway can keep serving an earlier package after a newer one is selected: an in-place upgrade under a running gateway, a promoted update whose restart was put off, a desktop update that has not restarted it. #31331 made
kirocrew statusandkirocrew doctorshow that. The diagnostics bundle a user attaches to a bug report still says nothing about it:kirocrew doctor --bundlestops before the doctor'srunning:row, andversions.txtrecords only the collecting process's own version. A maintainer reading the report cannot tell whether the logs came from the build the user thinks they are on.Why it matters
A bug seen during a half-applied update is easy to blame on the selected build when the gateway was still running the old one. The bundle is what a maintainer reads first, so it is where that mismatch has to show.
Not a goal
kirocrew status, the doctor'srunning:row, update, restart or ownership behaviour.What changed (motivation → approach → change)
The bundle's private
versions.txtgains oneversion_alignment:line.kirocrew doctor --bundle, versions matchaligned (0.13.0)kirocrew doctor --bundle, versions differversion_skew: the gateway runs 0.13.0.1, 0.13.0.2 is selected; restart the gateway to run itkirocrew doctor --bundle, no gateway answersunknown (the gateway did not report its version; try `kirocrew doctor`)kirocrew doctor --bundle, selected version unreadableunknown (could not read the selected package's version; check the install)not checked (collected inside the gateway, which cannot read a side-by-side install's selected package; ...)The CLI reads both sides as
kirocrew statusdoes when its owner sign-in fails: the running version from token-exempt/api/healthon the portkirocrew statusresolves, through the helper the doctor'srunning:row uses, and the selected one fromlive_target.selected_version(). The words come fromcli_server._format_version_line, the formatter behindkirocrew status'sVersion:line, called with no age, so the two lines cannot drift apart. The CLI hands the line to the shared collector indiagnostics.py; with nothing handed in, the dashboard's collector writesnot checked. Inside the gatewayselected_version()reads the gateway's own resolved tree, so after a promoted update or a desktop update it would report aligned while a newer package is selected; that is why the dashboard bundle does not compare.The reading lives in
doctor_checks/services.pybeside therunning:row.cli_doctor.py's bundle mode loads that family (with therenderhelpers it imports) and, for the formatter,cli_server, which adds about 1.7 seconds tokirocrew doctor --bundle. Its docstrings,doctor_checks/__init__.pyand the cli spec (docs/system-specs/modules/cli.md) name the family it loads, and the spec documents the line.Backwards compatibility
Compatible:
versions.txtgains a line andcollect_bundlegains an optional keyword; every existing caller and member is unchanged.Removes nothing: the change only adds a line to a private bundle member.
Tests
test/test_cli_doctor_gateway_row.py::test_bundle_version_alignment: aligned, skew, no gateway and an unreadable selected version each give the real formatter'skirocrew statustext for that case, and the CLI reads/api/healthon the resolved port.test/test_diagnostics.py::test_versions_txt_records_the_version_alignment: the CLI's line lands inversions.txt; with none handed in it readsnot checked.test/test_cli_doctor_refactor_report.py::test_bundle_mode_prints_only_the_bundleand::test_bundle_mode_prints_the_bundle_when_the_companion_does_not_compose:kirocrew doctor --bundlehands its reading to the collector and still prints only the bundle.Each new or changed test fails with the parent commit's
src/and passes with this change. On this head the three files pass alone at-n0(174 passed), and the 125 test files that importcli_doctor,diagnosticsordoctor_checks.services, or read the cli spec, pass together at-n 4 --dist loadgroup --max-worker-restart=2(6039 passed, 12 skipped) apart from one teardown error intest/test_live_target_pointer_visibility.pythat fails the same way on a cleanmaincheckout of the same machine. Determinism: the eight new and changed cases passed 20 runs at-n0; the three files passed 10 runs at-n 4 --dist loadgroup --max-worker-restart=2and two seeded shuffles of all 170 tests (seeds 1404 and 12575).Manual verification
Run on Linux (Ubuntu 24.04, Python 3.12) from source, against a gateway started from a throwaway
KIROCREW_HOMEon a free loopback port.Before this change,
kirocrew doctor --bundleagainst a healthy gateway (0.13.0) wrote aversions.txtwith no comparison line (grep -c version_alignment→0).After it, the
version_alignment:line of each bundle'sversions.txt:Against an idle gateway,
kirocrew doctor --bundletook 1.96 s and 2.02 s before this change and 3.71 s and 3.74 s after it: thecli_serverimport its formatter needs.Real-machine verification
Machine: AWS EC2 m7i.2xlarge, Ubuntu 24.04 (Linux 7.0.0-1014-aws, Python 3.12.3), x86_64, 8 vCPU / 32 GiB
Before (main 30f3498):
kirocrew doctor --bundleagainst a gateway started from a throwawayKIROCREW_HOME, thenunzip -p <zip> versions.txt | grep -c version_alignment->0(two runs)After (c86c7798b03d, this commit on that main): the same command ->
version_alignment: aligned (0.14.0); with aBUILD_VERSIONstamp of 0.14.0.7 written under the running gateway ->version_alignment: version_skew: the gateway runs 0.14.0, 0.14.0.7 is selected; restart the gateway to run it; with the gateway stopped ->version_alignment: unknown (the gateway did not report its version; try `kirocrew doctor`)Cleanup: gateways stopped by pid, throwaway data homes discarded, instance terminated (a tag search no longer lists it)
Screenshots / video
N/A -- no file under
website/; the change is one line in a CLI-collected bundle member, shown above.Related Issues
Part of #13086
Sibling sweep
N/A -- not a fix or revert PR.
Pattern harvest
N/A -- not a fix or revert PR.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits