Skip to content

fix: recognise the windows toolbox launcher in the doctor cli row - #35530

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/32803-windows-toolbox-doctor
Nov 18, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/32803-windows-toolbox-doctor

Conversation

@dodgeblaster

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On a Windows install managed by Toolbox, kirocrew doctor stops saying the kirocrew on PATH belongs to a different install when it runs this same install's version.

Every kirocrew doctor run on a Windows Toolbox install prints "kirocrew CLI on PATH belongs to a different install than this one", even though %LOCALAPPDATA%\Toolbox\bin\kirocrew.exe runs this install's version. The Toolbox check behind that row only knew the POSIX layout.

Why it matters

The warning tells the user to run kirocrew setup from the install that should own the name, which on this layout acts on a false premise. An always-on warning also hides the real case the row exists for: another install owning the name.

Not a goal

  • Asking Toolbox's own metadata for the active version: the row keeps asking the launcher, as the POSIX arm does.
  • Changing the version probe (its sandbox wrapper, timeout or exact version-line match).
  • Any other Windows Toolbox surface (service units, the token mint launcher list).

What changed (motivation → approach → change)

The row trusts a Toolbox launcher only when two gates pass: the PATH entry resolves to the POSIX toolbox-exec dispatcher, and the running interpreter lives under ~/.toolbox. On Windows the launcher is a per-tool kirocrew.exe in %LOCALAPPDATA%\Toolbox\bin and the install lives under %LOCALAPPDATA%\Toolbox, so both gates failed and the row fell through to the warning.

  • The doctor row also accepts a PATH entry whose directory is the Windows Toolbox bin directory (realpath, case-normalised).
  • env.is_toolbox_install also accepts an interpreter under the Windows Toolbox root.
  • Both read one new env._windows_toolbox_root; _windows_toolbox_bin_dir is now bin under it and returns the same path as before.
  • Off Windows nothing new is read; the version probe after the gates is unchanged, so a launcher printing any other version still warns.

Backwards compatibility

Compatible: on POSIX both gates behave as before, and on Windows they only accept more; the version probe still decides.

Removes nothing: the change only widens which layouts the two gates recognise.

Tests

test/test_cli_doctor_install.py::TestWindowsToolboxPathLauncher drives the real is_toolbox_install and the doctor row with IS_WINDOWS and LOCALAPPDATA pinned:

  • the Toolbox bin launcher printing this version gives the clean (Toolbox launcher, same version) row, and is_toolbox_install() is True;
  • the same layout printing another version still warns;
  • a kirocrew.exe outside the Toolbox bin directory is never probed;
  • an install outside the Toolbox root is never probed, and is_toolbox_install() is False;
  • off Windows the Windows layout is not read.

The existing POSIX TestToolboxPathLauncher tests pass unchanged.

Proof: PROVEN test/test_cli_doctor_install.py::TestWindowsToolboxPathLauncher::test_same_version_through_the_toolbox_bin_launcher_is_clean (head 7eda1a1)

Manual verification

Not run on a real Windows Toolbox host; the tests pin the Windows layout on Linux. Case-insensitive path matching rests on os.path.normcase, which only lowercases on Windows, so the Windows CI shard is the run that exercises it.

Related Issues

Fixes #32803

Related: #23172 and #24665 (the POSIX half), #24563 (added _windows_toolbox_bin_dir).

Sibling sweep

Swept: git grep -nE '".toolbox"|toolbox-exec|.toolbox/' -- 'src/*.py'
Sibling: src/kiro_crew/doctor_checks/install.py -- changed here
Sibling: src/kiro_crew/env.py -- changed here
Sibling: src/kiro_crew/service/common.py -- not affected -- builds POSIX service unit paths only
Sibling: src/kiro_crew/instances/token_mint.py -- not affected -- a POSIX launcher candidate list, not an install-ownership check

Pattern harvest

Not generalizable: a platform layout the POSIX fix declared out of scope; the general rule (route platform paths through one helper per platform) is already how env builds the Windows Toolbox bin directory.

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

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 11, 2026
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision fb3a15d4fea1d1a853b39d63515589c67286cf0c 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 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: a diagnostic-only widening, guarded by the unchanged version probe. doctor is the only reader of is_toolbox_install.

Notes

  • The Windows branch has not been run on a real Toolbox host. The cost of being wrong is limited to a doctor row, which a revert fixes cleanly. When it ships, confirm that a real kirocrew.exe launcher answers --version with exactly this install's version line.

[DESIGN-REVIEWED] fb3a15d

Description read

[DESCRIPTION-READ] 9c494eee13e9586bbaf392487d1178c985c8c3643cabceb57501cc2bb9b7242b

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of fb3a15d4fea1d1a853b39d63515589c67286cf0c — 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. This is a fix for #32803, made in the two gates that caused the false warning. is_toolbox_install has one consumer (this doctor row), so making it accept the Windows layout changes nothing else.

Inventory (4 items) — 4 justified

Intent: on a Windows Toolbox install, kirocrew doctor stops falsely saying that the kirocrew on PATH belongs to another install. FIX.

  1. On Windows, the doctor CLI row now treats a PATH entry inside %LOCALAPPDATA%\Toolbox\bin as a Toolbox launcher. The version probe still makes the final call. — justified
  2. On Windows, env.is_toolbox_install() now returns True for an interpreter under the Windows Toolbox root. Its only consumer is doctor_checks/install.py:313. — justified
  3. New private helper env._windows_toolbox_root; _windows_toolbox_bin_dir now builds bin under it, so the path-building logic is not duplicated. — justified
  4. Docstrings and the comment on the clean row now say "a Toolbox launcher" instead of "the dispatcher". — justified

[FIRST-PRINCIPLES-REVIEWED] fb3a15d

Description read

[DESCRIPTION-READ] 8a8fc91564d1ed02b76ce531c84557d0dc0b752a75e1c8f486f599e29fc52f93

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] fb3a15d

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

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

@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased onto main a0bf0ca: the only reds on the previous head were test/test_mcp_remote_transport.py::TestRewriter (Backend Tests shard 8, Linux and Windows), which fail the same way on the old base 3703c2e and are fixed on main by #35541. This PR's diff is unchanged (same 3 files); CI re-running.

@dodgeblaster
dodgeblaster force-pushed the fix/32803-windows-toolbox-doctor branch from 7eda1a1 to fb0cac0 Compare November 11, 2026 22:11
@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 11, 2026
@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fb3a15d

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

On a Windows install managed by Toolbox, `kirocrew doctor` always said
the `kirocrew` on PATH belonged to a different install. The Toolbox
check only knew the POSIX layout: the launcher had to resolve to the
shared `toolbox-exec` dispatcher, and the install had to run from
under `~/.toolbox`. On Windows the launcher is
`%LOCALAPPDATA%\Toolbox\bin\kirocrew.exe` and the install lives under
`%LOCALAPPDATA%\Toolbox`, so neither gate passed.

The row now also accepts a launcher whose directory is the Windows
Toolbox bin directory, and `is_toolbox_install` also accepts an
interpreter under the Windows Toolbox root. Both paths come from one
new `env._windows_toolbox_root`, which `_windows_toolbox_bin_dir` now
builds on. The version probe after the gates is unchanged: sandboxed,
and clean only on an exact version-line match.

Fixes #32803
@dodgeblaster
dodgeblaster force-pushed the fix/32803-windows-toolbox-doctor branch from fb0cac0 to fb3a15d Compare November 12, 2026 05:43
@dodgeblaster

Copy link
Copy Markdown
Contributor Author

Rebased onto main 758e63c to pick up the fixes for main's own reds (#35625, #35725). This PR's diff is unchanged (same 3 files); CI re-running.

@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 12, 2026
@dodgeblaster
dodgeblaster marked this pull request as ready for review November 12, 2026 18:53
@dodgeblaster
dodgeblaster requested review from a team and KiroCrewCaptain as code owners November 12, 2026 18:53
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 12, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 12% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

This PR widens the two gates behind the doctor CLI row so they recognise the Windows Toolbox layout:

  • a PATH entry whose directory, after realpath and normcase, is %LOCALAPPDATA%\Toolbox\bin;
  • an interpreter under %LOCALAPPDATA%\Toolbox.

I checked the code rather than trusting the description:

  • Same bin dir as before. _windows_toolbox_bin_dir still returns the same path. _validated_bin_dir only checks for an absolute path with no pathsep or NUL, so validating the root and then appending bin is equivalent. Its other caller, augmented_path, is unaffected.
  • POSIX unchanged. is_toolbox_install keeps the same POSIX semantics (is_relative_to on resolved roots). Its only consumer is the doctor row.
  • Version probe still decides. The probe is unchanged, so a launcher printing another version still warns.
  • The probe actually runs on Windows. I followed it through wrap_argv. Windows has no sandbox backend, but sandbox_allow_unsandboxed_exec defaults to True there, so the strict-mode probe runs instead of raising. On a governed host it fails closed to the warning, which is the same posture as before.
  • No new trust exposure. The probe was already

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

@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 12, 2026
@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 18, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 18, 2026 01:31

@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. Verified on head fb3a15d: the _windows_toolbox_bin_dir refactor returns the same path as before, because _validated_bin_dir only checks shape. POSIX behaviour is unchanged. Both new branches sit behind IS_WINDOWS. The exact-version probe still decides the row and still runs through the strict sandbox wrapper. Mutation runs show that reverting either fix hunk turns test_same_version_through_the_toolbox_bin_launcher_is_clean red. PR Readiness is green on this head, including all Windows backend shards.

Done well: _windows_toolbox_root is now the one owner of the Windows Toolbox location, so the doctor gate and the PATH builder cannot disagree. The new tests drive the real is_toolbox_install and cover the negative cases too.

  • Optional: test_the_windows_layout_is_not_read_off_windows does not pin the IS_WINDOWS gate in _is_toolbox_launcher, because the gate in is_toolbox_install hides it. Asserting _is_toolbox_launcher(str(launcher)) is False there would close that gap.
  • Optional: the Proof line in ## Tests names head 7eda1a1. Refresh it to fb3a15d the next time the body is edited.
  • Optional: one rewrapped docstring line in doctor_checks/install.py (line 297) is 101 characters long.

@KiroCrewCaptain
KiroCrewCaptain merged commit 7ccdd3d into main Nov 18, 2026
170 of 182 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/32803-windows-toolbox-doctor branch November 18, 2026 01:31
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 18, 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

2 participants