Skip to content

fix: say why a crew's version is unknown and which side is newer - #32464

Merged
bolichen97 merged 1 commit into
mainfrom
fix/25246-crew-version-banner
Nov 8, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/25246-crew-version-banner

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When a remote crew's version cannot be checked against this machine's, the crew window says why the version is unknown or which side is newer, and never shows a placeholder like 0 or ? as the crew's version.

The crew window's mismatch notice read "This crew runs Kiro Crew {{peer}} but this machine runs {{local}}. Update one so they match." for every case:

  • a version the gateway could not read showed as ?, with advice to update one side, although nothing was known to be out of date;
  • a peer answering a placeholder such as 0 showed as "runs 0", as if it were a release;
  • a real skew never said which side was older, so the reader could not tell what to update.

Why it matters

The notice is the only thing that explains why a crew window will not chat. When it reads the same for "could not read the version", "the crew answered nonsense" and "the crew is a release behind", people chase the wrong cause; the issue reports several multi-hour debugging sessions spent on a stale-cache theory that the banner pointed toward.

Not a goal

  • Mapping each failure code to its own prose. The notice shows the gateway's code (for example capability_unauthorized) in parentheses, the way the Remote Crew row already reports a failed version read.
  • Changing which crews the gateway accepts: version_match and every version refusal decide exactly as before.
  • An Update link or action inside the mismatch notice.
  • Documenting a debugging ladder for remote crews.

What changed (motivation → approach → change)

The window could not tell the cases apart because the capabilities reply carried only version, version_match and behind, and the window printed version || '?' into one sentence.

Case Notice now
Version unknown "Could not read which version this crew runs (<code>), so it cannot be checked against this machine's Kiro Crew <local>."
Crew older "This crew runs Kiro Crew <peer>, older than this machine's <local>. Update the crew to match."
Crew newer "This crew runs Kiro Crew <peer>, newer than this machine's <local>. Update this machine to match."
Versions the gateway cannot order the existing "Update one so they match." sentence
  • Gateway: one helper, known_version in apps/version.py, reads an all-zero release (0, 0.0.0) as no version. Every place that reads a crew's /api/version goes through it: the capabilities reply and GET /api/instances/versions (dashboard/handlers_instances_peer.py), the crew dispatch refusal (dashboard/handlers/remote_dispatch_routes.py, which then says "an unknown version"), and peer_version (instances/ssh_tunnel_manager_peer.py, so the remote update's check counts 0 as no answer). An unknown version always carries its reason: the carrier's failure code, or capability_malformed_reply when the crew answered without a usable version. The capabilities reply gains ahead, the same exact compare as behind with the two sides swapped.
  • Dashboard: one helper, crewVersionMismatchText in crew-window/crewWindowStore.ts, words the notice for both the crew window and New chat on crew (chat-sidebar/create.ts); types/index.gateway.ts gains ahead and describes the unknown-version reason. The three strings are new keys in all twelve catalogs, en-XA is regenerated, and en.context.json tells translators that {{code}} stays untranslated.
  • Spec: docs/system-specs/modules/instances.md describes ahead, the all-zero placeholder and the reason code.

Backwards compatibility

Compatible: every field the capabilities and versions replies carried is still there with the same meaning for a real version; the capabilities reply only gains ahead, and an unknown version gains a reason it lacked before.

Reader: website/src/pages/settings/CrewVersionStatus.tsx:CrewVersionStatus -- crew page -- a crew answering 0 shows its read-failed notice with capability_malformed_reply instead of a "Behind: remote 0" badge and Update (test_a_placeholder_zero_version_is_unknown_never_behind)
Reader: website/src/components/RemoteUpdateOffer.tsx:RemoteUpdateOffer -- crew page -- a crew answering 0 is listed among the crews whose version could not be read, not among the behind ones (test_a_placeholder_zero_version_is_unknown_never_behind)
Reader: src/kiro_crew/instances/ssh_tunnel_manager_remote_ops.py:_await_peer_version_change -- crew page -- a crew answering 0 after its restart ends the update unverified, not succeeded with version 0 (test_a_placeholder_zero_version_is_no_answer)

Tests

  • test_remote_crew_capabilities.py: a peer answering 0 is reported as an unknown version with capability_malformed_reply, a non-release build id still matches by equality, and behind / ahead name the older side for an older, newer and equal peer.
  • test_instances_remote_update.py: on the versions route a peer answering 0 is unknown and never behind, with its reason in error; an update whose crew answers 0 after the restart ends unverified.
  • test_session_control_crew.py: the crew dispatch refuses a crew answering 0 and calls its version unknown.
  • CrewChatWindow.test.tsx: the window shows the older and newer sentences; the tunnel-down case asserts the unknown sentence with its code.

Proof: PROVEN test/test_instances_remote_update.py::TestVersionsRoute::test_a_placeholder_zero_version_is_unknown_never_behind, test/test_instances_remote_update.py::TestUpdateJob::test_a_placeholder_zero_version_is_no_answer, test/test_remote_crew_capabilities.py::TestVersionGate::test_a_placeholder_zero_version_reads_as_unknown, test/test_session_control_crew.py::test_a_placeholder_zero_version_is_refused_as_unknown (head b1c3faa)

Manual verification

Rendered the real CrewChatWindow through the existing capture/remote-crew-update.html?view=window page on a local dev server, with the capabilities read answered by route interception for each case below, and checked that each frame shows its exact sentence. The "dev-box is not connected" line under the notice is the capture page's tunnel-less state, unchanged by this PR.

Screenshots / video

Crew older, dark:

crew older

Crew newer, dark:

crew newer

Version unknown, dark and light:

unknown dark

unknown light

Related Issues

Closes #25246

Sibling sweep

Swept: git grep -nE "/api/version|crewWindow.version_mismatch" -- src/kiro_crew website/src
Sibling: website/src/pages/chat-sidebar/create.ts -- changed here
Sibling: src/kiro_crew/dashboard/handlers_instances_peer.py -- changed here
Sibling: src/kiro_crew/dashboard/handlers/remote_dispatch_routes.py -- changed here
Sibling: src/kiro_crew/instances/ssh_tunnel_manager_peer.py -- changed here

Pattern harvest

Not generalizable: the defect is one placeholder version string read as a release; every reader of a crew's version now goes through one helper, so there is no second spelling to catch.

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 (see the Licensing section of CONTRIBUTING.md).

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

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The change only adds ahead and reads an all-zero placeholder as an unknown version. The local version is hardcoded (0.13.0), so no real build is turned into "unknown", and a crew answering 0 was already refused before this PR.

Notes

  • known_version is in apps/version.py, which is the app-management version module, but its callers are all about crew instances. If more crew-only rules get added there, move it to an instances-side helper.

[DESIGN-REVIEWED] 0f4f586

Description read

[DESCRIPTION-READ] 9c84ac675b22d674b79a29cc99a9bffa24297b8ed71d3248d609f5fd16e30cd4

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 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

Each difference comes from the defect reported in #25246. All readers of a crew's version now go through one helper, known_version. The only new field, ahead, has exactly one consumer.

What this change ships

Inventory (10 items) — 10 justified

Intent: a person whose crew window refuses to chat learns whether the crew's version could not be read, or which side to update. FIX.

  1. Unknown-version notice shows the gateway's reason code instead of ? and drops the "update one" advice — justified
  2. An older crew's notice says to update the crew — justified
  3. A newer crew's notice says to update this machine — justified
  4. Versions the gateway cannot order keep the existing "Update one so they match" sentence — justified
  5. A crew answering 0 or 0.0.0 counts as an unknown version, not a release — justified
  6. The capabilities reply gains an ahead field — justified
  7. An unknown version always carries a reason, capability_malformed_reply when the crew answered without a usable version — justified
  8. On the crew page, a 0 crew shows the read-failed notice instead of a "Behind" badge and Update — justified
  9. A remote update whose crew answers 0 after restarting ends unverified instead of succeeded — justified
  10. The crew dispatch refusal says "an unknown version" for a 0 crew — justified

[FIRST-PRINCIPLES-REVIEWED] 0f4f586

Description read

[DESCRIPTION-READ] 85e348d9dea0ce7a43865d41331da828c99b475f045c98240ba7917f2fed46e0

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 7, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing blocks: all three new notice sentences appear in the screenshots, and the blind reader read the older and newer cases correctly, including which side to update.

Notes

  • In version_unknown, the blind reader called "capability_unauthorized" jargon and said they "would be stuck." Unlike the older and newer sentences, it gives no next step. Add a short pointer to the place where this can be fixed, for example "Check this crew on the Remote Crew page."
  • The older and newer sentences say "Update the crew" and "Update this machine," but the reader found no way to do either ("I would not know where to go"). The PR rules out an Update link, but naming where the update happens (the crew page) would close the loop without adding a control.

[UX-REVIEWED] 0f4f586

Description read

[DESCRIPTION-READ] 1fe243af10462b41318034a388e8d42bcbeb5de61cf87e4bba17ffc07e1ad160

That sha256 names everything this verdict read: the PR description, plus the 7 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 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 0f4f586

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

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

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0f4f586

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 7, 2026 16:44
@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 7, 2026
@bolichen97
bolichen97 force-pushed the fix/25246-crew-version-banner branch from b1c3faa to 67e15f0 Compare November 7, 2026 19:58
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/dashboard/handlers_instances.py, docs/system-specs/modules/instances.md and the twelve website/src/i18n catalogs since this head was last tested (759bb96 -> 0fdf1eb); CI re-running.

The same push fixes the red Backend Tests shards: test_facade_mirror_guards.py::test_every_mirrored_facade_manifest_names_what_it_forwards failed because the new _peer_version helper was missing from the handlers_instances facade's type-checking manifest. It is listed there now.

[operator: bolichen97]

@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 readiness: checking Automated validation is still running labels Nov 7, 2026
The crew window's mismatch notice printed "?" for a version it could not
read, a placeholder "0" from a peer as if it were a release, and told the
user to "update one" without saying which side was behind.

Every reader of a crew's /api/version now treats an all-zero release as
no version. An unknown version always carries its reason, the
capabilities reply reports which side is newer, and the crew window and
New chat on crew word each case.

Closes #25246
@bolichen97
bolichen97 force-pushed the fix/25246-crew-version-banner branch from 67e15f0 to 0f4f586 Compare November 8, 2026 01:09
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in the Backend shard 5 and 6 tests since this head went red (67e15f0 on its old base -> 666f962); CI re-running.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 8, 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. On head 0f4f586 the review checked these things:

  • Every reader of a crew's version now goes through known_version: capabilities, the versions route, the dispatch refusal, and the remote-update check. Which crews are accepted does not change, because versions_compatible already refused a 0 peer.
  • ahead reuses _remote_is_behind with the arguments swapped. A parametrized test covers older, newer and equal.
  • Each changed backend line has a test that fails when the line is reverted. The build-abc case keeps a build id matching by equality.
  • All 13 catalogs translate the new keys. The merge with main is clean, and PR Readiness is green.

Done well: an unknown version always carries a reason code, because setdefault keeps the code the read failure reported.

  • Optional: the New chat on crew wording in website/src/pages/chat-sidebar/create.ts:372 has no test that fails if it is reverted. A case with version: '' in ChatSidebar.createMenu.test.tsx would pin it.
  • Optional: a crew that answers 0 now shows the read-failed notice and no Update action. The body discloses this. If that state shows up often, a follow-up could offer Restart on that row.
  • Optional: open PR #21614 moves the old version_mismatch call into website/src/hooks/folderCrew.ts. Whoever rebases it after this lands should send that call through crewVersionMismatchText(caps).

@bolichen97
bolichen97 merged commit 3ea0a5f into main Nov 8, 2026
99 of 100 checks passed
@bolichen97
bolichen97 deleted the fix/25246-crew-version-banner branch November 8, 2026 02:32
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 8, 2026
bolichen97 added a commit that referenced this pull request Nov 9, 2026
)

The crew window's mismatch notice printed "?" for a version it could not
read, a placeholder "0" from a peer as if it were a release, and told the
user to "update one" without saying which side was behind.

Every reader of a crew's /api/version now treats an all-zero release as
no version. An unknown version always carries its reason, the
capabilities reply reports which side is newer, and the crew window and
New chat on crew word each case.

Closes #25246

Backport note: en.context.json adds only the version_unknown line (the
neighbouring elicitationCard.dismiss key belongs to unreleased #23973),
and the instances.md rows take only this fix's sentences on release's
row text.

(cherry picked from commit 3ea0a5f)
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.

Remote-instance version banner renders remote version as '0'; conflates unknown / booting / real skew

2 participants