Skip to content

fix(doctor): warn, not fail, on a kas engine the first chat downloads - #31731

Merged
bolichen97 merged 1 commit into
mainfrom
fix/22583-doctor-kas-fresh-install
Nov 8, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/22583-doctor-kas-fresh-install

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When the gateway will download Kiro Crew's own KAS engine at the first chat, kirocrew doctor warns that the engine is not there yet instead of failing, so a fresh install without kiro-cli passes.

On a fresh install with no kiro-cli, KAS runs Kiro Crew's own engine (the automatic bundle route), and the gateway downloads the pinned engine at the first chat. Until then kirocrew doctor prints bundle: ⚠ not installed yet and also adds Kiro Crew's KAS engine is not installed yet (the first chat downloads it) to its issue list. So a healthy fresh install ends with ❌ Fix these issues: ... and exit 1. The reporter's re-run on main in #22583 shows this line in the red summary.

Why it matters

kirocrew doctor is the first command a new user runs. A red summary for a state the gateway fixes on its own makes a healthy install look broken, and teaches people to ignore doctor.

Not a goal

What changed (motivation → approach → change)

Symptom: a fresh install's doctor summary is red. Cause: the KAS section counts "the pinned engine is not on disk yet" as an issue on the automatic route, even though the gateway downloads it at the first chat. Change: on the automatic route, a missing pin keeps its ⚠ row and its download hint, and is an issue only when the gateway will not install it on this host; the row then says that instead of promising a download. That answer comes from backend_install._engine_installable_here, the check the dashboard and the gateway start already use: an unsupported platform or glibc, or a version override the gateway does not install unattended. It checks no network, so an offline host still fails at the first chat, as the ⚠ row warns. This is the same rule #24235 applied to the git and config rows.

State on the bundle route Before After
automatic route, pin missing, gateway can download it here ⚠ + issue ⚠, no issue
automatic route, pin missing, gateway will not install it here ⚠ "downloads it at the first chat" + issue ⚠ "will not install it on this host" + issue saying the same
agent.kas_bundle on, pin missing ⚠ + issue unchanged
pinned directory incomplete, or engines directory unreadable ❌ + issue unchanged

"Pin missing" covers both an empty engines directory and one holding only an older version. The kirocrew doctor list in docs/system-specs/modules/cli.md states the rule.

Backwards compatibility

Compatible: doctor drops one issue-list entry for a state the gateway resolves at the first chat; every other state still counts as an issue, and the one the gateway will not fix says so in its row and issue text.

Removes nothing: the bundle: row and its download hint still print; only the summary line and exit code change for that state, and only the kirocrew doctor command reads the issue list.

Tests

In test/test_cli_doctor_agent_auth.py::TestDoctorKasBundle, each parametrized over an empty engines directory and one holding only an older version:

  • test_a_pin_the_gateway_downloads_on_the_automatic_route_is_not_an_issue: the ⚠ row and the first-chat hint print, and the issue list stays empty.
  • test_a_pin_this_host_cannot_download_stays_an_issue: the row says the gateway will not install the engine on this host and makes no download promise, and one issue says the same.

The existing agent.kas_bundle-on tests keep pinning that route's issues unchanged.

Proof: PROVEN test/test_cli_doctor_agent_auth.py::TestDoctorKasBundle::test_a_pin_the_gateway_downloads_on_the_automatic_route_is_not_an_issue[on_disk0], test/test_cli_doctor_agent_auth.py::TestDoctorKasBundle::test_a_pin_the_gateway_downloads_on_the_automatic_route_is_not_an_issue[on_disk1], test/test_cli_doctor_agent_auth.py::TestDoctorKasBundle::test_a_pin_this_host_cannot_download_stays_an_issue[on_disk0], test/test_cli_doctor_agent_auth.py::TestDoctorKasBundle::test_a_pin_this_host_cannot_download_stays_an_issue[on_disk1] (head f672113)

Determinism: the new tests passed 20 runs at -n0, 10 runs at -n 4 --dist loadgroup --max-worker-restart=2 beside test_cli_doctor_parts.py and test_cli_doctor_refactor_report.py, and one shuffled run of the whole file (seed 9572).

Manual verification

N/A — unit coverage sufficient: the tests run the real _doctor_kas with only the route, the engine probes and the installable check pinned.

Screenshots / video

N/A — no frontend change.

Related Issues

Part of #22583

Sibling sweep

Swept: git grep -n "issues.append" -- src/kiro_crew/cli_doctor_parts/kas_relay.py
Sibling: src/kiro_crew/cli_doctor_parts/kas_relay.py:157 -- changed here

Pattern harvest

Not generalizable: each doctor row decides its own normal state from its own probe, so there is no shared shape to lint for.

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 19:46
@bolichen97
bolichen97 requested a review from Zedmor November 6, 2026 19:46
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 20:13
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision fb568c83c2d89fdba2b901ccd17510a2faf4abaf 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

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the change reuses the existing _engine_installable_here predicate that the gateway start and dashboard already use, and it affects only doctor's summary.

Notes

  • In the "older version on disk" case, the PR assumes the gateway also downloads the new pin when a stale engine is present, not only when the directory is empty. The tests mock _engine_installable_here, so they don't check that refresh path. It's worth confirming that the gateway-start path (backend_install.py:276) also installs the pin in that state.

[DESIGN-REVIEWED] fb568c8

Description read

[DESCRIPTION-READ] 18dfd38d90f9aa698a7b19f774eacb2f5b6b7f685352c80f898062ebb2c1e0a6

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 fb568c83c2d89fdba2b901ccd17510a2faf4abaf — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] fb568c8

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

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

@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 fb568c83c2d89fdba2b901ccd17510a2faf4abaf — 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

The fix reuses the existing backend_install._engine_installable_here check and is grounded in #22583. Reversing the "issue because offline fails" pin is stated openly and argued.

Notes

  • Item 1 — inherited: the deleted comment said "Still a ⚠ with an issue, because an offline host fails then". The description gives its reason for dropping that ("an offline host still fails at the first chat, as the ⚠ row warns"), so it is not a silent reversal.

What this change ships

Inventory (4 items) — 4 justified

Intent: a fresh install with no kiro-cli passes kirocrew doctor and does not end red for an engine the gateway downloads on its own. FIX.

  1. On the automatic route, a missing pinned engine that the gateway can download no longer adds an issue, so doctor exits 0 — justified
  2. On the automatic route, when this host cannot install the pin, the issue text says the gateway will not install it here — justified
  3. In that same case, the row hint drops the "downloads it at the first chat" promise — justified
  4. The cli.md doctor list states the new rule — justified

[FIRST-PRINCIPLES-REVIEWED] fb568c8

Description read

[DESCRIPTION-READ] 37ca757fdf593ea0fa2982eb19acadd0e409c76f5e7689f656d99e03d4b2ab96

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

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fb568c8

False positive or not applicable? A repository writer can comment:
/ai-review override gpt fb568c83c2d89fdba2b901ccd17510a2faf4abaf 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 force-pushed the fix/22583-doctor-kas-fresh-install branch from f672113 to f2e6fe8 Compare November 7, 2026 01:44
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/cli.md since this head's CI ran (8dbdf04 -> 678769e); CI re-running. The new base also carries the fixes for the two red tests this head inherited from main (#31625, #31803); the patch itself is unchanged.

[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
@bolichen97
bolichen97 force-pushed the fix/22583-doctor-kas-fresh-install branch from f2e6fe8 to 76f6feb Compare November 7, 2026 05:00
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/cli.md since this head went green (678769e -> e4611c5); CI re-running. The previous head's review lanes and the stub E2E job did not finish (an API rate limit and a job timeout), so this push also re-runs them; the patch itself is unchanged.

[operator: bolichen97]

@bolichen97
bolichen97 force-pushed the fix/22583-doctor-kas-fresh-install branch from 76f6feb to 2758066 Compare November 7, 2026 07:57
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/cli.md since this head went green (e4611c5 -> 5f7f8d1); CI re-running. The previous head 76f6feb never got verdicts from its review lanes (the CI token ran out of API quota), so this push also gives them a fresh run. The commit is unchanged by the rebase; the related backend tests pass on the new base.

[operator: bolichen97]

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] The red Backend Tests shard 2 (Linux and Windows, and the Coverage Gate that follows it) is test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget, which is red on main too: the security package is 34855 lines on main against a 34845 budget, and this PR touches no file in it. #32183 raises that budget; this PR waits for it to merge and then re-runs. The review lanes, Dependency License Gate and Sensitive Change Review on 2758066 failed because the CI installation token hit its API rate limit, not on this change.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Re-sync budget reset

This head has no green to lose: its only test red is a check that was red on main, which main has since fixed, and its review lanes did not run because of an API rate limit. A pull_request re-run keeps the old merge commit, so only a new head on current main can clear it. Granting one more re-sync for that.

[operator: bolichen97]

@bolichen97
bolichen97 force-pushed the fix/22583-doctor-kas-fresh-install branch from 2758066 to eccdc0d Compare November 7, 2026 13:13
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/ (kas-auth.md and four more specs beside cli.md; no file this PR touches) since this head went green (5f7f8d1 -> f289a6d); CI re-running. The new base carries main's fix for the red line-budget test (#32252), and the commit is unchanged by the rebase; the related doctor tests and the line-budget test pass on the new base.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: checking Automated validation is still running 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 7, 2026
@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: checking Automated validation is still running labels Nov 7, 2026
@bolichen97
bolichen97 force-pushed the fix/22583-doctor-kas-fresh-install branch from 6b19a2a to 89bdd6b Compare November 7, 2026 19:55
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/cli.md since this head's CI ran (d27a5fd -> 0fdf1eb); CI re-running. The patch is unchanged. The new head also re-runs the GPT 6.1 lane, whose verdict for 6b19a2a was not published because the shared token hit its rate limit.

[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
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] The red Backend Tests shards 5 and 6 (Linux and Windows), and the Coverage Gate that follows them, are main's, not this PR's. test/test_held_note_turn_starts.py::test_every_turn_start_flushes_the_hold_or_is_listed, test/test_held_note_turn_starts.py::test_every_listed_turn_start_still_skips_the_flush and test/test_dashboard_server_composition_contract.py::test_the_lazy_imports_stay_inside_the_functions_that_need_them failed with the same assertions on main's own push run https://github.com/kirodotdev/KiroCrew/actions/runs/42413945602 (c3b50d3), and this PR touches none of the files they check. #32606 fixed all three and has merged.

A rerun tests the same merge commit, so taking that fix needs a rebase, and this PR has used its three re-syncs (main keeps moving in docs/system-specs/modules/, beside cli.md). A maintainer's Re-sync budget reset comment here lets the next pass rebase onto main and re-run CI. The patch is unchanged since 89bdd6b, and every review lane is green on it.

On a host with no kiro-cli, KAS takes Kiro Crew's own engine on the
automatic route, and the gateway downloads the pinned engine at the
first chat. kirocrew doctor printed a missing pin there as a warning
but also put it in its issue list, so a healthy fresh install ended
with "Fix these issues" and exit 1.

On the automatic route a missing pin now keeps its warning row and
download hint, and is an issue only when the gateway will not install
it on this host (an unsupported platform or glibc, or a version
override it does not install unattended); the row then says so instead
of promising a download. An operator who turned
agent.kas_bundle on, an incomplete pinned directory and an unreadable
engines directory still count as issues.
@bolichen97
bolichen97 force-pushed the fix/22583-doctor-kas-fresh-install branch from 89bdd6b to fb568c8 Compare November 8, 2026 05:29
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Rebased onto main's fix for the red Backend shards 5 and 6 (#32606): 89bdd6b -> fb568c8, onto e9cbb5b. This is a red-main re-sync, not a green-age one; the patch is unchanged. CI re-running.

Local gate passed on this tree: the changed and related doctor and kas tests (997 of 998), flake8, isort, black, mypy, the flake-pattern ratchet and semgrep. Local GPT and local Opus review found nothing. The one local red, test/test_acp_harness_contract.py::test_a_missing_self_served_binary_names_its_install_command[copilot], comes from a ~/.mcp.json in the review host's home directory, not from this diff.

@github-actions github-actions Bot added readiness: checking Automated validation is still running 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
@bolichen97
bolichen97 merged commit d549bec into main Nov 8, 2026
97 of 98 checks passed
@bolichen97
bolichen97 deleted the fix/22583-doctor-kas-fresh-install branch November 8, 2026 06:36
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 8, 2026
buluoray added a commit that referenced this pull request Nov 8, 2026
…#31731)

On a host with no kiro-cli, KAS takes Kiro Crew's own engine on the
automatic route, and the gateway downloads the pinned engine at the
first chat. kirocrew doctor printed a missing pin there as a warning
but also put it in its issue list, so a healthy fresh install ended
with "Fix these issues" and exit 1.

On the automatic route a missing pin now keeps its warning row and
download hint, and is an issue only when the gateway will not install
it on this host (an unsupported platform or glibc, or a version
override it does not install unattended); the row then says so instead
of promising a download. An operator who turned
agent.kas_bundle on, an incomplete pinned directory and an unreadable
engines directory still count as issues.

(cherry picked from commit d549bec)

Original author: @bolichen97 (picked by hand: conflict only in docs/system-specs/modules/cli.md)
buluoray added a commit that referenced this pull request Nov 8, 2026
…#31731)

On a host with no kiro-cli, KAS takes Kiro Crew's own engine on the
automatic route, and the gateway downloads the pinned engine at the
first chat. kirocrew doctor printed a missing pin there as a warning
but also put it in its issue list, so a healthy fresh install ended
with "Fix these issues" and exit 1.

On the automatic route a missing pin now keeps its warning row and
download hint, and is an issue only when the gateway will not install
it on this host (an unsupported platform or glibc, or a version
override it does not install unattended); the row then says so instead
of promising a download. An operator who turned
agent.kas_bundle on, an incomplete pinned directory and an unreadable
engines directory still count as issues.

(cherry picked from commit d549bec)

Original author: @bolichen97 (picked by hand: conflict only in docs/system-specs/modules/cli.md)
buluoray added a commit that referenced this pull request Nov 8, 2026
…#31731)

On a host with no kiro-cli, KAS takes Kiro Crew's own engine on the
automatic route, and the gateway downloads the pinned engine at the
first chat. kirocrew doctor printed a missing pin there as a warning
but also put it in its issue list, so a healthy fresh install ended
with "Fix these issues" and exit 1.

On the automatic route a missing pin now keeps its warning row and
download hint, and is an issue only when the gateway will not install
it on this host (an unsupported platform or glibc, or a version
override it does not install unattended); the row then says so instead
of promising a download. An operator who turned
agent.kas_bundle on, an incomplete pinned directory and an unreadable
engines directory still count as issues.

(cherry picked from commit d549bec)

Original author: @bolichen97 (picked by hand: conflict only in docs/system-specs/modules/cli.md)
buluoray added a commit that referenced this pull request Nov 8, 2026
…#31731)

On a host with no kiro-cli, KAS takes Kiro Crew's own engine on the
automatic route, and the gateway downloads the pinned engine at the
first chat. kirocrew doctor printed a missing pin there as a warning
but also put it in its issue list, so a healthy fresh install ended
with "Fix these issues" and exit 1.

On the automatic route a missing pin now keeps its warning row and
download hint, and is an issue only when the gateway will not install
it on this host (an unsupported platform or glibc, or a version
override it does not install unattended); the row then says so instead
of promising a download. An operator who turned
agent.kas_bundle on, an incomplete pinned directory and an unreadable
engines directory still count as issues.

(cherry picked from commit d549bec)

Original author: @bolichen97 (picked by hand: conflict only in docs/system-specs/modules/cli.md)
buluoray added a commit that referenced this pull request Nov 8, 2026
…#31731)

On a host with no kiro-cli, KAS takes Kiro Crew's own engine on the
automatic route, and the gateway downloads the pinned engine at the
first chat. kirocrew doctor printed a missing pin there as a warning
but also put it in its issue list, so a healthy fresh install ended
with "Fix these issues" and exit 1.

On the automatic route a missing pin now keeps its warning row and
download hint, and is an issue only when the gateway will not install
it on this host (an unsupported platform or glibc, or a version
override it does not install unattended); the row then says so instead
of promising a download. An operator who turned
agent.kas_bundle on, an incomplete pinned directory and an unreadable
engines directory still count as issues.

(cherry picked from commit d549bec)

Original author: @bolichen97 (picked by hand: conflict only in docs/system-specs/modules/cli.md)
buluoray added a commit that referenced this pull request Nov 8, 2026
…#31731)

On a host with no kiro-cli, KAS takes Kiro Crew's own engine on the
automatic route, and the gateway downloads the pinned engine at the
first chat. kirocrew doctor printed a missing pin there as a warning
but also put it in its issue list, so a healthy fresh install ended
with "Fix these issues" and exit 1.

On the automatic route a missing pin now keeps its warning row and
download hint, and is an issue only when the gateway will not install
it on this host (an unsupported platform or glibc, or a version
override it does not install unattended); the row then says so instead
of promising a download. An operator who turned
agent.kas_bundle on, an incomplete pinned directory and an unreadable
engines directory still count as issues.

(cherry picked from commit d549bec)

Original author: @bolichen97 (picked by hand: conflict only in docs/system-specs/modules/cli.md)
buluoray added a commit that referenced this pull request Nov 8, 2026
…#31731)

On a host with no kiro-cli, KAS takes Kiro Crew's own engine on the
automatic route, and the gateway downloads the pinned engine at the
first chat. kirocrew doctor printed a missing pin there as a warning
but also put it in its issue list, so a healthy fresh install ended
with "Fix these issues" and exit 1.

On the automatic route a missing pin now keeps its warning row and
download hint, and is an issue only when the gateway will not install
it on this host (an unsupported platform or glibc, or a version
override it does not install unattended); the row then says so instead
of promising a download. An operator who turned
agent.kas_bundle on, an incomplete pinned directory and an unreadable
engines directory still count as issues.

(cherry picked from commit d549bec)

Original author: @bolichen97 (picked by hand: conflict only in docs/system-specs/modules/cli.md)
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