Skip to content

fix(settings): explain the windows cloud launcher block once - #34340

Merged
bolichen97 merged 2 commits into
mainfrom
fix/32150-windows-cloud-setup
Nov 10, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/32150-windows-cloud-setup

Conversation

@JLargent42

@JLargent42 JLargent42 commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On a Windows gateway, Settings → Remote Crew → Set up a new one says once, plainly, that the dashboard's cloud launcher needs Linux or macOS, says how to launch anyway, links a guide, and never suggests the AWS credentials are wrong.

On a Windows gateway the dashboard's cloud launcher refuses with 400 posix_host_required before it makes any AWS call. The Set-up tab still drew the whole AWS checklist around that refusal: the raw "cloud provisioning requires a POSIX host (Linux/macOS); use WSL on Windows" error, a credentials line ("your credentials were not checked", and "Could not reach AWS with this profile" on 0.12.0), an Ask the agent button, and a disabled Launch saying "Finish the AWS setup above to enable this." Nothing linked to a guide, nothing said WSL needs admin rights and a restart, and nothing mentioned the CLI launcher, which does run on Windows.

Why it matters

Windows is the most common laptop. A Windows user who picks a cloud crew hits a dead end that also looks like their AWS credentials are broken, while aws sts get-caller-identity works fine for them. Seen in 7 of 7 clean-machine onboarding runs (#18614).

Not a goal

What changed (motivation → approach → change)

Symptom: the Windows refusal shows up as one error among AWS checklist rows that blame credentials. Root cause: the Set-up tab treated posix_host_required like any other preflight failure, so it drew the checklist, the generic error notice and the launch form as usual.

Change:

  • New RemoteCrewWindowsNotice (website/src/pages/settings/RemoteCrewWindowsNotice.tsx) replaces the built-in lane's prerequisites card and launch form when the gateway platform reads windows (useGatewayPlatform, read from the cached prerequisite status), or when the preflight answers posix_host_required (in case the platform signal isn't cached yet). In one card it says the launcher needs Linux or macOS, and that the AWS profile wasn't used so it isn't the problem. It then gives the two ways forward. One is kirocrew cloud launch in PowerShell, the launcher install.ps1 already hands off to. A desktop install calls it by its full path, because the installer adds nothing to PATH. The other is Kiro Crew inside WSL, which needs administrator rights and a restart. It ends with a link to the guide.
  • When the preflight refusal is how the tab learned it, that sentence renders through ErrorNotice with the rejection's report and the agent hand-off (the errors-use-error-notice rule). A known-Windows gateway sends no preflight, so nothing is rejected and the sentence is plain text.
  • docs/guides/windows-install.md gains "Launch a cloud crew from Windows" and a per-feature table row. The section covers the PowerShell path, with the desktop shim's full path and a note that installing the AWS CLI usually needs admin rights. It also covers the WSL steps: wsl --install, the AWS CLI and profile inside Ubuntu, the one-line installer, opening the dashboard from Windows, and the port 5476 clash with the desktop app.
  • Five new strings are added to every locale catalog, and en-XA is regenerated.
  • The instances spec (docs/system-specs/modules/instances.md) and the feature map record the notice.

Backwards compatibility

Compatible: no API, response or config changes. Only how the Set-up tab draws on a Windows gateway changes, and Launch was already unusable there.

Removes nothing: on Windows the hidden checklist and Launch could never succeed, because the server refuses every launch with posix_host_required. POSIX gateways render exactly as before (pinned by a test below).

Tests

website/src/test/RemoteCrewPanelWindowsGateway.test.tsx:

  • "says once that the launcher needs Linux or macOS when the preflight answers posix_host_required": the notice shows the not-the-problem sentence inside its one ErrorNotice alert, which carries the page's only Ask the agent button. It also shows the kirocrew cloud launch path with the desktop PATH note, the admin-and-restart note and the guide link. The page shows no POSIX error, no credential text, no "Finish the AWS setup above" and no Launch.
  • "runs no AWS check at all when the gateway is known to be Windows": cloudPreflight is never called, there is no alert and no Ask the agent, and the page shows the same absences.
  • "keeps the AWS checklist on a POSIX gateway": Launch still renders and the notice does not.

On main (0cd8a209), the first two fail (Unable to find role="heading" and name /Cloud crews can’t launch from this Windows dashboard/). A probe on main showed the POSIX error, "credentials were not checked", "Finish the AWS setup above", Ask the agent and Launch all on screen.

Proof: not provable -- frontend test (prove.py runs Python only)

All 13 RemoteCrewPanel* / SettingsRemoteCrewPanel* test files pass (273 tests). npm run typecheck, eslint on the touched files, npm run i18n:check (all diff-scoped checks PASS, en-XA in sync, DNT intact), scripts/docs-lint.sh and scripts/check_feature_map.py pass.

Manual verification

I rendered the built SPA (website/dist) in headless Chromium with every /api/** call stubbed. No gateway and no AWS account were used. Two scenarios, each in dark and light:

  • Prerequisite status platform Windows: the notice renders, and /api/cloud/preflight was called 0 times.
  • Platform unknown, preflight answering 400 posix_host_required: the same notice renders.

Each frame was checked: no "requires a POSIX host", no "credentials were not checked", no "Finish the AWS setup above". Ask the agent appears on none of the known-Windows frames and exactly once, inside the notice, on the refused-preflight frames.

Not verified: a real Windows machine, or running kirocrew cloud launch end to end on Windows.

Screenshots / video

Windows gateway, dark:

Remote Crew Set-up tab on a Windows gateway, dark: one card titled Cloud crews can’t launch from this Windows dashboard, saying the AWS profile wasn’t used so it isn’t the problem, the PowerShell path with the desktop PATH note, the WSL path, and a Read the Windows guide link

Same card, light:

The same notice in the light theme

Platform not cached yet and the preflight answered posix_host_required: the same card, with its first sentence in the shared error notice and its Ask the agent hand-off:

Dark: the notice with its first sentence inside an error notice that carries Ask the agent

Light

Light

Related Issues

Fixes #32150

Sibling sweep

Swept: git grep -n "posix_host_required" -- website/src src/kiro_crew
Sibling: website/src/pages/settings/RemoteCrewPanel.tsx:381 -- not affected -- the launch-history route is not POSIX-gated, and the crew list already treats that code as "no history"
Sibling: website/src/apps/aws-control/AwsControlPage.tsx -- not affected -- it already shows its own Windows notice (add_accounts_unsupported) when the server reports the platform unsupported
Sibling: website/src/pages/settings/RemoteCrewPanelLaunch.tsx -- not affected -- the launch progress card only renders a job that exists, and a Windows gateway cannot create one

Pattern harvest

Not generalizable: one tab drew a host-capability refusal as one failed check among AWS rows. The other Windows-gated surface (AWS Control) already handles it up front.

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.

On a Windows gateway the dashboard's cloud launcher answers 400
posix_host_required before any AWS call, but the Set-up tab still drew
the AWS checklist: the raw POSIX error, a credentials row saying they
were not checked, Ask the agent, and a disabled Launch, with no guide.

The tab now shows one notice instead. It says the launcher needs a
Linux or macOS gateway and the profile was not checked, and names the
two ways forward: the CLI launch wizard in PowerShell, or a gateway
inside WSL, which needs admin rights and a restart. A gateway known to
be Windows skips the preflight entirely. The Windows guide gains the
WSL steps the notice links to.

Fixes #32150
@JLargent42
JLargent42 requested review from a team and KiroCrewCaptain as code owners November 10, 2026 05:21
@JLargent42
JLargent42 requested a review from buluoray November 10, 2026 05:21
@JLargent42 JLargent42 self-assigned this Nov 10, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 10, 2026
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 14cff1809f8d7788a639df67400d555a29e5f1d9 — 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: every item serves the issue's single job, a Windows gateway's Set-up tab saying once why launch can't work. The Windows path reuses the existing useGatewayPlatform hook and posix_host_required code; POSIX rendering is untouched.

What this change ships

Inventory (8 items) — 8 justified

Intent: a Windows user setting up a cloud crew learns once, without being told their AWS credentials are wrong, that the dashboard launcher needs Linux or macOS, and what to do instead. This is a FIX (#32150, #18614).

  1. On a Windows gateway, the AWS checklist, the raw error and the disabled Launch are replaced by one notice card — justified
  2. A gateway known to be Windows no longer sends the AWS preflight probe — justified
  3. If the platform signal is missing, a preflight refused with posix_host_required shows the same card — justified
  4. In that refused case, the first sentence renders through ErrorNotice with the report and the single Ask the agent — justified
  5. The card links to a new "Launch a cloud crew from Windows" guide section (PowerShell CLI path, WSL steps) — justified
  6. Five new strings in every locale catalog, with en-XA regenerated — justified
  7. The instances spec and the feature map record the notice — justified
  8. A settingsCoverage unmapped-panel entry for the new component — justified

[FIRST-PRINCIPLES-REVIEWED] 14cff18

Description read

[DESCRIPTION-READ] 1943861440eb508b3e9d8d2cd9899bf67775ab0b3f2144cccb50be18da8c9cb0

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the server's posix_host_required gate is still the authority, the client only reads it early through the existing useGatewayPlatform signal, and POSIX gateways render unchanged.

Notes

  • The notice now comes from two sources: the platform label (classifyPlatform → 'windows') and the server's own POSIX check. If the server ever lets a Windows host through, the client would still hide Launch with nothing in the server's answer to correct it. Using the preflight refusal as the only trigger would keep one source, at the cost of one AWS-free request.

[DESIGN-REVIEWED] 14cff18

Description read

[DESCRIPTION-READ] 25eccc3fde5c09ef596e5e7b009e658581ff692fe2cb786df3c4bfe700b64565

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

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

UX-Verdict: PASS

Nothing blocks: the screenshots show both states, and the blind reader understood the guide link (the main next step) and would click it.

Notes

  • When the preflight is refused, the reason sentence shows as a red ErrorNotice under an info-icon heading. The blind reader asked "is this a heads-up or a failure?" because the same expected platform limit reads calm in one state and alarming in the other. Show the windows_body text as plain text in both states, and move the report and Ask the agent hand-off below it in a neutral style.
  • In windows_cli, kirocrew cloud launch sits inside the sentence as plain prose. The reader said they had "no idea how to follow it." Render the command as a copyable code chip, the way other command steps in Settings do.
  • windows_wsl says "open the dashboard it starts," which the reader took to be a different dashboard from this one. Use "open its dashboard in this browser."

[UX-REVIEWED] 14cff18

Description read

[DESCRIPTION-READ] 6626d415d8a78241f87470ad2777107c690a8b39ce59517a9337899df5b1507e

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 14cff18

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

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

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 14cff18

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 14cff1809f8d7788a639df67400d555a29e5f1d9 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 10, 2026
@JLargent42

Copy link
Copy Markdown
Contributor Author

Review dispositions for 2c158a8:

  • GPT F1 (errors-use-error-notice), fixed. When the posix_host_required refusal is how the tab learns the gateway is Windows, the notice's sentence now renders through ErrorNotice, with reportForError(preflightQuery.error) and the agent hand-off. A known-Windows gateway sends no preflight and keeps the plain informational card. Both cases are pinned in RemoteCrewPanelWindowsGateway.test.tsx.
  • GPT F2 (CLI not on PATH after a desktop install), fixed. The CLI sentence (all 12 catalogs) now says the desktop app does not add kirocrew to PATH, and the guide gives the bundled shim's full-path command.
  • Opus note (AWS CLI MSI needs admin), fixed. The guide no longer says "with no admin rights". It says installing the AWS CLI usually needs admin rights and the launch itself needs none.
  • UX notes on the "not checked" and "Nothing changes" wording, fixed. The text now reads "Your AWS profile wasn't used, so it isn't the problem." and "Your Windows install keeps working as it is."
  • UX note (show the command as code with a copy button), not taken. The command sits inside a translated sentence. Splitting it out needs a component-interpolation path this panel doesn't use for any other string, and the guide already shows the command as a copyable code block. This is cosmetic and doesn't affect whether the workaround can be used.
  • Design / First Principles note (gate on posix_only instead of the built-in lane), not taken. The built-in form's preflight route is POSIX-gated on its own (handlers_cloud.py api_cloud_preflight calls _guard(request, "preflight") with the default posix_only=True), whatever the lane's flag says. Gating on posix_only would draw the AWS checklist on Windows for any built-in-kind lane flagged posix_only: false, and its preflight would still be refused. A lane drawn by an edition renderer owns its own form, which is listed under Not a goal.

@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 10, 2026
When the preflight refusal, not the platform signal, is how the Set-up
tab learns the gateway is Windows, the notice's sentence now renders
through ErrorNotice with the rejection's report and agent hand-off.

The desktop installer adds nothing to PATH, so the CLI sentence and the
Windows guide now point desktop installs at the bundled shim's full
path, and the guide says installing the AWS CLI usually needs admin
rights. The notice now says the AWS profile is not the problem and that
the Windows install keeps working. The fr, ru, hi and bn strings use the
informal register their style guides require. The feature map lists the
notice and the settings coverage gate waives it, as it holds no setting.
@JLargent42
JLargent42 force-pushed the fix/32150-windows-cloud-setup branch from 2c158a8 to 14cff18 Compare November 10, 2026 06:33
@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 10, 2026
@Zedmor

Zedmor commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Code change approver recommendation: Approve

Automated, not a person, and not a review: a maintainer still decides.

decider-v3c@217fe607 · p_defect 0.1 · router R0 (approves only when p_defect <= 0.12, on changes of at most 400 changed lines) · head 14cff1809f · 334 changed lines

Why: the decider approves with p_defect 0.1 <= 0.12 and every rail passes.

I'm approving this. It is a small frontend-only change. On a Windows gateway, the built-in EC2 lane's AWS checklist and launch form are replaced by one notice card. The server-side posix_host_required gate in handlers_cloud.py is not touched.

How the client decides it's Windows. The server refuses when sys.platform.startswith('win'). The prerequisite status turns win32 into the label "Windows", and classifyPlatform maps that label to 'windows', so the client and server agree. If the platform hasn't been cached yet, a preflight refused with posix_host_required triggers the same notice. A non-owner sees the platform as the sentinel 'gateway', which reads as 'other', so their preflight still runs and the refusal brings up the notice.

Scope. The notice only applies to the built-in lane: BUILTIN_REMOTE_PROVISIONER_KINDS is just aws_ec2, which is posix_only. Lanes an edition draws with its own renderer keep their own form, as the description says. Every place the preflight error and credentials text are drawn sits inside the branch the notice now replaces. The launch progress card, the launch-status error and the provisioner-list error all sit outside

If this recommendation is wrong, reply here; the replies are how the approver is evaluated.

@JLargent42

Copy link
Copy Markdown
Contributor Author

Dispositions for the non-blocking notes on 14cff18:

  • First Principles (two triggers: the platform label and the server refusal), kept. The issue asks for the Windows notice to appear before any AWS check runs, so a known-Windows gateway must not send the preflight. That rules out the refusal as the only trigger. The refusal stays as the fallback for an uncached platform signal. If the server ever allows a Windows launch, this client gate is the one line to drop, and RemoteCrewPanelWindowsGateway.test.tsx pins both triggers.
  • UX (red ErrorNotice under an info heading), kept as is. The previous GPT round upheld a blocking errors-use-error-notice finding for exactly this state: a rejected request must render through ErrorNotice with its report and hand-off. The calm, plain-text version is what a known-Windows gateway shows, because nothing was rejected there.
  • UX (command as a copyable chip), deferred. Same as the earlier disposition: the command is part of a translated sentence, and the linked guide shows it as a copyable code block.
  • UX ("open the dashboard it starts" read as a different dashboard), deferred. It is a cosmetic change to one sentence in 12 catalogs, and the guide's step 5 already says to open that URL in the Windows browser. It isn't worth another full CI round on its own. I can fold it in if anything else needs a push.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 10, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved at 14cff18.

On a Windows gateway, the Set-up tab now shows one RemoteCrewWindowsNotice in place of the built-in lane's AWS checklist and launch form, instead of a checklist that implied the AWS profile was wrong.

  • When it shows: when useGatewayPlatform() reads windows, or when the preflight answers 400 posix_host_required (in case the platform signal isn't loaded yet or the gateway is older).
  • No AWS check: a known-Windows gateway no longer sends the preflight at all (enabled gains !windowsGateway). Other platforms and lanes an edition draws itself are unchanged.
  • What it says: the two ways forward, kirocrew cloud launch in PowerShell (by its full path from a desktop install) or a gateway inside WSL, linking the new section in windows-install.md. When the refusal is how the tab learned it, the sentence goes through ErrorNotice with the rejection's report.
  • Strings: all 13 locales are added.

A frontend-only change, no new refusal and no regex. CI: all 97 checks are green on this head.

@bolichen97
bolichen97 enabled auto-merge (squash) November 10, 2026 08:06
@bolichen97
bolichen97 merged commit 715d4aa into main Nov 10, 2026
99 checks passed
@bolichen97
bolichen97 deleted the fix/32150-windows-cloud-setup branch November 10, 2026 08:07
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 10, 2026
bolichen97 pushed a commit that referenced this pull request Nov 10, 2026
* fix(settings): explain the windows cloud launcher block once

On a Windows gateway the dashboard's cloud launcher answers 400
posix_host_required before any AWS call, but the Set-up tab still drew
the AWS checklist: the raw POSIX error, a credentials row saying they
were not checked, Ask the agent, and a disabled Launch, with no guide.

The tab now shows one notice instead. It says the launcher needs a
Linux or macOS gateway and the profile was not checked, and names the
two ways forward: the CLI launch wizard in PowerShell, or a gateway
inside WSL, which needs admin rights and a restart. A gateway known to
be Windows skips the preflight entirely. The Windows guide gains the
WSL steps the notice links to.

Fixes #32150

* fix(settings): route the refused preflight through the error notice

When the preflight refusal, not the platform signal, is how the Set-up
tab learns the gateway is Windows, the notice's sentence now renders
through ErrorNotice with the rejection's report and agent hand-off.

The desktop installer adds nothing to PATH, so the CLI sentence and the
Windows guide now point desktop installs at the bundled shim's full
path, and the guide says installing the AWS CLI usually needs admin
rights. The notice now says the AWS profile is not the problem and that
the Windows install keeps working. The fr, ru, hi and bn strings use the
informal register their style guides require. The feature map lists the
notice and the settings coverage gate waives it, as it holds no setting.

(cherry picked from commit 715d4aa)
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.

Cloud crew on Windows: setup blocks with 'requires a POSIX host; use WSL' plus a wrong credentials error, and no guide

3 participants