Skip to content

feat: record gateway version alignment in the diagnostics bundle - #36440

Merged
bolichen97 merged 1 commit into
mainfrom
fix/13086-bundle-version-alignment
Nov 19, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/13086-bundle-version-alignment

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a diagnostics bundle from kirocrew doctor --bundle says 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 status and kirocrew doctor show that. The diagnostics bundle a user attaches to a bug report still says nothing about it: kirocrew doctor --bundle stops before the doctor's running: row, and versions.txt records 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

  • No mismatch age in the bundle: the gateway's token-exempt health reply carries no start time.
  • No comparison in a bundle the dashboard's Report a Problem button collects. That collector runs inside the gateway, and its own files are not the selected package of a side-by-side install, so it records the comparison as not checked instead of guessing.
  • No rows for the desktop app, the MCP gateway daemon or sidecars, and no diagnostic snapshot, OpenTelemetry attribute or dashboard surface. They stay open on Surface selected-versus-running component version skew #13086.
  • No change to kirocrew status, the doctor's running: row, update, restart or ownership behaviour.

What changed (motivation → approach → change)

The bundle's private versions.txt gains one version_alignment: line.

Collected by Line
kirocrew doctor --bundle, versions match aligned (0.13.0)
kirocrew doctor --bundle, versions differ version_skew: the gateway runs 0.13.0.1, 0.13.0.2 is selected; restart the gateway to run it
kirocrew doctor --bundle, no gateway answers unknown (the gateway did not report its version; try `kirocrew doctor`)
kirocrew doctor --bundle, selected version unreadable unknown (could not read the selected package's version; check the install)
the dashboard's Report a Problem not checked (collected inside the gateway, which cannot read a side-by-side install's selected package; ...)

The CLI reads both sides as kirocrew status does when its owner sign-in fails: the running version from token-exempt /api/health on the port kirocrew status resolves, through the helper the doctor's running: row uses, and the selected one from live_target.selected_version(). The words come from cli_server._format_version_line, the formatter behind kirocrew status's Version: line, called with no age, so the two lines cannot drift apart. The CLI hands the line to the shared collector in diagnostics.py; with nothing handed in, the dashboard's collector writes not checked. Inside the gateway selected_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.py beside the running: row. cli_doctor.py's bundle mode loads that family (with the render helpers it imports) and, for the formatter, cli_server, which adds about 1.7 seconds to kirocrew doctor --bundle. Its docstrings, doctor_checks/__init__.py and the cli spec (docs/system-specs/modules/cli.md) name the family it loads, and the spec documents the line.

Backwards compatibility

Compatible: versions.txt gains a line and collect_bundle gains 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's kirocrew status text for that case, and the CLI reads /api/health on the resolved port.
  • test/test_diagnostics.py::test_versions_txt_records_the_version_alignment: the CLI's line lands in versions.txt; with none handed in it reads not checked.
  • test/test_cli_doctor_refactor_report.py::test_bundle_mode_prints_only_the_bundle and ::test_bundle_mode_prints_the_bundle_when_the_companion_does_not_compose: kirocrew doctor --bundle hands 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 import cli_doctor, diagnostics or doctor_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 in test/test_live_target_pointer_visibility.py that fails the same way on a clean main checkout 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=2 and 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_HOME on a free loopback port.

Before this change, kirocrew doctor --bundle against a healthy gateway (0.13.0) wrote a versions.txt with no comparison line (grep -c version_alignment → 0).

After it, the version_alignment: line of each bundle's versions.txt:

# gateway running, nothing changed since it started
version_alignment: aligned (0.13.0)
# same gateway still running, a BUILD_VERSION stamp of 0.13.0.99 written under it
version_alignment: version_skew: the gateway runs 0.13.0, 0.13.0.99 is selected; restart the gateway to run it
# that gateway stopped
version_alignment: unknown (the gateway did not report its version; try `kirocrew doctor`)
# bundle collected by the dashboard (POST /api/diagnostics/collect) with a gateway running
version_alignment: not checked (collected inside the gateway, which cannot read a side-by-side install's selected package; `kirocrew doctor --bundle` compares them)

Against an idle gateway, kirocrew doctor --bundle took 1.96 s and 2.02 s before this change and 3.71 s and 3.74 s after it: the cli_server import 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 --bundle against a gateway started from a throwaway KIROCREW_HOME, then unzip -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 a BUILD_VERSION stamp 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

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • 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

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: 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 2beddb0c5a · 133 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@bolichen97
bolichen97 enabled auto-merge (squash) November 13, 2026 06:20
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision d99a457d3970b0a90666d8d04fac9f3ca3ecec27 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 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the bundle reuses the running: row's reading and kirocrew status's formatter, every read fails soft, and the dashboard collector says not checked instead of guessing.

Notes

  • Importing all of cli_server just to get _format_version_line adds about 1.7 s to every kirocrew doctor --bundle run, roughly doubling it. Moving that formatter into a light leaf module, imported by both cli_server and services, would keep the single source of wording without the import cost.

[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 .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 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of d99a457d3970b0a90666d8d04fac9f3ca3ecec27 — 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

Nothing blocks: the change adds one private bundle line built from the running: row's existing reading and kirocrew status's existing formatter. It adds no new comparison logic and changes no default.

What this change ships

Inventory (4 items) — 4 justified

Intent: 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.

  1. A kirocrew doctor --bundle zip's versions.txt now has a version_alignment: line (aligned, version_skew, or unknown) — justified
  2. A bundle from the dashboard's Report a Problem now has version_alignment: not checked (...) — justified
  3. kirocrew doctor --bundle takes about 1.7 s longer because it loads the services doctor family and cli_server — justified
  4. collect_bundle takes a new optional keyword, version_alignment, with 2 callers (cli_doctor.py:660 passes it; dashboard/handlers/diagnostics.py:105 uses the default) — justified

[FIRST-PRINCIPLES-REVIEWED] d99a457

Description read

[DESCRIPTION-READ] 778d64212202ab1726790cc69dfca5395f9aab133e40009b19977d54ff794ecf

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 added the readiness: checking Automated validation is still running label Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] d99a457

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

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

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d99a457

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d99a457d3970b0a90666d8d04fac9f3ca3ecec27 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 13, 2026
@bolichen97
bolichen97 force-pushed the fix/13086-bundle-version-alignment branch from 2beddb0 to 47b0ec3 Compare November 13, 2026 15:03
@bolichen97

bolichen97 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor Author
  • A second spelling of the Version: line formatter span=5150467d08e6

fixed in 47b0ec3: _bundle_version_alignment now returns cli_server._format_version_line({"version": _running_gateway_version(port)}, live_target.selected_version()[0], None), the composition kirocrew status already uses on its token-auth path; its four hand-written branches are deleted.
test_bundle_version_alignment runs the real formatter and pins its exact text for all four cases, and the cli spec names the formatter, so a wording change there now moves the bundle line with it.
[operator: bolichen97]

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 14, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

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 docs/system-specs/modules/cli.md, kept main's wording of the paragraph and this PR's --bundle sentence; the change itself is the same. The new base also carries #36652, which fixes test/test_mate_conductor_parity.py::test_every_shared_rule_has_an_ultra_counterpart_or_a_named_gap, the one test that was red on the previous head and on main at that head's base.

[operator: bolichen97]

@bolichen97
bolichen97 force-pushed the fix/13086-bundle-version-alignment branch from 47b0ec3 to 3bbbd58 Compare November 19, 2026 15:03
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 19, 2026
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
@bolichen97

Copy link
Copy Markdown
Contributor Author

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 test/test_process_cache_floor_ratchet.py::test_every_new_module_level_cache_has_a_per_test_reset, the test that was red on Backend Tests (3.12, 1) and (Windows) (4) of the previous head and on main at that head's base. It also carries #39516, which puts the Windows backend shards back to four workers. The previous head's other red, a Windows-only watcher timeout on Backend Tests (Windows) (5), is in a test this change does not touch.

[operator: bolichen97]

@bolichen97
bolichen97 force-pushed the fix/13086-bundle-version-alignment branch from 3bbbd58 to d99a457 Compare November 19, 2026 20:38
@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 readiness: checking Automated validation is still running labels Nov 19, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Nov 19, 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.

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.

@bolichen97
bolichen97 merged commit ffba442 into main Nov 19, 2026
99 checks passed
@bolichen97
bolichen97 deleted the fix/13086-bundle-version-alignment branch November 19, 2026 21:51
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 19, 2026
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