From 31fc49513e0644ad99a3647aaad08baa5a20b2fd Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Tue, 8 Sep 2026 12:25:00 -0400 Subject: [PATCH] fix(cloud-environment): install the fleet plugin set before the repo bootstrap The cache build ran the checked-out repo's `.claude/cloud-bootstrap.sh` before fetching and installing the fleet plugin list. The canonical cloud-bootstrap hard-exits its plugin stage when `/opt/melodic-fleet-plugins.json` is absent, so in that order a repo's own plugin deltas were never installed at cache build: they arrived only when the SessionStart hook re-ran the bootstrap, and went live at the next resume. The comment calling the cache-build bootstrap call "load-bearing for plugins" was false in that order. Move the fleet fetch + install block above the repo bootstrap invocation so the bootstrap's overlay finds the list and the repo's deltas are live at turn one. Both blocks are byte-identical apart from their comments, which now state the order and why. The fleet step needs only `claude` and `jq` (both pre-image) and both blocks run after the `wait` barrier, so nothing else moves. README: the repo-bootstrap and plugin-install sections now describe the new order, and the deltas paragraph no longer claims session drift repair is the only path (it still runs on resume; it is no longer the only one). setup.test.sh: adds an ordering assertion in the file's existing idiom (the fleet install's line number must precede the repo bootstrap invocation's) and rewords the drift-repair-only claim above the settings-block guards. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01L5ZJnwTRCgc31bmfrdugyU --- components/cloud-environment/README.md | 17 ++++-- components/cloud-environment/setup.sh | 71 ++++++++++++---------- components/cloud-environment/setup.test.sh | 25 ++++++-- 3 files changed, 71 insertions(+), 42 deletions(-) diff --git a/components/cloud-environment/README.md b/components/cloud-environment/README.md index ea800f09..fb724c3b 100644 --- a/components/cloud-environment/README.md +++ b/components/cloud-environment/README.md @@ -47,7 +47,8 @@ distrusted root is a distinct `WARN`/notice line, never conflated with ## Repo bootstrap handoff -After the parallel toolchain tracks finish, the script runs the resolved +After the parallel toolchain tracks finish and the +[fleet plugin install](#plugin-install) has run, the script runs the resolved checkout's committed `.claude/cloud-bootstrap.sh`, best-effort, with `CLAUDE_CODE_REMOTE=true`, `CLAUDE_PROJECT_DIR` set to the checkout root, and the checkout root as the working directory. @@ -58,7 +59,7 @@ its next cache rebuild (see [Update lifecycle](#update-lifecycle)). ## Plugin install -After the repo bootstrap, a generic, data-driven stage installs plugins from +Before the repo bootstrap, a generic, data-driven stage installs plugins from one settings-shaped file: **the fleet list**, [`fleet-plugins.json`](fleet-plugins.json) beside this script, the one place the organization's cloud plugin set is declared. The script fetches it from @@ -72,9 +73,15 @@ repo-agnostic. A repo's own `.claude/settings.json` carries only the deltas it declares beyond the fleet (an extra marketplace, a plugin beyond the fleet, or a `false` opt-out, which project scope applies over the user-scope install). -Those are not installed here: each repo's session bootstrap applies them as -an overlay on top of this list, from the snapshot copy, at session start (see -the [cloud-bootstrap component](../cloud-bootstrap/README.md)). +Those are not installed by this stage: the +[repo bootstrap](#repo-bootstrap-handoff) that runs next applies them as an +overlay on top of this list, from the snapshot copy (see the +[cloud-bootstrap component](../cloud-bootstrap/README.md)). That is why this +stage runs first — the bootstrap's plugin step skips outright when the fleet +list is absent, so a bootstrap running before the fetch would bake no deltas +at all and leave them to arrive only when the session bootstrap re-runs and +the operator resumes. The same bootstrap still runs at session start, where +it repairs drift between the snapshot and the repo's current declarations. `extraKnownMarketplaces` entries are registered (`claude plugin marketplace add`, skipping ones already registered) and every `enabledPlugins` entry set diff --git a/components/cloud-environment/setup.sh b/components/cloud-environment/setup.sh index e502bc8f..8e51c761 100755 --- a/components/cloud-environment/setup.sh +++ b/components/cloud-environment/setup.sh @@ -36,7 +36,7 @@ # interleaves; the main shell's LOG is untouched by design. set -u -SCRIPT_VERSION='2026-09-07.2' +SCRIPT_VERSION='2026-09-08.1' STAMP='/opt/melodic-env-setup.done' STAMP_FALLBACK='/tmp/melodic-env-setup.done' # Fleet plugin list: the one standards-hosted, settings-shaped file every @@ -316,37 +316,18 @@ for track in "A gh + powershell|$track_a_log" \ rm -f "$track_file" 2>/dev/null done -# Bake the checked-out repo's committed bootstrap (.claude/cloud-bootstrap.sh -# under the resolved repo root) into the cached snapshot. One name, no -# fallbacks: every fleet repo commits its generic repository setup — -# dependencies and plugin installs — there. Running it here is load-bearing -# for plugins: the session's plugin registry is built at process start and -# never re-read, so plugin installs must land at cache build, not -# mid-session. -if [[ -z "$REPO_ROOT" ]]; then - log 'repo bootstrap skipped: repo root unresolved (see WARN above); nothing baked' -elif [[ -f "$REPO_ROOT/.claude/cloud-bootstrap.sh" ]]; then - if (cd "$REPO_ROOT" && - CLAUDE_CODE_REMOTE=true CLAUDE_PROJECT_DIR="$REPO_ROOT" \ - bash .claude/cloud-bootstrap.sh) >>"$LOG" 2>&1; then - log 'repo bootstrap .claude/cloud-bootstrap.sh baked' - else - log 'WARN repo bootstrap .claude/cloud-bootstrap.sh failed (see log)' - fi -else - # Unambiguous no-op: the root WAS resolved, the repo just has no bootstrap. - # The unresolved-root case logs its own distinct line above. - log "repo root resolved to $REPO_ROOT, no bootstrap present (.claude/cloud-bootstrap.sh) — expected no-op" -fi - # Generic plugin install from one settings-shaped file (extraKnownMarketplaces # + enabledPlugins): the fleet list at FLEET_PLUGINS_URL, which every snapshot # installs whatever repo it was built for. No repo-specific logic — a repo's -# own enabledPlugins block declares deltas beyond the fleet and the session -# bootstrap applies them as an overlay, so the snapshot itself stays the same -# for every repo built against it. This must happen here, at cache build: +# own enabledPlugins block declares deltas beyond the fleet and the repo +# bootstrap below applies them as an overlay, so the snapshot itself stays the +# same for every repo built against it. This must happen here, at cache build: # Claude Code reads its plugin registry at process start and never re-reads # it, so only snapshot-baked installs are loaded at a session's first turn. +# It must also happen BEFORE the repo bootstrap: that bootstrap's plugin stage +# reads this fetched list and skips outright when it is absent, so a bootstrap +# that ran first would bake none of the repo's deltas and leave them to arrive +# on a later resume. # Github-source marketplaces' install/update semantics already handle # versions — no snapshot-refresh logic here (the commit-drift refresh in # claude-code-plugins' own hook is specific to its directory-source @@ -357,11 +338,11 @@ elif ! command -v jq >/dev/null 2>&1; then log 'plugins: jq not available; skipping' else # The fetched copy lands in the snapshot (FLEET_PLUGINS, or its /tmp - # fallback with a WARN, mirroring the stamp) so the per-repo bootstrap's - # drift repair reads the same list offline. A fetch failure costs this - # build's plugin install, never the build: the next rebuild fetches again, - # and a session on a snapshot without the list installs nothing rather than - # guessing at a set. + # fallback with a WARN, mirroring the stamp) so the repo bootstrap below — + # and every later drift repair it runs on resume — reads the same list + # offline. A fetch failure costs this build's plugin install, never the + # build: the next rebuild fetches again, and a session on a snapshot without + # the list installs nothing rather than guessing at a set. rm -f "$FLEET_PLUGINS" "$FLEET_PLUGINS_FALLBACK" 2>/dev/null if curl -fsSL --proto '=https' --retry 2 --retry-delay 3 \ "$FLEET_PLUGINS_URL" -o "$FLEET_PLUGINS_FALLBACK" >>"$LOG" 2>&1 && @@ -381,6 +362,32 @@ else fi fi +# Bake the checked-out repo's committed bootstrap (.claude/cloud-bootstrap.sh +# under the resolved repo root) into the cached snapshot. One name, no +# fallbacks: every fleet repo commits its generic repository setup — +# dependencies and plugin installs — there. Running it here is load-bearing +# for plugins: the session's plugin registry is built at process start and +# never re-read, so plugin installs must land at cache build, not mid-session. +# It runs AFTER the fleet install above so its plugin stage finds the fetched +# fleet list and overlays the repo's own deltas onto it — that is what makes +# those deltas live at a session's first turn instead of only after the +# session bootstrap re-runs and the operator resumes. +if [[ -z "$REPO_ROOT" ]]; then + log 'repo bootstrap skipped: repo root unresolved (see WARN above); nothing baked' +elif [[ -f "$REPO_ROOT/.claude/cloud-bootstrap.sh" ]]; then + if (cd "$REPO_ROOT" && + CLAUDE_CODE_REMOTE=true CLAUDE_PROJECT_DIR="$REPO_ROOT" \ + bash .claude/cloud-bootstrap.sh) >>"$LOG" 2>&1; then + log 'repo bootstrap .claude/cloud-bootstrap.sh baked' + else + log 'WARN repo bootstrap .claude/cloud-bootstrap.sh failed (see log)' + fi +else + # Unambiguous no-op: the root WAS resolved, the repo just has no bootstrap. + # The unresolved-root case logs its own distinct line above. + log "repo root resolved to $REPO_ROOT, no bootstrap present (.claude/cloud-bootstrap.sh) — expected no-op" +fi + # Temp-file hygiene: without this the fetched installers — and this script # itself, which the environment bootstrap curls to /tmp — persist into the # snapshot and show up in every live session. Runs after the repo bootstrap, diff --git a/components/cloud-environment/setup.test.sh b/components/cloud-environment/setup.test.sh index 963f5632..6c7c280e 100755 --- a/components/cloud-environment/setup.test.sh +++ b/components/cloud-environment/setup.test.sh @@ -153,11 +153,11 @@ assert_contains 'README bootstrap URL matches the component path' \ "$(cat "$readme")" \ 'raw.githubusercontent.com/melodic-software/standards/main/components/cloud-environment/setup.sh' -# The build installs from the fleet list alone. A repo's enabledPlugins block -# is a deltas overlay applied by the session bootstrap's drift repair, so no -# call here may install from the checkout's settings file: reintroducing one -# would make the snapshot repo-specific again and resurrect the block as a -# whole-set install source. +# This script installs from the fleet list alone. A repo's enabledPlugins block +# is a deltas overlay the repo's own bootstrap applies, so no call here may +# install from the checkout's settings file: reintroducing one would make the +# snapshot repo-specific again and resurrect the block as a whole-set install +# source. # shellcheck disable=SC2016 # the $ is a literal in the needle assert_not_contains 'setup.sh does not install from the checkout settings block' \ "$(cat "$script")" 'install_plugins_from "$settings"' @@ -165,6 +165,21 @@ assert_not_contains 'setup.sh does not install from the checkout settings block' assert_not_contains 'setup.sh does not resolve the checkout settings block for install' \ "$(cat "$script")" 'settings="$REPO_ROOT/.claude/settings.json"' +# Ordering contract: the fleet install must precede the repo bootstrap. The +# repo bootstrap applies the repo's deltas as an overlay on the fleet list and +# skips entirely when that list is absent, so a bootstrap that runs first bakes +# no deltas into the snapshot and the repo's own plugins go live only on the +# next resume. +# shellcheck disable=SC2016 # the $ is a literal in the grep needle +fleet_install_ln="$(grep -n -F 'install_plugins_from "$fleet_file" fleet' "$script" | head -n 1 | cut -d: -f1)" +repo_bootstrap_ln="$(grep -n -F 'bash .claude/cloud-bootstrap.sh' "$script" | head -n 1 | cut -d: -f1)" +if [[ -n "$fleet_install_ln" && -n "$repo_bootstrap_ln" && "$fleet_install_ln" -lt "$repo_bootstrap_ln" ]]; then + pass 'fleet plugin install runs before the repo bootstrap' +else + fail 'fleet plugin install runs before the repo bootstrap' \ + "fleet install at line '${fleet_install_ln:-none}', repo bootstrap at line '${repo_bootstrap_ln:-none}'" +fi + # Spawn census for install_plugins_from: two sources must share one # marketplace list and one plugin list, the memoization cloud-bootstrap.sh # relies on when it reads the fleet list and then the repo overlay. Sourced