Skip to content

fix(cloud): lead the AWS pre-flight helper row with the edit, link the guide - #21568

Merged
bolichen97 merged 1 commit into
mainfrom
fix/aws-preflight-wording-20239
Oct 17, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/aws-preflight-wording-20239

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: the Remote Crew set-up pre-flight tells a user exactly which file and setting to edit when their credential helper is not found, and points them at the guide when a refused Session Manager plugin has no known fix command.

Two UX Review findings deferred from #19960:

  1. The credentials row's "credential helper not found" message explains PATH first, hedges ("It is usually the program your profile's credential_process runs."), and says "your AWS config" without naming the file or how to find the helper's full path.
  2. When the Session Manager plugin is found but refused and no fix command is known for that reason, the row gives only a generic next step, with no pointer to the guide's troubleshooting entry.

Why it matters

These rows are the first thing a user sees when Remote Crew set-up fails. A vague sentence sends them hunting for which file to edit, or to "Ask the agent" for something the guide already answers.

Not a goal

  • Changing what the pre-flight checks or when it refuses a plugin.
  • Changing the gateway's own English message (cloud/iam.py), which still shows as the row's monospace detail line.
  • Changing the row for a refusal that has a fix command (it already links AWS's install page).

What changed (motivation → approach → change)

  • credentials_helper_missing (all 12 catalogs): leads with the edit, "Give <name> its full path in the credential_process line of your AWS config file (usually ~/.aws/config), then re-check.", then why ("The AWS CLI could not find it on the gateway's PATH."), then how and where ("To get the full path, run which <name> in a terminal on the computer that runs Kiro Crew, from the account that runs it.": which only sees the gateway's PATH there). The hedge is gone. The file path and the command are typed by the user, so they are code constants interpolated as {{file}} / {{command}} (remoteCrewPluginRefusal.ts, credentialHelperMissingSentence), never catalog text.
  • New plugin_refused_guide link label (all 12 catalogs): when a refused plugin has no fix command, the row's step now also links docs/guides/remote-crew-on-ec2.md#set-up-pre-flight-credential-helper-not-found-or-plugin-refused, the guide entry that covers both rows.
  • en.context.json updated for both keys; en-XA.json regenerated with npm run i18n:pseudo.

Backwards compatibility

Compatible: copy and one added link; no API, setting or behavior change.

Removes nothing: the only removed text is the hedge sentence in one message.

Tests

  • RemoteCrewPanelPluginRefusal.test.tsx: the no-command refusal row shows the guide link with the exact anchor, outside the alert; a refusal with a command shows no guide link; credentialHelperMissingSentence leads with the edit, names ~/.aws/config and which <name>, says to run it on the gateway's computer from its account, and has no hedge.
  • RemoteCrewPanel.test.tsx: the panel-level helper-missing test matches the new lead sentence ("Give sso-cred-helper its full path …") and still pins the CLI's own error on its own monospace line.
  • scripts/capture-aws-preflight-honest.mjs asserts the new copy and the guide link before writing each PNG.
  • On a fresh npm ci: vitest run src/i18n src/test/RemoteCrewPanel.test.tsx src/test/RemoteCrewPanelPluginRefusal.test.tsx 1105 passed; tsc -p tsconfig.app.json, eslint on the touched files, i18n:check, i18n:render and the related frontend set clean.

Manual verification

Rendered the real built SPA with the capture harness above (fixture API), dark and light.

Screenshots / video

Credentials row, helper not found (light):

credential helper missing

Refused plugin with no fix command, now linking the guide (dark):

plugin refused no fix

Related Issues

Closes #20239

Pattern harvest

Not generalizable: two copy findings on one row, deferred from #19960's UX review.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable) — the guide already has the entry this links
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 17, 2026 08:57
@bolichen97
bolichen97 requested a review from mbriones98 October 17, 2026 08:57
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 17, 2026
@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 68fd5a23761ed4f3168436e5076247380147d39c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check that the hardcoded blob/main anchor #set-up-pre-flight-credential-helper-not-found-or-plugin-refused has a test that fails if the guide heading is renamed.

[DESIGN-REVIEWED] 68fd5a2

Description read

[DESCRIPTION-READ] 5a49fee2ae96e3d1ba4134702ad8acab57b3a8002c282b5f4bc90fff484e6519

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 68fd5a23761ed4f3168436e5076247380147d39c — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

One thing to check: which <name> is a POSIX command. If a gateway on Windows can reach this row, the new sentence tells that user to run a command their machine doesn't have.

What this change ships

Inventory (5 items) — 5 justified

Intent: a user whose Remote Crew set-up pre-flight fails can see which file to edit, or which guide entry to read, without asking anyone. This is a FIX (copy), and it closes #20239.

  1. The helper-not-found sentence now starts with the edit to make and names ~/.aws/config — justified
  2. The hedge sentence "It is usually the program…" is gone — justified
  3. The sentence says to run which <name> on the gateway's computer, from the gateway's account, to get the full path — justified
  4. A refused plugin with no known fix command now links the guide's pre-flight troubleshooting entry (the anchor exists at docs/guides/remote-crew-on-ec2.md:169) — justified
  5. New plugin_refused_guide label in all 12 catalogs, plus updated context notes and pseudo-locale — justified

[FIRST-PRINCIPLES-REVIEWED] 68fd5a2

Description read

[DESCRIPTION-READ] 2d08d5bc545e9e00f1dfe1166f03a584d1977e672f551659ebfc8363dd1f4eb5

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

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — 🟡 CONCERNS

UX-level review of 68fd5a23761ed4f3168436e5076247380147d39c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

The command and file path users must type, which sso-cred-helper and ~/.aws/config, render as plain red prose, with nothing marking where the command ends.

Watch

  • The typed command blends into the sentence. The code passes {{command}} and {{file}} in as plain text, so shot-01 shows "run which sso-cred-helper in a terminal" in the same red body font as the rest. The blind reader saw "run which sso-cred-helper in a terminal" as a phrase it didn't understand, not as a command to copy. Anyone with a missing helper hits this every time, and the exact thing to type is hard to pick out. Fix: show {{command}} and {{file}} as inline monospace code spans, and add a copy button to the command.
  • The two rows put the fix in different places. In shot-01 the fix is inside the red failure text. In shot-02 it is a separate grey step line with a guide link under it. The reader said they "wasn't sure where to look for the action". This is moderate friction for anyone who sees both rows. Fix: put the helper row's edit in the same step line, and add the same guide link there, since the PR says the guide entry covers both rows.

[UX-REVIEWED] 68fd5a2

Description read

[DESCRIPTION-READ] 78078e078c7bc456ba1ac86b49bc6a062c75796c0c4d3fe7358d1bcd768b317a

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 68fd5a2

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 68fd5a23761ed4f3168436e5076247380147d39c: <one-sentence reason>

@bolichen97
bolichen97 force-pushed the fix/aws-preflight-wording-20239 branch from b3ca7da to 1e76a69 Compare October 17, 2026 09:00
@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 68fd5a2

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 68fd5a23761ed4f3168436e5076247380147d39c: <one-sentence reason>

@bolichen97
bolichen97 enabled auto-merge (squash) October 17, 2026 09:05
@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 Oct 17, 2026
@bolichen97

bolichen97 commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (not a defect)

  • span=58520fac6c6e

The pre-flight route never answers on a Windows gateway: api_cloud_preflight calls _guard(request, "preflight") (src/kiro_crew/dashboard/handlers_cloud.py:397), whose default is posix_only=True.
_guard returns 400 posix_host_required when sys.platform.startswith("win") (handlers_cloud.py:118-127), so this row only renders for a Linux or macOS gateway.
On both, which exists and ~/.aws/config is the AWS CLI's default config path; the sentence says "usually" for an AWS_CONFIG_FILE override.
The plugin install command differs between Linux and macOS, which is why it comes from the gateway; these two values do not differ on any platform this row can appear on.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (the PASS punchline's check, answered)

A Windows gateway cannot reach this row: /api/cloud/preflight is POSIX-gated by _guard(..., posix_only=True) in src/kiro_crew/dashboard/handlers_cloud.py:397, which answers 400 posix_host_required on Windows.
So which <name> is only ever shown for a Linux or macOS gateway, where it exists.

@bolichen97

bolichen97 commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (disproportionate to the frozen goal)

  • span=bda81d2c79f3

The goal is that the row names the file and setting to edit and how to find the full path; the sentence now names credential_process, ~/.aws/config and which <name> verbatim.
Rendering them as inline code means changing the row's failure prop and ErrorNotice from a string to rich nodes, plus the agent hand-off report that reads that string: a new rendering contract for every check row, beyond this copy fix.
The values stay exact, copyable text in the sentence; code styling across check rows is a separate change.

@bolichen97

bolichen97 commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (out of the frozen goal)

  • span=ee0eac3d069f

The plugin row's layout (diagnosis in the red line, the next step in the grey line under it) predates this PR; the PR only adds a guide link to that existing step.
The frozen "Not a goal" excludes reshaping the plugin row; the credentials row leads with the fix because its UX finding asked for exactly that.

@bolichen97

bolichen97 commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (suggestion kept as is)

  • span=702ab5b5e3a8

The label says what the link opens ("the troubleshooting steps") and names the guide by its real title, so a reader who follows it lands on a page whose heading matches the link.
The anchored entry covers both pre-flight problems (helper not found and plugin refused), so a problem-specific label would be narrower than the page it opens.

@bolichen97
bolichen97 force-pushed the fix/aws-preflight-wording-20239 branch 2 times, most recently from 435ce77 to 91e16e2 Compare October 17, 2026 10:42
…e guide

The credential-helper-missing row now names the AWS config file and the credential_process setting first, drops the hedge, and says how to find the full path (which <name>). A refused Session Manager plugin with no known fix command links the Remote Crew on EC2 guide's pre-flight entry. All 12 catalogs updated. Closes #20239.
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (the PASS punchline's Windows check, answered)

A Windows gateway never renders this row: api_cloud_preflight calls _guard(request, "preflight") (src/kiro_crew/dashboard/handlers_cloud.py:397) whose default posix_only=True answers 400 posix_host_required on Windows (handlers_cloud.py:118-127).
On Linux and macOS, which exists and ~/.aws/config is the AWS CLI default; the sentence says "usually" for an AWS_CONFIG_FILE override.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: fixed in 68fd5a2

The sentence now says where and as whom to run it: "To get the full path, run which <name> in a terminal on the computer that runs {{productName}}, from the account that runs it.", in all 12 catalogs.
RemoteCrewPanelPluginRefusal.test.tsx and capture-aws-preflight-honest.mjs pin the new clause.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (disproportionate to the frozen goal)

  • span=21baf3433a10

The goal is that the row names the file, the setting and the command; the sentence names credential_process, ~/.aws/config and which <name> verbatim.
Code styling inside the row means turning the check row's failure prop and ErrorNotice message from a string into rich nodes, plus the agent hand-off report that reads that string: a new rendering contract for every check row, beyond this copy fix.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (suggestion kept as is)

  • span=4c256c440f8d

The reader read the link correctly. Its label names the page by its real title, so the heading the reader lands on matches the link.
The anchored entry covers both pre-flight problems, so a problem-specific label would be narrower than the page it opens; the link's place under the step is the existing step layout, outside the frozen goal.

@bolichen97
bolichen97 force-pushed the fix/aws-preflight-wording-20239 branch from 91e16e2 to 68fd5a2 Compare October 17, 2026 12:01
@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 Oct 17, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (the PASS punchline's anchor check, answered: disproportionate)

The test pins the exact href (RemoteCrewPanelPluginRefusal.test.tsx), the same way the repo's other guide links are pinned (McpTab.notProbedReason.test.tsx:92, secrets-env.md#route-the-server-through-the-gateway); none of them read the guide's headings.
A cross-file docs-heading check for every SPA guide link is a repo-wide mechanism, not part of this copy fix.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (the PASS punchline's Windows check, answered: not a defect)

A Windows gateway never renders this row: api_cloud_preflight calls _guard(request, "preflight") (src/kiro_crew/dashboard/handlers_cloud.py:397), whose default posix_only=True answers 400 posix_host_required on Windows (handlers_cloud.py:118-127).
On Linux and macOS which exists, so the sentence never names a missing command.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (disproportionate to the frozen goal; same class as spans bda81d2c79f3 and 21baf3433a10)

  • span=e1ce783ac10b

The goal is that the row names the file, the setting and the command, and where to run it; the sentence names credential_process, ~/.aws/config and which <name> verbatim.
Code styling inside the row means turning the check row's failure prop and ErrorNotice message from a string into rich nodes, plus the agent hand-off report that reads that string: a new rendering contract for every check row, beyond this copy fix.

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Disposition: rebutted (out of the frozen goal; same class as span ee0eac3d069f)

  • span=42879321b14f

The plugin row's layout (diagnosis in red, next step in the grey line under it) predates this PR; the PR only adds a guide link to that existing step, and "Not a goal" excludes reshaping the plugin row.

@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 Oct 17, 2026
@bolichen97
bolichen97 merged commit 0b2457c into main Oct 17, 2026
104 checks passed
@bolichen97
bolichen97 deleted the fix/aws-preflight-wording-20239 branch October 17, 2026 16:52
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 17, 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.

Remote Crew AWS pre-flight: name the AWS config file and point to the guide in two messages

2 participants