Skip to content

fix(electron): reuse a composed edition's gateway instead of refusing it - #15355

Merged
buluoray merged 1 commit into
mainfrom
fix/desktop-reuse-edition-gateway
Sep 30, 2026
Merged

buluoray merged 1 commit into
mainfrom
fix/desktop-reuse-edition-gateway

Conversation

@bolichen97

@bolichen97 bolichen97 commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The desktop app reuses a running gateway started by a composed edition instead of refusing to start.

A composed edition boots the gateway from its companion's own top-level module (python -m kirocrew_<edition> gateway). The desktop launcher's port-owner matcher, isKirocrewCommand in website/electron/gateway-stop.js, accepted a Python process only when its -m operand was exactly kiro_crew. The edition's own gateway therefore classified as foreign, gateway-supervisor.js returned foreign-holder (a reuse decision on a foreign owner with no remote crew to name), and the app refused to start on a port its own edition was serving.

Why it matters

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 with a "something else holds the port" state and no way through, because the holder is in fact their own gateway.

Not a goal

  • Teaching the core any edition's module name. The match is the kirocrew_<edition> naming convention the kirocrew.plugins entry points follow; no edition is named.
  • Changing how the Python side classifies (port_resolution._gateway_module_roots() already reads installed entry points).
  • Changing the supervisor's reuse/evict decision tree or the token-source rules (token-sources.js deliberately never trusts this predicate for the secret).
  • Any change to the Windows path-binding rule: an absolute Windows executable must still be one the launch resolver selected.

What changed (motivation → approach → change)

Part Job
KIROCREW_MODULE_RE -m operand is kiro_crew or an exact top-level kirocrew_<edition>
KIROCREW_SERVER_SUBCOMMANDS the first positional after the module must be gateway, dashboard or start
platform-context.md the kirocrew_<edition> name is now a MUST for companions
TestDesktopGatewayIdentityParity pins the two JS constants to their Python twins

Symptom: a composed edition's gateway is reported as a foreign holder and the app refuses to start. Root cause: gateway-stop.js compared the -m operand to the literal kiro_crew. Change: the operand is matched against the companion naming convention instead. The Electron process cannot read the Python environment's installed entry points, so it mirrors the convention those entry points follow rather than the entry points themselves.

The module name alone does not authorize a kill. forceStopPort SIGKILLs whatever this predicate says is ours, so the match also requires a server subcommand in the fixed argparse slot after the module, the same set port_resolution._KIROCREW_SERVER_SUBCOMMANDS gates kirocrew stop on. A process that merely imports a kirocrew_* module on our port stays foreign. The match remains on the first execution selector only, exact top-level module only (no dotted submodule, no bare prefix, no hyphen, no mixed case).

The two identity constants now live in two runtimes, so test/test_cli.py::TestDesktopGatewayIdentityParity reads gateway-stop.js and pins the subcommand set equal to _KIROCREW_SERVER_SUBCOMMANDS and the module pattern to the root a conventional kirocrew.plugins entry point yields. Widening one side without the other fails a test instead of a user.

docs/system-specs/modules/platform-context.md makes the naming convention normative in the Companion packaging section, so a companion named outside it is a spec violation rather than a desktop-only surprise; docs/system-specs/modules/cli.md records the desktop-side rule beside the Python one, names the parity test, and states that the legacy dotted spawn -m kiro_crew.gateway is matched by stop only.

Backwards compatibility

Compatible: every gateway spawn the repo ships (gateway-supervisor.js, cli_server.py, the service units) carries -m kiro_crew gateway, which still matches. The one narrowing is -m kiro_crew followed by a non-server subcommand (run, setup), which never holds the gateway port, so no reuse or force-stop path that works today stops working.

Tests

test/test_cli.py::TestDesktopGatewayIdentityParity (2 tests): the JS KIROCREW_SERVER_SUBCOMMANDS set equals Python's _KIROCREW_SERVER_SUBCOMMANDS; the JS KIROCREW_MODULE_RE accepts kiro_crew and the root of a conventional companion entry point and rejects a dotted submodule, a bare or hyphenated name, and mixed case. Dropping start from the JS set fails the first test.

website/electron/test/gateway-stop.test.js:

  • classifyPortOwner: a composed edition's gateway classifies as ours, not foreign — the end-to-end verdict for a -m kirocrew_enterprise gateway listener is kirocrew.
  • isKirocrewCommand: a composed edition's -m kirocrew_<edition> gateway is ours — positive cases across POSIX, a path with a space, -s -P interpreter flags, and a trusted Windows python; negative cases for -m as a later argument, after -c, a dotted submodule, a bare kirocrew_, kirocrew, a hyphen, mixed case, kiro_crew_enterprise, a prefixed look-alike, a bare -m, a kirocrew_* module with no subcommand or a non-server subcommand (kirocrew_backup, kirocrew_backup serve), a server word in a later slot (run gateway, --port 5476 gateway), and kiro_crew alone or with run.

Mutation controls: loosening the pattern to kirocrew_.* fails the new test; dropping the subcommand check fails the new test. The unmutated code passes the whole Electron suite (npm run test:electron: 2021 tests, 0 failures).

Manual verification

N/A — unit coverage sufficient: the change is a pure predicate on a command-line string and the tests exercise the same classifyPortOwner path the supervisor calls.

Related Issues

no linked issue: observed directly on a composed-edition install where the desktop app reported a foreign port holder for the edition's own gateway; no tracker entry exists.

Pattern harvest

Rule candidate: lint
Pattern: "the same identity constant copied into a second runtime with no cross-runtime test pinning the copies equal" -- the added parity test is the instance; a generic check would grep for a named twin in each copy's comment and require a test naming both.

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

@bolichen97
bolichen97 requested a review from a team September 30, 2026 08:13
@bolichen97
bolichen97 requested a review from a team as a code owner September 30, 2026 08:13
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

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

UX-Verdict: PASS

Nothing to check.

[UX-REVIEWED] 06cbd2c

Description read

[DESCRIPTION-READ] 80651ba03793cafb89c8461473764fe4da7cad9d09fcfae83e617cf5324d5c91

That sha256 names everything this verdict read: the PR description, plus the 3 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 Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify on one real composed-edition install that reuse completes past the token handshake, since manual verification was skipped and CI only exercises the predicate.

[DESIGN-REVIEWED] 06cbd2c

Description read

[DESCRIPTION-READ] 52393cfe8ab406b7207250102330767e573033475ec21b66d22d13937a99e185

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

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 06cbd2cfa2042210e25c681c717e26b0f106e227 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 06cbd2c

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

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

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

Confirm the affected edition install spawns -m kirocrew_<edition> gateway; an edition console script (kirocrew-enterprise gateway) still reads foreign on both sides.

What this change ships

Inventory (5 items) — 5 justified

Intent: FIX — the desktop app reuses a composed edition's already-running gateway instead of refusing to start on its own port. Provenance is checkable: the added classifyPortOwner test fails on base, where only -m kiro_crew matched.

  1. The desktop app now recognizes a composed edition's -m kirocrew_<edition> <server-subcommand> gateway as its own, for reuse and force-stop — justified
  2. A python -m kiro_crew process without a server subcommand (run, setup, pod) no longer counts as the desktop's gateway — justified
  3. Companion packages must now name their top-level module kirocrew_<edition>; the spec makes the convention normative — justified
  4. cli.md records the desktop-side matcher and that the legacy dotted spawn stays foreign on the desktop — justified
  5. A cross-runtime test pins the desktop's two identity constants to their Python twins — justified

Notes from the counts run: item 2's narrowing matches the pre-existing Python gate (port_resolution._KIROCREW_SERVER_SUBCOMMANDS, required for -m kiro_crew at port_resolution.py:525), bounds the SIGKILL authority the widened module pattern would otherwise grant, and is declared under Backwards compatibility; no shipped port-holding spawn loses recognition (grepped -m kiro_crew spawns: supervisor, cli_server.py:1018, packaging wrappers — all carry a server subcommand; pod _run refuses the live port by design). Sibling matchers hardcoding kiro_crew in website/electron/: 0 besides gateway-stop.js (grep kiro_crew, non-test hits are comments and spawn args). The one shape unrecognized on both runtimes — an edition's own console script — is a pre-existing, equal gap on the Python side (_args_look_like_kirocrew matches basename kirocrew only), hence the punchline.

[FIRST-PRINCIPLES-REVIEWED] 06cbd2c

Description read

[DESCRIPTION-READ] e6ba4ff87a9d72c63a21e0c903c467c607cb0ba733b1834fd58ba6c734a7e203

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.

buluoray
buluoray previously approved these changes Sep 30, 2026

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

LGTM. I checked this at head 8d78cd1.

isKirocrewCommand now accepts the first -m selector when it matches ^(?:kiro_crew|kirocrew_[a-z0-9][a-z0-9_]*)$ (gateway-stop.js), which is the same convention port_resolution._gateway_module_roots() relies on for kirocrew.plugins companions. classifyPortOwner and forceStopPort both default to this predicate, so a composed edition's gateway now classifies kirocrew and the supervisor reuses it instead of returning foreign-holder. The Windows path binding and the "first execution selector only" rule are unchanged. token-sources.js does not trust this predicate for the local secret.

Verified:

  • A real edition launcher line, /…/farm/bin/python3.12 -P -m <edition companion> gateway, returns true.
  • node --test test/gateway-stop.test.js passes 39/39. Reverting the regex to ^kiro_crew$ fails exactly the two new tests (38, 40).
  • No other identity check in website/electron/ hardcodes kiro_crew. The remaining hits are the spawn argv and comments.

Non-blocking: the new tests pin the matcher, but no test covers the supervisor end to end (foreign-holder refused before, reused after). A gateway-supervisor.test.js case with a faked ps line would lock in the user-visible outcome.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 06cbd2c

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

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

@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 Sep 30, 2026
@bolichen97
bolichen97 force-pushed the fix/desktop-reuse-edition-gateway branch from 8d78cd1 to c96c069 Compare September 30, 2026 09:17
@bolichen97

Copy link
Copy Markdown
Contributor Author

mechanism: server-subcommand gate on the -m match, mirroring port_resolution._KIROCREW_SERVER_SUBCOMMANDS

  • fixed span=79441a497ccc — Convention match can SIGKILL unrelated Python services

Fixed in c96c069. The -m match now requires a server subcommand (gateway / dashboard / start) in the fixed argparse slot after the module, so python -m kirocrew_backup and python -m kirocrew_backup serve classify foreign and are never signalled.
The reuse and force-stop matchers stay one predicate on purpose: the Electron process has no entry-point view of the Python environment, so a narrower kill matcher would reinstate the composed-edition refusal this PR fixes. The subcommand gate is the same identity the Python side already kills on.
Pinned by new negative cases in gateway-stop.test.js; removing the gate fails the test.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed span=33f1c7d0a45f — Make the convention normative where companions are specified

Fixed in c96c069: docs/system-specs/modules/platform-context.md Companion packaging now states the companion's top-level module MUST be kirocrew_<edition> (lowercase, digits, underscores), names both matchers, and says what breaks when a companion is named outside it.

@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 Sep 30, 2026
chenmingwei23
chenmingwei23 previously approved these changes Sep 30, 2026
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.
@bolichen97
bolichen97 force-pushed the fix/desktop-reuse-edition-gateway branch from c96c069 to 06cbd2c Compare September 30, 2026 09:46
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 30, 2026
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 30, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

mechanism: cross-runtime parity test reading gateway-stop.js from the Python suite

  • fixed span=5e4993aba57e — Duplicated gateway identity across Python and Electron has no drift guard

Fixed in 06cbd2c: test/test_cli.py::TestDesktopGatewayIdentityParity reads website/electron/gateway-stop.js, pins KIROCREW_SERVER_SUBCOMMANDS equal to port_resolution._KIROCREW_SERVER_SUBCOMMANDS, and pins KIROCREW_MODULE_RE to accept the root a conventional kirocrew.plugins entry point yields and to reject a dotted submodule.
Mutation control: dropping start from the JS set fails the first test. Both JS constants carry a comment naming the pin, and cli.md names it beside the Python rule.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • fixed span=562b7f33d00d — The Python matcher still accepts the legacy dotted spawn -m kiro_crew.gateway that the Electron matcher refuses

Fixed in 06cbd2c by the spec line the item offered as one of its two options: docs/system-specs/modules/cli.md now states the dotted form is recognised by stop only and the desktop launcher does not match it and never has.
Widening the desktop matcher to the dotted form is not taken here: no launcher this repo ships spells the gateway that way, and the desktop's behaviour on it is unchanged by this PR.

@bolichen97

Copy link
Copy Markdown
Contributor Author

CI note: the one remaining red is inherited, not this diff.

Backend Tests (Windows) (2) fails in test/test_session_control_revive.py (attempt 1: 4 nodes, attempt 2 after a failed-jobs rerun: 1 different node). This PR touches no Python source; the same shard is red on main at this PR's base 64b0a33c9d in main's own CI run. The flake is already being fixed upstream: #15374, #15377, #15379 all edit that file. Every other check on 06cbd2cf is green, and GPT, Opus, Design, First Principles and UX are all PASS with no findings.

@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 Sep 30, 2026
@buluoray
buluoray enabled auto-merge (squash) September 30, 2026 17:06

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

Approving at 06cbd2c.

What I checked myself in a worktree pinned to this head:

  • The fix works for the internal edition. The Toolbox launcher ends in exec "$PYTHON" -m kirocrew_amazon "$@", and the desktop app passes gateway --no-open --port N. So tokens[index+1] is kirocrew_amazon, which matches KIROCREW_MODULE_RE, and tokens[index+2] is gateway, which is in KIROCREW_SERVER_SUBCOMMANDS. The app reuses the gateway instead of refusing it as a foreign holder.
  • Tightening the core path costs nothing. -m kiro_crew now also has to be followed by a server subcommand, which is the same slot rule _args_look_like_kirocrew already applies on the Python side. The one core spawn in gateway-supervisor.js (-s -P -m kiro_crew gateway …) still matches. -m kiro_crew run … is now refused, which is correct: the task runner is not a gateway, and this match is what authorizes a kill.
  • The tests fail when the guards are removed. node --test electron/test/gateway-stop.test.js passes 39/39 (1 skipped). Dropping the subcommand check turns 1 test red. Making the edition regex unmatchable turns 2 red. TestDesktopGatewayIdentityParity and TestComposedEditionGatewayModule pass 7/7.
  • The failing CI check is inherited. Backend Tests (Windows) (2) fails in test/test_session_control_revive.py, the family behind #15364. This PR changes no Python source, only a test that reads the JS file.

Non-blocking: the legacy dotted -m kiro_crew.gateway is still recognised by stop but not by the desktop, as the cli.md note says. That matches what happened before this PR, so it is fine to leave.

@buluoray
buluoray disabled auto-merge September 30, 2026 17:27
@buluoray
buluoray merged commit c50c246 into main Sep 30, 2026
186 of 190 checks passed
@buluoray
buluoray deleted the fix/desktop-reuse-edition-gateway branch September 30, 2026 17:27
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 30, 2026
bolichen97 added a commit that referenced this pull request Sep 30, 2026
… it (#15355) (#15580)

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

3 participants