docs(cloud): record the same-session plugin load limit and add the paste-once rollout kit - #2677
Conversation
A 2026-08-15 cloud session on this repo showed the SessionStart hook completing all 65 plugin installs (registry, user-scope settings, and marketplace all correct on disk) while the session itself still resolved no plugin command or skill: the plugin/command registry is built at process start, before hook effects land, and is never re-read. Neither /plugin nor --plugin-dir exists in cloud sessions to force a reload, so on an ephemeral VM the hook alone can never yield a session with plugins loaded. Record the observation and its consequence in CLOUD-SESSIONS.md, reframe the environment setup-script one-liner from a performance lever to the required pre-launch slot for plugin liveness, state the timing limit in the hook's own header, refresh CLOUD-FLEET-SETUP.md's stale "bootstrap is unwired" finding (settings.json now registers the hook), and fix the verification step that relied on /plugin being available in cloud sessions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018NhKrvZ4Jz1qK2wWDWXiZd
Confirmed on resume that a process restart re-reads the plugin registry (the full catalog loaded after stop/resume), and record that in CLOUD-SESSIONS.md. Add prompts/cloud-bootstrap-rollout.md: the account environment stub (paste once per claude.ai account, fetches the shared setup from the public standards repo), a prompt for creating that shared script in melodic-software/standards, and the per-repo migration prompt that renames .claude/hooks/session-start.sh to .claude/cloud-bootstrap.sh so one script serves both callers with honest semantics — the environment setup script pre-launch (what makes plugins live at turn one) and the SessionStart hook for per-session drift repair. Point CLOUD-FLEET-SETUP step 1 at the kit and settle the one-environment-per-account question. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018NhKrvZ4Jz1qK2wWDWXiZd
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b7fc6b1bb6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…da110 # Conflicts: # docs/CLOUD-FLEET-SETUP.md
Main landed #2668 while this branch was open: the fleet guide now points account stubs at the existing standards cloud-environment component (components/cloud-environment/setup.sh), which already runs the checked-out repo's bootstrap at cache build, and records that Custom network access is a hard requirement for the .NET install (#2654). Rework the rollout kit to adopt that canon instead of inventing a parallel cloud/env-setup.sh: the account part now pastes the canonical stub with the Custom allowlist, the standards part updates the existing component to prefer .claude/cloud-bootstrap.sh with a session-start.sh fallback, and the ordering puts standards before account cache rebuilds since publishing a component change does not invalidate built caches. Also fold in review findings: migrating repos must re-derive path-relative repo-root fallbacks for the new .claude/ depth, and the component should pass CLAUDE_PROJECT_DIR so repo scripts never guess. Update the fleet guide's rollout note and the cloud-sessions pointer to match. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018NhKrvZ4Jz1qK2wWDWXiZd
|
Claude finished @kyle-sexton's task in 3m 15s —— View job Code review (
|
|
Claude finished @kyle-sexton's task in 1m 19s —— View job Security review (
|
|
Last security-reviewed head: |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
Claude has reviewed this PR 3 times. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
The rollout kit's one-Default-per-account decision supersedes the "add a new environment named e.g. Melodic" option, but the sentence presenting that option survived four lines below the blockquote pointing at the kit, leaving the fleet guide contradicting itself for a top-to-bottom reader. State the settled choice and link the kit's rationale section. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018NhKrvZ4Jz1qK2wWDWXiZd
|
Claude finished @kyle-sexton's task in 56s —— View job Code review (
|
…lback Decision: the standards cloud-environment component runs a repo's .claude/cloud-bootstrap.sh and nothing else — no session-start.sh fallback branch. A repo without the file is a clean no-op whose sessions rely on their SessionStart hook until the repo migrates, which makes completing the migration the switch that turns on pre-launch bootstrap (and turn-one plugins) per repo. Update the rollout kit's standards and migration prompts and the fleet-guide rollout note to state that contract instead of the fallback they previously prescribed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018NhKrvZ4Jz1qK2wWDWXiZd
|
Claude finished @kyle-sexton's task in 3m 45s —— View job Code review (
|
| 1. Where the component runs the checked-out repo's bootstrap, invoke | ||
| .claude/cloud-bootstrap.sh when present — and only that path, no | ||
| session-start.sh fallback — best-effort (|| true) with | ||
| CLAUDE_CODE_REMOTE=true and with CLAUDE_PROJECT_DIR set to the checkout | ||
| root, so repo scripts never have to guess their root from their own path. | ||
| A repo without the file is a clean no-op: it simply has not migrated yet, | ||
| and its sessions rely on their SessionStart hook until it does. |
There was a problem hiding this comment.
Correctness: Part 1, done before every repo's Part 3, regresses turn-one plugin loading fleet-wide — including this repo, today.
Per docs/CLOUD-FLEET-SETUP.md's Findings section (line 300, unchanged by this PR): "plugins go live at turn one only when the cache build runs the bootstrap pre-launch, which the standards cloud-environment component does" — present tense, confirming the component currently invokes this repo's .claude/hooks/session-start.sh pre-launch, and that this is why this repo's sessions get plugins at turn one today.
Once Part 1 lands (component invokes .claude/cloud-bootstrap.sh only, "no session-start.sh fallback — by decision") and Part 2 rebuilds an account's cache, every repo that hasn't yet completed its own Part 3 rename — including this repo, since this PR doesn't rename its own hook — silently loses pre-launch execution. Line 57's "its sessions rely on their SessionStart hook until it does [migrate]" undersells this: the whole point of this PR is that the per-session hook alone can never produce a session with plugins loaded (per docs/CLOUD-SESSIONS.md §"Plugins in sessions on this repo"). So the transition from Part 1/2 to a given repo's Part 3 isn't neutral — it's a regression back to the exact turn-one-empty-registry bug this PR documents and fixes, for every not-yet-migrated repo.
The "Ordering" note above only sequences Part 1 before Part 2; nothing sequences Part 3 (or at least this repo's Part 3) tightly after Part 1/2 to bound the regression window, and nothing flags that the window exists. Worth either: (a) keeping a session-start.sh fallback in the component until the fleet finishes migrating, then removing it in a follow-up, or (b) making Part 3 for this repo (and any other already-working repo) a mandatory same-sitting step immediately after Part 1/2, called out explicitly in the kit.
Resolves docs/CLOUD-SESSIONS.md conflicts with #2677 by keeping main's evidence-backed same-session plugin-limit text and aligning its naming with the bootstrap rename; drops this branch's now-redundant summary sentence from the script's plugin comment in favor of main's Timing limit block, reworded for the two-caller layout. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SiC1awyDKZMW2u1Dks1Tqh
2 participants
No linked issue
Summary
Cloud sessions could never use this repo's plugins on turn one: the SessionStart hook installs the full catalog, but Claude Code builds its plugin/command registry at process start — before hook effects land — and never re-reads it. This PR records that finding with its evidence and fix, and adds the copy-paste rollout kit for moving the whole fleet (and every account environment) onto the layout that works.
Fix
docs/CLOUD-SESSIONS.md: document the same-session limit observed 2026-08-15 (hook completed65 enabled, 65 newly installed, 0 failedwith the on-disk registry fully populated, yet the same session resolved no plugin command or skill), plus the confirmation that a stop/resume restarts the process and loads everything; reframe the environment setup-script one-liner from a performance lever to the required pre-launch slot for plugin liveness..claude/hooks/session-start.sh: state the timing limit in the header — hook-time installs serve the next process start, so the environment setup script must run this bootstrap at cache build for a session to start with plugins loaded.docs/CLOUD-FLEET-SETUP.md: refresh the stale "bootstrap is currently unwired" finding (settings.json registers the hook onmainand it ran), fix the verification step that relied on/plugin(unavailable in cloud sessions), and point step 1 at the rollout kit.prompts/cloud-bootstrap-rollout.md(new): the paste-once account environment stub, the prompt for creating the sharedcloud/env-setup.shinmelodic-software/standards, and the per-repo migration prompt that renames.claude/hooks/session-start.shto.claude/cloud-bootstrap.sh— one script, two callers (environment setup script pre-launch; SessionStart hook for per-session drift repair) — and settles on one Default environment per account.Verification
markdownlint-cli2,typos, andeditorconfig-checkerpass on all touched files;shellcheckandshfmt -dpass on the hook (comment-only change)./pluginand--plugin-dirare unavailable in cloud sessions; the setup script runs after clone and before the session process.Related
docs/CLOUD-SESSIONS.md§"Plugins in sessions on this repo",docs/CLOUD-FLEET-SETUP.md,docs/MIGRATION-PLAYBOOK.md(same-version commit drift), #2061, #2539, #2657🤖 Generated with Claude Code
https://claude.ai/code/session_018NhKrvZ4Jz1qK2wWDWXiZd
Generated by Claude Code