Skip to content

fix(apps): take an app down only to replace it on a registry update - #32213

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/14306-registry-update-replacement-bracket
Nov 7, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/14306-registry-update-replacement-bracket

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Updating or re-installing an installed app from the App Store stops its backend only for the moment its files are swapped, and brings the app back if the swap fails.

Two gaps on the registry paths:

  • Installing an already-installed app from the App Store (POST /api/apps/registry/install and /install-stream) replaced the app's files with its backend still running. On Windows that fails with a sharing violation (WinError 32), the same failure the update route had before fix(apps): stop the backend before a registry update replaces files #14278.
  • The update route (POST /api/apps/{name}/update, registry branch) stopped the backend and removed the app's agents, skills, crons and MCP servers before the clone and build. A successful update kept the app offline for the whole clone and build, and an update refused before touching any file (not in the registry, admission, downgrade, a failed build) still stopped and restarted the app.

Why it matters

Anyone on Windows who re-installs an app from the App Store gets a failed install. Everyone else gets an app that goes dark for minutes during an update, and restarts for nothing when the update is refused.

Not a goal

What changed (motivation → approach → change)

The stop and the resource scrub sat in the route, before the install, because the route had no other place to put them. The issue asked for the bracket to sit inside the install, at the point where files are actually replaced.

install_from_registry takes an optional before_replace callback and awaits it right before update_app copies a managed app's new files in: after every gate, the clone, the build, setup.onInstall and the startup-hook recheck. A new shared helper, _reinstall_from_registry in routes_lifecycle.py, passes the take-down (stop the backend, deregister everything but the agent configs) as that callback. The update route's registry branch and both registry install routes use it for an installed app; a fresh install calls install_from_registry as before. A self-managed app (resources: "app") is never taken down: it replaces no installed file and owns its own registrations. A gateway-managed app whose registry entry declares resources: "app" takes that path too, so once the install has written its record self-managed the helper stops its backend and fully deregisters it; it registers its own from then on.

The agent configs stay on disk through the take-down (deregister_app(name, keep_agents=True) in bridges_register.py) because they hold the user's edits. Registration rewrites each one in place, so a config it cannot rewrite keeps its last good copy: a full disk, or a data home that does not own a shared agents directory, where registration declines to write. After the take-down the helper prunes the configs the installed manifest no longer declares. A failure restores an app that may run; an app the update left unable to run (a new sessionApproval) loses its configs, by the suspend on success and a deregister on failure. The update route now suspends such an app as the two registry install routes already do.

Request Before After
Registry install of an installed managed app files replaced with the backend running stop, scrub, replace, re-register, restart; restored on a failed replacement
Registry update, refused before the copy stop, scrub, restart app keeps running
Registry update, success offline for clone + build + copy offline for the copy only

The registry facade lists the two typing names the new parameter brings (Awaitable, Callable), the routes facade names the two bridges helpers the prune uses, and the app-kit-platform spec records where the take-down happens, which routes go through it, and why a registry update keeps the agent configs.

Backwards compatibility

Compatible: before_replace and deregister_app's keep_agents are optional keywords that default to the old behaviour, every route keeps its status codes and response fields, and the update route's two preflights (startup hook 409, missing git 400) are unchanged.

Removes nothing: the stop, scrub and restore still run on every update and re-install that reaches the file copy; only their position moves.

Tests

  • test_an_update_takes_the_app_down_only_to_copy_its_files drives install_from_registry: a managed app is taken down after the build and the recheck, right before the copy; a self-managed app is never taken down. test_registry_reinstall_rechecks_retained_startup_before_replacement also pins that a refusal at the recheck never takes the app down.
  • test_reinstall_over_an_installed_app_takes_it_down_to_replace_its_files pins stop, deregister, replace, register, start on both registry install routes, for a successful and a failed replacement.
  • test_registry_update_refused_before_the_replacement_leaves_the_app_running pins that a clone failure on the update route stops nothing.
  • test_registry_update_to_self_managed_cleans_up_only_gateway_owned_resources pins a stop and a full deregister for a gateway-managed app the install makes self-managed, also when a later step fails, and neither for an app that was self-managed already.
  • test_a_registry_update_keeps_the_users_agent_edits runs on the update route and both registry install routes.
  • test_a_registry_update_keeps_an_agent_file_it_cannot_rewrite pins, on all three routes, that a declined or failed (disk full) rewrite leaves the user's config byte for byte.
  • test_a_registry_update_that_needs_consent_leaves_no_agent_file pins that an app a new sessionApproval disables keeps no agent config, on success and on a failure after the copy.
  • test_an_agent_the_new_version_drops_does_not_come_back runs on the local and the registry update.
  • The existing update-route ordering and restore tests model the take-down inside the install.

Proof: PROVEN test/test_app_update_keeps_agent_edits.py::TestUpdateKeepsAgentEdits::test_a_registry_update_keeps_the_users_agent_edits[/api/apps/cov-test-app/update-body0-200], test/test_app_update_keeps_agent_edits.py::TestUpdateKeepsAgentEdits::test_a_registry_update_keeps_the_users_agent_edits[/api/apps/registry/install-body1-201], test/test_app_update_keeps_agent_edits.py::TestUpdateKeepsAgentEdits::test_a_registry_update_keeps_the_users_agent_edits[/api/apps/registry/install-stream-body2-200], test/test_app_update_keeps_agent_edits.py::TestUpdateKeepsAgentEdits::test_a_registry_update_keeps_an_agent_file_it_cannot_rewrite[/api/apps/cov-test-app/update-body0-200-declined], test/test_app_update_keeps_agent_edits.py::TestUpdateKeepsAgentEdits::test_a_registry_update_keeps_an_agent_file_it_cannot_rewrite[/api/apps/cov-test-app/update-body0-200-disk full] (head 6edab91)

Determinism: the three changed test files passed three runs in a shuffled order (seeds 1, 2, 3), 94 tests each. The new route test passed 20 runs at -n0, and its file (51 tests) passed in a shuffled order (seed 14306).

Manual verification

N/A — unit coverage sufficient: the route tests pin the call order around a stubbed install, and the pipeline test drives the real install_from_registry to the swap. The Windows sharing violation itself needs a Windows host to reproduce.

Screenshots / video

N/A — no frontend change.

Related Issues

Closes #14306

Sibling sweep

Swept: git grep -nE "\bupdate_app\b(|install_from_registry(" -- 'src/kiro_crew/**.py'
Sibling: src/kiro_crew/apps/routes_install.py:176 -- not affected -- the local-source branch already stops the backend before update_app and has no clone or build to wait for; its delete-then-rewrite of the agent configs predates this PR and is tracked in #32258
Sibling: src/kiro_crew/apps/default_installs.py:269 -- not affected -- it passes resolved_entry, which install_from_registry refuses for an installed app, so it only ever installs fresh
Sibling: src/kiro_crew/apps/manager_adopt.py:65 -- not affected -- it swaps a built-in record, whose code ran from the read-only package rather than the tree being replaced

Swept: git grep -nE "_deregister_app_off_loop(" -- src/kiro_crew/apps
Sibling: src/kiro_crew/apps/routes_enable.py:434 -- not affected -- the enable rollback disables the app, so no re-registration follows the deregister
Sibling: src/kiro_crew/apps/routes_uninstall.py:589 -- not affected -- uninstall removes the app, so no re-registration follows the deregister

Pattern harvest

Not generalizable: the take-down belongs at one transaction's replacement boundary, which only install_from_registry has; the other file swaps already stop first or replace nothing a backend holds.

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

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 7, 2026 08:22
@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 6edab91dd6f029bbc8b90926c282b006f2757aae 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 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

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

Nothing blocks. The take-down now runs inside the install, at the file copy, and the defect is linked (#14306). One rider adds a second way to keep the user's agent edits.

Notes

  • Item 4 — rides along: on a registry update, deregister_app(name, *, keep_agents: bool = False) now leaves the agent configs in place. The local-source branch still keeps edits through _snapshot_agent_configs_off_loop (routes_install.py:175). That makes two spellings of "keep the user's agent edits across an update". The claimed failure modes ("a full disk, or a data home that does not own a shared agents directory") have no issue or test that fails on base. Subtraction: delete keep_agents, and make _take_down call _snapshot_agent_configs_off_loop and pass the snapshot to the register/restore steps, as the local branch does.

What this change ships

Inventory (7 items) — 6 justified

Intent: updating or re-installing an app from the App Store takes it offline only while its files are swapped, and stops failing on Windows. FIX.

  1. Re-installing an installed managed app from the App Store stops its backend before the file swap (Windows WinError 32) — justified
  2. A registry update that is refused, or whose clone or build fails, leaves the app running — justified
  3. A successful registry update is offline only for the copy, not for the clone and build — justified
  4. A registry update keeps agent configs on disk instead of snapshotting them — rides along, second spelling of _snapshot_agent_configs_off_loop
  5. Agents the new version drops are pruned after the take-down — justified
  6. The update route now suspends an app that needs fresh sessionApproval, as the install routes already do — justified
  7. An app the install turns self-managed is stopped and fully deregistered — justified

[FIRST-PRINCIPLES-REVIEWED] 6edab91

Description read

[DESCRIPTION-READ] 443a11b23713bb38a7ba9e0e62f8008f3a21376eb92e3c47642afc4c1750a2b2

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks. The take-down now sits inside the install, right where files get replaced, and every route that replaces an installed app's files goes through the shared helper.

Notes

  • _reinstall_from_registry checks the record's resources before and after the install to catch a switch to self-managed. That leaves two owners of the install's ownership decision. Adding a second callback to install_from_registry for that path, next to before_replace, would keep it in one place.

[DESIGN-REVIEWED] 6edab91

Description read

[DESCRIPTION-READ] bf5ed5571d6ea4020eaa7be7b83a71f1485b349e7f855f71d9e2010d0c3b11fc

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 6edab91

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

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

@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6edab91

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6edab91dd6f029bbc8b90926c282b006f2757aae 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 7, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 7, 2026 08:43
@bolichen97
bolichen97 force-pushed the fix/14306-registry-update-replacement-bracket branch from 221ed2b to cdbb733 Compare November 7, 2026 11:06
@bolichen97

bolichen97 commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=b72866d639ef a registry update deleted the agent configs before a rewrite that could fail

fixed in cdbb733: the registry take-down deregisters with deregister_app(name, keep_agents=True), so no agent config is unlinked before the re-registration. _register_agents rewrites each one in place through atomic_write, so a write it declines (_declined_foreign_spec_write, a data home that does not own the shared agents directory) or one that fails (ENOSPC) leaves the last good copy and the user's edits on disk.
Dropped agents are pruned only after the copy, against the installed manifest (_prune_stale_app_resources). An app the update leaves unable to run loses its configs: suspended on success, fully deregistered on a failure after the copy.
The take-down no longer snapshots, so no edit lives only in memory. Pinned by test_a_registry_update_keeps_an_agent_file_it_cannot_rewrite (declined and disk full, on all three routes) and test_a_registry_update_that_needs_consent_leaves_no_agent_file.
The local-source update keeps its older snapshot-then-deregister order, which this PR does not change; that sibling is tracked in #32258.

[operator: bolichen97]

@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] The Backend Tests shard 2 red (Linux and Windows) on the previous head is test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget, which is red on main too: the security package is 34,855 lines on main against a budget of 34,845, and this PR does not touch that package. #32183 raises the budget; this PR waits for it to merge rather than working around it.

@bolichen97
bolichen97 force-pushed the fix/14306-registry-update-replacement-bracket branch from cdbb733 to 6edab91 Compare November 7, 2026 13:50
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=b72866d639ef switching to self-managed ownership left the old backend and resources active

fixed in 6edab91: _reinstall_from_registry reads the record's ownership before the install and, when the install skipped the take-down, again after it. A gateway-managed app whose record the install wrote self-managed (resources: "app") then has its backend stopped and deregister_app run in full (agents included), in the app-kit-platform §17 order, also when a step after the record write fails. An app that was self-managed already is left alone, and a managed install still goes through the take-down.
Pinned by test_registry_update_to_self_managed_cleans_up_only_gateway_owned_resources (gateway to app, gateway to app with a later failure, app to app). The same push fixes this head's two CI reds: a docstring phrase the comment-history gate rejects, and a test that patched atomic_write on an owner module instead of the kiro_crew.apps.bridges facade.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention 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 7, 2026

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

Approved for the on-call. Review lanes pass on 6edab91, no conflict, no open change request.

@KiroCrewCaptain
KiroCrewCaptain merged commit b879c75 into main Nov 7, 2026
99 of 109 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/14306-registry-update-replacement-bracket branch November 7, 2026 19:44
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision 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 update: registry install of an installed app skips the backend stop; stop brackets the whole clone/build

2 participants