Skip to content

fix: refresh app agents before the boot builds the mcp overlay - #32133

Closed
bolichen97 wants to merge 1 commit into
mainfrom
fix/14059-app-agents-before-overlay
Closed

bolichen97 wants to merge 1 commit into
mainfrom
fix/14059-app-agents-before-overlay

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On the first gateway start after an upgrade, agents declared by an app reach their control-plane MCP tools through stubs that name the running launcher, not the previous one.

An app agent that lists a host-managed server (@kirocrew-core, @kirocrew-cron) in its tools gets that server's launch spec copied into its materialized spec, and the spec names the running launcher. When a server is routed, the boot builds the MCP overlay from ~/.kiro/agents before the dashboard re-materializes app agents. So after an upgrade the overlay stubs for those agents keep the previous version's launcher, and their sessions get identity_unattested on the first work_* / session_* call until the operator toggles Share MCP Backends or restarts a second time. Under --no-dashboard the boot never re-materializes app agents at all.

Why it matters

Every operator who routes a server and runs an app that declares agents hits this on each upgrade: the app's agents lose their control-plane tools on the first start, and nothing on screen points at the cause.

Not a goal

  • Moving the whole app resource reconcile (MCP servers, skills, crons, the stale-resource prune) ahead of the overlay; it stays in dashboard startup.
  • Changing how an app enabled at runtime reaches the overlay; the existing overlay refresh covers that.
  • The deferred crew-fork refresh, which can also land after the overlay pass (see Sibling sweep).

What changed (motivation → approach → change)

Symptom and cause. The overlay pass reads the agent specs on disk, and app agent specs get the current launcher only later, from the dashboard's app reconcile. A second overlay pass after that reconcile cannot help: an overlay refresh refuses a routed target the running daemon does not hold, and a moved launcher is exactly that.

Change. When mcp_gateway.stub_servers is non-empty, the boot now re-materializes every enabled app's agent specs, and nothing else, right before the overlay pass in gateway_runtime/service_boot.py, on dashboard and --no-dashboard boots alike. The new refresh_enabled_app_agents in apps/bridges_register.py runs the agent half of register_app for each enabled app: the same source (a shipped builtin's manifest is read from the package, which matters because the data-home copy is still the previous version's at this point after an upgrade), the same admission gate, and the same field-wise refresh. One app's failure is logged and the others still refresh; a failure of the whole step keeps the old specs and the boot goes on. The app-kit platform spec (§7) records the order.

Boot cost. The step runs off the event loop (asyncio.to_thread) and only when a server is routed, which is off by default, so a default boot does no new work. It cannot be deferred: the overlay and the daemon's routing are fixed when the broker starts, and a spec written after that waits for a restart. Its worst case is one small JSON read, render and write per declared agent of each enabled app, which scales with installed apps, not with sessions or history, and repeats writes the dashboard's reconcile already makes later in the same boot.

Backwards compatibility

Compatible: the step writes the same app agent specs the dashboard's reconcile already writes later in the same boot, only earlier; no spec, config key or API changes shape.

Removes nothing: no file, key or capability is deleted or narrowed; app agent specs are rewritten from their templates as before.

Tests

  • test/test_app_agents_refresh_before_mcp_overlay.py runs the boot with an enabled app whose materialized agent spec names an old launcher. With a routed server, the overlay pass sees the current launcher; with nothing routed, the spec is left alone, so the default boot gains no work.
  • test/test_slack_gateway_overload_wiring.py gives its bare orchestrator the routed-server list run now reads.

Proof: PROVEN test/test_app_agents_refresh_before_mcp_overlay.py::test_boot_refreshes_app_agents_before_the_overlay_pass[stub_servers0-expected0] (head 2b77131)

Determinism: the new test passed 20 runs at -n0, 10 runs at -n 4 --dist loadgroup --max-worker-restart=2 beside test/test_slack_gateway_overload_wiring.py and test/test_app_bridges_agent_configs.py, and a shuffled order of those three files (seed 18489, 88 node ids).

Manual verification

N/A — unit coverage sufficient: the test drives the real boot sequence up to the overlay pass with a real installed app, and the overlay builder itself is unchanged.

Screenshots / video

N/A — no frontend change.

Related Issues

Closes #14059

Sibling sweep

Swept: git grep -nE "refresh_forks=|_materialize_managed_refs|reconcile_enabled_app_resources" -- src/kiro_crew/
Sibling: src/kiro_crew/agent_parts/spec_rebuild.py -- not affected -- the host agent spec is rebuilt in _init_services, before the overlay pass
Sibling: src/kiro_crew/dashboard/server_runtime/app_platform.py -- not affected -- the full reconcile still runs here and rewrites the same specs after the overlay

Open: agent_materialization/fork_refresh.py refreshes crew forks of owned templates (their managed server commands included) on a thread started at boot, which can finish after the overlay pass. It is deferred off the boot path on purpose, so it needs its own decision and is left for a follow-up.

Pattern harvest

Not generalizable: the one boot-ordered writer of app agent specs ran after the one reader that freezes them; the order is now pinned by a boot test rather than a rule.

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

Contributed under the project's Apache-2.0 license.

An app agent that lists a host-managed server in its tools gets that
server's launch spec, which names the running launcher, copied in when
it is materialized. The boot built the MCP overlay before the dashboard
re-materialized app agents, so the first start after an upgrade routed
them through the previous launcher until a second restart. When a
server is routed, the boot now re-materializes every enabled app's
agents first, on dashboard and --no-dashboard boots alike.
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 7, 2026 06:02
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 7, 2026
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@bolichen97
bolichen97 enabled auto-merge (squash) November 7, 2026 06:14
@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 7, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Superseded: main already resets the kirocrew-* launchers when it builds the overlay (#13155); verified with a targeted repro on main d27a5fde9079. For each of the 10 reserved kirocrew-* servers with a managed invocation on the test host (kirocrew-computer is gated off there), an app agent spec whose entry names a previous version's launcher (/opt/toolbox/tools/kirocrew/0.7.0.8/bin/kirocrew), rewritten with that server routed, gets a stub that launches the running managed invocation (_rewrite_single_spec, the same path test/test_mcp_gateway_control_plane_repair.py::test_a_hand_authored_control_plane_launches_the_managed_binary_and_passes_the_gate[reaped-pin] pins). test_the_fingerprint_sees_the_managed_launch_so_an_upgrade_regenerates_overlays covers the upgrade boot. Closing this PR; the boot-path refresh it adds is not needed.

@bolichen97 bolichen97 closed this Nov 7, 2026
auto-merge was automatically disabled November 7, 2026 14:57

Pull request was closed

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 7, 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.

App-declared agents: boot builds the MCP overlay before app agents are re-materialized, so the first start after an upgrade serves stale stubs

1 participant