Skip to content

fix(acp): share a KAS MCP server's launch reference (backport #34542) - #34610

Merged
buluoray merged 1 commit into
release/0.12.0from
crew/slack/kas-mcp-launch-ref-0.12.0
Nov 11, 2026
Merged

buluoray merged 1 commit into
release/0.12.0from
crew/slack/kas-mcp-launch-ref-0.12.0

Conversation

@buluoray

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On 0.12.x, a KAS local stdio MCP server stays up when another session starts, instead of being restarted, timing out and losing its tools.

Backport of #34542 to release/0.12.0. On 0.12.1, every new session on a shared KAS runtime declares the env-relay launcher with its own session key and a random version. KAS keeps one MCP pool per engine process and restarts a server whose declaration changed, so the server is killed mid-start, hits the 60 s timeout, and its tools vanish with no notice. A customer is hitting "MCP not loading" on 0.12.1.

Why it matters

Any 0.12.x user with a local stdio MCP server whose env Crew relays (any non-boolean env value) loses that server's tools as soon as a second session starts on the same KAS runtime. Nothing in the UI says why.

Not a goal

What changed (motivation → approach → change)

One pick, 337ad4fcc7d6ab7e1deb15e6a688399ed7b04dcd (squash of #34542, original author @JLargent42), applied with -x. The commit's author is Ray because the leak guard refuses a noreply author email; the original author is credited in the commit message.

Root cause → change: the launcher reference now names no session (SHARED_SESSION = "shared"), and its version is an HMAC of the snapshot under a per-process in-memory key, so every session of the same agent sends the same declaration. The gateway counts the projections holding each shared file (_SHARED_HOLDS), and discard_batch removes it with the last hold.

Prerequisites: none picked. Hand-port of three conflicting hunks. The conflicting context on main comes from feature work that is not on 0.12.x. Pulling it in would add a whole feature, so it was left out:

Hunks git auto-merged, trimmed because they describe the bridge release does not have:

  • kas_env_launch.py module docstring: dropped the "A Crew-owned Connection bridge keeps a random version per write ..." sentence.
  • src/kiro_crew/kas_env_shim.py snapshot_name docstring: dropped the Connection bridge sentence.
  • docs/system-specs/modules/security.md: dropped "A Crew-owned Connection bridge keeps a random version per write, and its provider removes exactly the ones its batch names when it shuts down."

Backwards compatibility

Compatible: the launcher still accepts any reference whose snapshot matches; old per-session snapshots are removed by the existing boot sweep.

Removes nothing: the shape of the launch reference changes, but no key, path or reader is removed; per-session files are replaced by shared ones read by the same launcher.

Tests

Test changes come from the pick (test/test_kas_env_launch.py, test/test_kas_env_launch_resume.py, test/test_kas_mcp_not_run_notice.py).

Run locally, single process (-n0), on head fa7cfe7:

  • test/test_kas_env_launch.py, test/test_kas_env_launch_resume.py, test/test_kas_mcp_not_run_notice.py, test/test_kas_header_bridge.py, test/test_kas_inherited_auth_env.py, test/test_kas_agents_mcp_env_relay.py: 184 passed
  • test/test_kas_env_shim.py: 16 passed
  • black, flake8, check_comment_history.py and check_brand_name.py against origin/release/0.12.0: clean

Proof: not provable -- other: backport; the fix was proven on main in #34542 and this PR carries the same tests

Manual verification

N/A — unit coverage above; the same change is on main.

Related Issues

Backport of #34542. Fixes #34382 on 0.12.x.

Sibling sweep

Siblings: none -- the backport touches the same sites #34542 changed on main

Pattern harvest

Not generalizable: backport of an already-harvested fix (#34542)

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

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

…34542)

KAS keeps one MCP pool per engine process and restarts a server whose
declaration changed. The env-relay launcher reference carried the session
key and a random version, so every new session on a shared runtime killed
the server mid-start for every session. The reference now names no session
and its version is an HMAC of the snapshot under a per-process key; the
gateway counts the projections holding each file and removes it with the
last.

Fixes #34382

Original author: @JLargent42 (#34542)
(cherry picked from commit 337ad4f)
@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 10, 2026 15:32
@buluoray
buluoray requested review from tim-finnigan and removed request for a team November 10, 2026 15:32
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 10, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision fa7cfe78082744a5de331fb700c52667295b72bc touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: this is a faithful backport of #34542, already decided on main, and the three hand-ported hunks only leave out the OAuth bridge that 0.12.x does not have.

Notes

  • The version HMAC is keyed per process, so every gateway restart writes new shared files and orphans the old ones until the boot sweep removes them. That matches the old per-session behaviour, so it is not a regression.
  • A failed create still holds its file, as the discard_batch docstring says. That file waits for the boot sweep.

[DESIGN-REVIEWED] fa7cfe7

Description read

[DESCRIPTION-READ] 7e9a6ab6b65e8c3113360b01c3f002d71a2924776cd3dd4fb1f33043a0b7d005

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

This backports a fix whose defect is on record (#34382). The one leftover is a dead shared=False branch left behind by the hand-port.

Notes

  • Item 5 — one consumer, generalized: both _write_snapshot callers on this branch pass shared=True and session_key=SHARED_SESSION (grepped _write_snapshot( in kas_env_launch.py: 2 call sites, 0 using the default). The secrets.token_hex(16) random-version branch and the contextlib.nullcontext() fallback only exist on main because of the Connection bridge, which the description says "is not on 0.12.x". Subtraction: drop the shared parameter, its else branch and the nullcontext path from the 0.12.x _write_snapshot, and always take _shared_version under _SHARE_LOCK.

What this change ships

Inventory (6 items) — 5 justified

Intent: on 0.12.x, keep a KAS local stdio MCP server running when a second session starts. FIX.

  1. A stdio MCP server's launch reference names no session, so every session sends the same declaration — justified
  2. The launch version is an HMAC under a per-process key instead of a random value — justified
  3. A shared snapshot file is removed only when its last holder discards it (_SHARED_HOLDS) — justified
  4. The header bridge reference is also shared — justified
  5. _write_snapshot keeps a shared flag with a random-version branch no caller uses — one consumer, generalized
  6. Spec and doc text updated to the shared reference — justified

[FIRST-PRINCIPLES-REVIEWED] fa7cfe7

Description read

[DESCRIPTION-READ] d604ed93567714a1e40cad40fdd93208bbd2ae02f024477db2ce40a3ce09a894

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings. None of the three candidates holds up against the code. A provider's shutdown() has no caller that runs it twice ("every caller drops the provider afterwards"). The names a handle records always cover the names in its batch, so the max(..., 1) fallback never takes a hold the session didn't take itself. The per-session reference is only sent when a snapshot write fails with an OSError.

[OPUS-REVIEWED] fa7cfe7

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

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

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] fa7cfe7

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

@buluoray
buluoray merged commit 3e04af5 into release/0.12.0 Nov 11, 2026
21 of 23 checks passed
@buluoray
buluoray deleted the crew/slack/kas-mcp-launch-ref-0.12.0 branch November 11, 2026 02:23
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Nov 11, 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