Skip to content

fix(electron): backport composed-edition gateway reuse to release/0.8.0 - #15580

Merged
bolichen97 merged 1 commit into
release/0.8.0from
backport/0.8.0-electron-composed-gateway
Sep 30, 2026
Merged

bolichen97 merged 1 commit into
release/0.8.0from
backport/0.8.0-electron-composed-gateway

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On a 0.8.0.x build, the desktop app reuses a running gateway started by a composed edition instead of refusing to start.

This backports #15355 to release/0.8.0; it is already merged on main (c50c246). A composed edition boots the gateway from its companion's own top-level module (python -m kirocrew_<edition> gateway). On 0.8.0, the desktop launcher's port-owner matcher, isKirocrewCommand in website/electron/gateway-stop.js, accepts a Python process only when its -m operand is exactly kiro_crew. The edition's own gateway then classifies as foreign, and the app refuses to start on a port its own edition is serving ("port in use"). Root cause and design are in #15355.

Why it matters

0.8.0.x is on the stable channel. Every desktop user of a composed edition whose gateway is already up (a service unit, a launcher, a prior app run) is blocked at launch, because the holder is in fact their own gateway.

Not a goal

What changed (motivation → approach → change)

One commit, git cherry-pick -x c50c2465c0 (authorship kept), in the #11339 / #11645 / #15314 backport shape. It applied without conflict, and every line matches the source.

  • website/electron/gateway-stop.js: a -m operand counts as ours when it matches KIROCREW_MODULE_RE (kiro_crew or a composed edition's kirocrew_<edition> root) AND the first positional after it is a server subcommand (gateway, dashboard, start). Without that second check, the widened module name alone could authorize a SIGKILL of any process that merely imports a kirocrew_* module on our port.
  • test/test_cli.py: TestDesktopGatewayIdentityParity pins both Electron constants to their Python twins in port_resolution (the server subcommand set and the module roots).
  • cli.md and platform-context.md specs document it.

Dependencies: none. gateway-stop.js and gateway-stop.test.js are byte-identical on this branch and on c50c246^.

Backwards compatibility

Compatible for every gateway the app starts or reuses: python -m kiro_crew gateway|dashboard|start classifies as before, and a composed edition's own gateway is now ours too. The matcher is stricter in one case, on purpose: a python -m kiro_crew <non-server subcommand> process on the port is no longer treated as ours, so it is not a stop target. That is the same set kirocrew stop already gates on (as in #15355).

Tests

website/electron/test/gateway-stop.test.js and test/test_cli.py::TestDesktopGatewayIdentityParity (from #15355). Run on this branch:

  • node --test test/gateway-stop.test.js: 39 passed, 1 skipped.
  • pytest test/test_cli.py: 442 passed, 2 skipped.
  • With gateway-stop.js reverted to release/0.8.0: 2 Electron tests fail (classifyPortOwner: a composed edition's gateway classifies as ours, not foreign, isKirocrewCommand: a composed edition's -m kirocrew_<edition> gateway is ours), and 2 parity tests fail (test_server_subcommands_are_the_same_set, test_module_pattern_accepts_every_conventional_entry_point_root).

Backend CI (ci.yml) does not run on release-branch PRs, so these local runs are the backend evidence.

Manual verification

N/A beyond #15355: the code is byte-identical to main's fix, and the matcher is covered by unit tests on both runtimes.

Screenshots / video

Why no screenshot: no rendered change. The fix is the launcher's port-owner classification in the Electron main process; no page, layout or style changes.

Related Issues

Backport of #15355 to release/0.8.0.

Pattern harvest

Rule candidate: lint
Pattern: the same identity constant copied into a second runtime with no cross-runtime test pinning the copies equal. (Harvested in #15355.)

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

… it (#15355)

The desktop launcher decides who holds the gateway port from the
holder's command line. `isKirocrewCommand` accepted a Python process
only when its first `-m` operand was exactly `kiro_crew`. A composed
edition boots the gateway from its companion's own top-level module
(`-m kirocrew_<edition>`) so the composition root runs instead of the
core CLI, so every such gateway classified as `foreign`, and the
supervisor's reuse decision returned `foreign-holder` with no remote
crew to name. The app then refused to start on a port its own edition
was serving.

The Python side already solved this in
`port_resolution._gateway_module_roots()` by reading installed
`kirocrew.plugins` entry points. The Electron process has no view of
that Python environment, so it matches the naming convention the entry
points follow instead: `kiro_crew`, or an exact top-level
`kirocrew_<edition>` module. The core still learns no edition's name.
The match stays on the first execution selector only, and a dotted
submodule, a bare prefix, a hyphenated or mixed-case look-alike never
authorize a kill.

(cherry picked from commit c50c246)
@bolichen97
bolichen97 requested a review from a team as a code owner September 30, 2026 21:08
@bolichen97
bolichen97 requested review from cruisercohen and removed request for a team September 30, 2026 21:08
@bolichen97

Copy link
Copy Markdown
Contributor Author

Local test evidence on the release/0.8.0 tree (head 8a9fb23f4e)

Backend CI (ci.yml) does not run on release-branch PRs, so this is the backend evidence. Runs are from a worktree of this head, Python 3.12.13, on Linux; pytest's pythonpath = src resolves to the worktree.

$ cd website/electron && node --require ./test/_preload.cjs --test test/gateway-stop.test.js
# tests 40  # pass 39  # fail 0  # skipped 1
$ /workplace/bolichen/KiroCrew/.venv/bin/python -m pytest -q -n 8 --dist loadgroup --max-worker-restart=2 test/test_cli.py
442 passed, 2 skipped

Regression tests fail without the change (website/electron/gateway-stop.js -> release/0.8.0):

not ok 38 - classifyPortOwner: a composed edition's gateway classifies as ours, not foreign
not ok 40 - isKirocrewCommand: a composed edition's `-m kirocrew_<edition>` gateway is ours
FAILED test/test_cli.py::TestDesktopGatewayIdentityParity::test_server_subcommands_are_the_same_set
FAILED test/test_cli.py::TestDesktopGatewayIdentityParity::test_module_pattern_accepts_every_conventional_entry_point_root

Static gates on this head (run from the worktree, no flags): scripts/check_black_formatting.py passed (nothing in scope unformatted outside the baseline); scripts/check_subprocess_encoding.py rc=0; isort --check-only and flake8 on the changed .py files rc=0; mypy src/kiro_crew: Success: no issues found in 1860 source files. scripts/docs-lint.sh: All documentation checks passed.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 30, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] 8a9fb23

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the cherry-pick matches c50c246 exactly (git diff c50c2465c0 HEAD -- <files>), since release-branch PRs get no backend CI run.

[DESIGN-REVIEWED] 8a9fb23

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

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

Backend CI skips release-branch PRs, so the description's local pytest/node runs are the only backend evidence — spot-check them before merge.

What this change ships

Inventory (5 items) — 5 justified

Intent: FIX — backport #15355 so a 0.8.0 desktop app reuses a composed edition's running gateway instead of refusing "port in use".

  1. Desktop app now reuses a composed edition's -m kirocrew_<edition> gateway instead of refusing its port as foreign — justified
  2. A python -m kiro_crew <non-server subcommand> port holder no longer counts as ours, so it is never a stop target — justified
  3. New cross-runtime test pins the Electron identity constants to their Python twins — justified
  4. cli.md now documents the desktop matcher and the legacy dotted-spawn asymmetry — justified
  5. platform-context.md now records the kirocrew_<edition> companion naming requirement — justified

[FIRST-PRINCIPLES-REVIEWED] 8a9fb23

@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 8a9fb23f4e5c7cd696f0d25c7bc4145bb88d65e3 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 8a9fb23

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

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

Nothing blocks; one advisory: the new companion-naming paragraph misdescribes the Python matcher it documents.

FINDING — docs/system-specs/modules/platform-context.md:403 — the added paragraph states "neither can read the companion's entry points" and then, in the same sentence, that _gateway_module_roots() "derives the Python side's set from the installed kirocrew.plugins entry points" (it does — port_resolution.py calls plugin_entry_points()), and line 408's "Both also require a server subcommand ... as the first positional after the module" is false for the Python side, whose legacy dotted branch returns True on -m kiro_crew.gateway with no positional at all (if dotted_subcmd in _KIROCREW_SERVER_SUBCOMMANDS: return True), so the spec AGENTS.md makes authoritative for platform/ now states the opposite of the code governing which pid may be signalled → Fix: reword to "neither can learn a companion's module name from core — the Python side derives its set from the installed kirocrew.plugins entry points, the desktop launcher has no view of that environment and matches KIROCREW_MODULE_RE", and restrict the subcommand sentence to the -m <module> <subcmd> form, noting the Python side additionally accepts the dotted -m <module>.<subcmd>.

[OPUS-REVIEWED] 8a9fb23

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

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

@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 Sep 30, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=a7db3e63c428 platform-context.md:403 misdescribes the Python matcher — deferred

Deferred upstream. The paragraph is identical on main HEAD, and the finding is advisory. This PR is a faithful backport. Changing it only on release/0.8.0 would make the 0.8 line diverge from main and conflict with the next backport, so the fix belongs on main first and would reach this branch the same way.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Byte-identity and combined-tree checks (the review lanes asked for these; they have no shell)

  • sha256 of git diff HEAD^ HEAD +/- lines equals that of git diff c50c2465c0^ c50c2465c0 (aec9484d18a52ac7).

Combined check across all eight 0.8.0 backports (#15574 to #15581). They octopus-merge cleanly onto release/0.8.0 @ 556bf8e (merge e948b10401). release/0.8.0 has since gained #15544 (adaptive concurrency), which touches none of these PRs' files, so no rebase is needed. On that merged tree, scripts/local-gate.py --base origin/release/0.8.0:

  • Backend related set, 4 batches: 26519 + 39518 + 41054 + 16738 passed. 24 tests were deselected because they fail identically on untouched release/0.8.0 on this host: PDF-extractor child processes, installed-version metadata (0.8.0-rc.1), fresh-interpreter import probes, a systemd service probe, aws_control packaging producer CLI, and a peak-RSS reading. The failure sets were compared file by file on both trees.
  • Frontend related set, 3 batches: 9805 + 13140 + 4400 passed. Batch 1's 12 failures (SchedulePage.secrets, ArtifactDetailPage, ChatInput.approval) fail identically on untouched release. Batch 2/3's failures were Denied ID .../node_modules/@pierre/diffs/... from my symlinked node_modules. Rerun with a real node_modules in the fix(chat): backport recycle-notice answer visibility to release/0.8.0 #15578 worktree, the only frontend change in the set, all 8 affected files pass (205 tests).

@bolichen97
bolichen97 merged commit 938f88c into release/0.8.0 Sep 30, 2026
22 checks passed
@bolichen97
bolichen97 deleted the backport/0.8.0-electron-composed-gateway branch September 30, 2026 23:44
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 1, 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.

1 participant