Skip to content

fix: say how to update a pip install the gateway cannot auto-update - #38666

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/36220-update-hint
Nov 19, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/36220-update-hint

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A pip or pipx install of Kiro Crew that the gateway cannot auto-update says, in plain words, to run kirocrew update, and a host whose security policy pins the update source is told about the pin instead.

On a plain pip install into a user-made venv, with auto-update on and a newer release out, the gateway logs at every update check:

Auto-update is on, but this install (kirocrew) cannot apply it unattended (only the managed venv updates itself unattended) — notifying instead

It names no step, and "managed venv" is an internal term a pip user cannot act on.

Why it matters

Everyone who installs with the install guide's pip forms (and pipx, and Windows) sees this line at every start and has no way to learn from it how to update. kirocrew update already prints the right in-place command for that install shape, but nothing points at it.

Not a goal

  • Making a pip or pipx install update itself unattended.
  • Changing what kirocrew update prints or does.
  • Rewording the source-pin refusal of kirocrew update.

What changed (motivation → approach → change)

The gateway already knew it could not update a pip or pipx install by itself, but it stopped at saying so. kirocrew update is the step that fits each of those installs: on a plain pip environment it prints the in-place upgrade command and the restart, and on pipx it re-runs the installer.

So the gateway's notify line (slack/gateway_runtime/update_schedule.py) now ends with ; to update it, run `kirocrew update` from your own terminal on a wheel install. A host whose security policy pins the update source gets no step, because kirocrew update refuses there too. For that to hold on every wheel install, the wheel route in platform/update_capability.py checks the pin first, the order the update's own preflight uses, so a pinned pip, pipx or Windows install reports the pin instead of its install shape. The two shape reasons the line quotes say what they mean without "managed venv": only the install script's own environment updates itself, not a pip or pipx install, and on Windows the install script's self-updating environment is macOS and Linux only. The cli spec's effect paragraph says the same.

Backwards compatibility

Compatible: nothing that works today stops working. The route (None) is the same for every input; what moves is which reason wins when a pinned wheel install also fails another check, and the wording of the two install-shape reasons, which the notify line and the version-compliance lines quote.

Reader: src/kiro_crew/slack/gateway_runtime/update_schedule.py:_check_for_updates_legacy -- release -- below the policy's minimum version, a pinned pip, pipx or Windows install, and a pinned managed venv with no trusted openssl or an unsafe CDN base, takes the existing effect.blocked branch, as any other pinned managed venv or git checkout already does: it logs "not applying" and lights no badge, where before it lit one with a kirocrew update or pip install hint that the pin refuses

Tests

  • test/test_update_check_install_aware_auto_apply.py::TestAutoUpdateEffect::test_a_wheel_install_that_only_notifies_says_how_to_update (pip-or-pipx, windows, pip-pinned-away): the step appears for an unpinned wheel install, not for a pinned one, and "managed venv" never appears. All three fail on the base.

Determinism: the new test ran five times with -n0 (3 passed each run) and once with its three ids in reverse order (3 passed).

Proof: PROVEN test/test_update_check_install_aware_auto_apply.py::TestAutoUpdateEffect::test_a_wheel_install_that_only_notifies_says_how_to_update[pip-or-pipx], test/test_update_check_install_aware_auto_apply.py::TestAutoUpdateEffect::test_a_wheel_install_that_only_notifies_says_how_to_update[windows], test/test_update_check_install_aware_auto_apply.py::TestAutoUpdateEffect::test_a_wheel_install_that_only_notifies_says_how_to_update[pip-pinned-away] (head 3451a4ef622a)

Manual verification

On Linux, with a wheel built from this patch and installed into a fresh python3.12 -m venv, and the installed __version__ lowered to 0.12.1 (the stable feed reports 0.12.2):

  • Plain pip venv: the gateway logs … cannot apply it unattended (only the install script's own environment updates itself, not a pip or pipx install) — notifying instead; to update it, run kirocrew update from your own terminal. kirocrew update then prints the plain-pip message, the in-place pinned-wheel pip install and kirocrew restart, and exits 1 with the version unchanged.
  • Pinned host (security_policy.json with updates.source: "https://git.corp.example/platform/*"; confirmed loaded): … cannot apply it unattended (the update source is not the one the security policy pins) — notifying instead, with no step. kirocrew update refuses with Update blocked by security policy.
  • auto_update false: no Auto-update is on line.

The base was also reproduced on the released 0.12.1 wheel, which prints the old line with no step.

Real-machine verification

Machine: EC2 m7i.2xlarge, Ubuntu 24.04 x86_64, 8 vCPU / 32 GiB
Before (main c22557c): kirocrew gateway --port <free port> --no-open --no-tunnel --no-crons from the released 0.12.1 wheel in a fresh venv, auto-update on -> Auto-update is on, but this install (kirocrew) cannot apply it unattended (only the managed venv updates itself unattended) — notifying instead; the new test on that base fails 3 of 3.
After (head f504938; the gateway runs used 3451a4ef622a, the same patch before clean rebases): the same command -> the line ends with ; to update it, run `kirocrew update` from your own terminal, and a pinned host gets the pin reason with no step (both quoted above). On head f504938's tree, on another machine of the same type: the new test 3 passed in each of 3 runs; 35 related test files 1725 passed, 1 failed, and that one (a host-git fixture self-check in test/test_host_git_repo_exec_neutralization.py) fails on main 5e49873 too.
Cleanup: the gateway machine is terminated (describe-instances returns nothing for it); it had no key pair and no inbound rules.

Related Issues

Fixes #36220

Sibling sweep

Swept: git grep -n "managed venv" -- src/kiro_crew/platform/update_capability.py src/kiro_crew/slack/gateway_runtime/update_schedule.py
Sibling: src/kiro_crew/slack/gateway_runtime/update_schedule.py -- changed here
Sibling: src/kiro_crew/platform/update_capability.py -- changed here

Pattern harvest

Not generalizable: a single log line that lacked a remediation step, and one refusal order that did not match the preflight it mirrors.

Checklist

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • 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

Contributions are accepted under the project's Apache-2.0 license.

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

Every item traces to #36220 or the existing spec rule that no badge points at a kirocrew update the pin refuses. The pin reorder is what makes effect.blocked true on pinned wheel installs.

What this change ships

Inventory (6 items) — 6 justified

Intent: a pip, pipx or Windows install that cannot update itself tells its user to run kirocrew update, and a pinned host is told about the pin instead. FIX.

  1. The gateway's notify line on an unpinned wheel install now ends with "run kirocrew update from your own terminal" — justified
  2. The pip/pipx reason now says "the install script's own environment" instead of "managed venv" — justified
  3. The Windows reason now says "macOS and Linux only" instead of "a POSIX install" — justified
  4. A pinned pip, pipx or Windows install now reports the pin reason instead of its install-shape reason — justified
  5. A pinned wheel install below the policy's minimum version no longer lights an update badge (declared under Reader) — justified
  6. The cli spec's effect paragraph matches the new order and the new step — justified

[FIRST-PRINCIPLES-REVIEWED] f504938

Description read

[DESCRIPTION-READ] bf3785ce0766a617648cf36dcd2f676826d478cb227ab7105e502446de874195

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns: the pin check now comes first, in the same order as the update's own preflight, and the notify line names the step that already exists for that install shape.

[DESIGN-REVIEWED] f504938

Description read

[DESCRIPTION-READ] f2bb53e623901ef6ae70f272e4ba6f38c094870ea80443765b7133397c352da3

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] f504938

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

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

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f504938

False positive or not applicable? A repository writer can comment:
/ai-review override gpt f50493834611e886fc17f7382fcf0e62ef5490a4 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 17, 2026
On a plain pip or pipx install the gateway logs at every update check
that auto-update cannot apply, but not what to do, and its reason reads
"only the managed venv updates itself unattended". The line now ends by
pointing at `kirocrew update`, which prints the in-place upgrade and the
restart for a pip environment and re-runs the installer for pipx.

A host whose security policy pins the update source gets no step, since
that command refuses there too. The wheel route now checks the pin
first, as the update's own preflight does, so a pinned pip, pipx or
Windows install reports the pin rather than its install shape. The two
install-shape reasons say what they mean without "managed venv".
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/cli.md, the gateway's gateway.py and gateway_runtime/update_schedule.py since this head ran CI (c22557c -> 5e49873); CI re-running.

Backend Tests (3.12, 8) failed only on test/test_app_manager_installed_record.py::TestListingReusesTheWalk::test_an_unchanged_folder_is_not_walked_again (assert 2 == 1), a test that was flaky on main (#38886) and is fixed there by #38980 and #39010; this PR does not touch it. Coverage Gate failed because that shard failed, and SAST (Semgrep) stopped on a semgrep-core internal error with no finding. The rebase was clean and leaves the patch unchanged. On a Linux test machine against this exact tree: 35 related test files passed twice apart from one host-git fixture check that fails on main too, that flaky test passed 3 of 3, and mypy, flake8, isort, black, docs-lint, the flake-pattern ratchet and semgrep passed.

[operator: bolichen97]

@bolichen97
bolichen97 force-pushed the fix/36220-update-hint branch from 72deaaf to f504938 Compare November 19, 2026 11:29
@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 19, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates an 8% chance that this change introduces a defect, within the 12% limit for approving on its own, but it is held at tier pending: being reviewed.

The wheel route now checks the policy source pin first, the same order as wheel_apply.preflight_bases, which kirocrew update's wheel path runs before any shape logic. So a pinned pip, pipx or Windows install correctly reports the pin and gets no step. The route value is unchanged for every input; only the reason and effect.blocked change. That moves the below-floor case for pinned wheel installs onto the existing "not applying" branch, which no longer lights a badge for a command the pin refuses. The new notify-line step is gated on managed_by == kirocrew and not blocked. The MANAGED_BY_KIROCREW name resolves through gateway.py's globals. No existing test checks the old reason strings. The new parametrized test fails on the base branch and would catch a revert of the reorder (the pip-pinned-away case). CI is green.

Tier: pending: being reviewed.

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

@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.

I reviewed head f504938. The wheel route now checks the policy source pin first, in the same order as the update preflight and the kirocrew update wheel path, so a pinned pip, pipx or Windows install reports the pin and is not told to run a command the pin refuses. The new notify step only appears for an unpinned wheel install. MANAGED_BY_KIROCREW is wired through both the gateway import and the runtime module's manifest. The new parametrized test would fail on the base and passes here, along with the rest of the related update tests, and every CI check on this head is green, so nothing blocks.

@KiroCrewCaptain
KiroCrewCaptain merged commit 7f4b10e into main Nov 19, 2026
99 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/36220-update-hint branch November 19, 2026 13:03
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 19, 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.

Gateway log says auto-update can't apply to a pip/venv install but not how to update it

2 participants