Merge remote-tracking branch 'origin/main' into published-caching-cs-11043

Author: backspace

.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "cardstack-boxel",
+  "owner": {
+    "name": "Cardstack",
+    "url": "https://boxel.ai"
+  },
+  "description": "Claude Code plugins published from the cardstack/boxel monorepo.",
+  "plugins": [
+    {
+      "name": "boxel-cli",
+      "source": "./packages/boxel-cli/plugin",
+      "description": "Skills for working with Boxel realms via @cardstack/boxel-cli."
+    }
+  ]
+}

.claude/skills/indexing-diagnostics/SKILL.md

@@ -1220,8 +1220,8 @@ Three env vars control the per-prerender-server shape. They're resolved once at
 
 | Env var | Default | What it controls | When to change it |
 |---|---|---|---|
-| `PRERENDER_PAGE_POOL_SIZE` | `5` | Total simultaneous Chrome tabs the pool can manage. Also the `capacity` the server reports to the manager on each heartbeat, which drives warm-vacancy routing. | Fleet capacity. Raise when `waits.semaphoreMs` dominates `launchMs` across rows from all realms (server-wide saturation); lower if you need to reduce memory footprint and you can confirm from snapshots that pending rarely approaches `totalTabs`. |
-| `PRERENDER_AFFINITY_TAB_MAX` | `5` (clamped to `PRERENDER_PAGE_POOL_SIZE`) | Max tabs a single affinity (realm or user) can simultaneously hold from the pool. | Rarely. Must be ≥ 2 for the self-referential prerender deadlock to be prevented — PagePool logs a warning at startup when it isn't. Lower only if you want to force multi-realm fairness at the tab-routing level. |
+| `PRERENDER_PAGE_POOL_MIN` / `_MAX` | unset → fixed pool of `options.maxPages` (5) | Dynamic-pool envelope. The pool boots at MIN, expands up to MAX under saturation, contracts back to MIN after sustained idle. The live capacity is what the server reports to the manager on each heartbeat, which drives warm-vacancy routing. | Fleet capacity. Raise MAX when `waits.semaphoreMs` dominates `launchMs` across rows from all realms (server-wide saturation); lower MAX if you need to reduce memory footprint and you can confirm from snapshots that pending rarely approaches `totalTabs`. Setting MIN === MAX disables expansion/contraction. |
+| `PRERENDER_AFFINITY_TAB_MAX` | `5` (clamped to the effective pool max: `PRERENDER_PAGE_POOL_MAX` when set, otherwise fixed `maxPages`) | Max tabs a single affinity (realm or user) can simultaneously hold from the pool. | Rarely. Must be ≥ 2 for the self-referential prerender deadlock to be prevented — PagePool logs a warning at startup when it isn't. Lower only if you want to force multi-realm fairness at the tab-routing level. |
 | `PRERENDER_AFFINITY_FILE_CONCURRENCY` | unset → `max(1, PRERENDER_AFFINITY_TAB_MAX − 1)` (the deadlock-safety ceiling) | Cap on concurrent `file` renders within a single affinity. Module and command calls bypass admission; they're never capped by this knob. | Cross-realm fairness. When one realm's fan-out (e.g. a catalog reindex) is stealing render budget from every other realm, lower this below the ceiling to reserve tabs for other affinities. The effective cap is always `min(env, ceiling)` so this can't accidentally break the deadlock-safety invariant. |
 
 **Default invariant**: when `PRERENDER_AFFINITY_FILE_CONCURRENCY` is unset, the effective file-admission cap equals the deadlock-safety ceiling — same behavior as before the knob existed. Changing the knob is an explicit operator decision driven by `admissionMs` telemetry; don't adjust it without data.

.github/workflows/ci-lint.yaml

@@ -125,3 +125,100 @@ jobs:
         if: ${{ !cancelled() }}
         run: pnpm run lint
         working-directory: packages/boxel-cli
+      - name: Verify Boxel CLI plugin synopsis is fresh
+        # Regenerates the `<!-- generated:commands -->` blocks in plugin/skills/*/SKILL.md
+        # from the Commander tree and fails if the working tree changed — i.e. someone
+        # added or changed a CLI command without running `pnpm build:plugin`.
+        if: ${{ !cancelled() }}
+        run: |
+          pnpm run build:plugin
+          if ! git diff --exit-code -- plugin/skills; then
+            echo "::error::plugin/skills synopsis is stale. Run 'pnpm build:plugin' in packages/boxel-cli and commit the result."
+            exit 1
+          fi
+        working-directory: packages/boxel-cli
+      - name: Verify boxel-skills sync
+        # Regenerates plugin/skills/boxel-development and plugin/skills/boxel-design from
+        # cardstack/boxel-skills at the pinned tag in scripts/build-skills.ts. Fails if
+        # the working tree changed — i.e. someone hand-edited boxel-skills-derived
+        # content without bumping the pin and re-running `pnpm build:skills`.
+        if: ${{ !cancelled() }}
+        run: |
+          pnpm run build:skills
+          if ! git diff --exit-code -- plugin/skills; then
+            echo "::error::plugin/skills is out of sync with cardstack/boxel-skills. Bump BOXEL_SKILLS_VERSION in scripts/build-skills.ts (or fix upstream), run 'pnpm build:skills' in packages/boxel-cli, and commit the result."
+            exit 1
+          fi
+        working-directory: packages/boxel-cli
+      - name: Verify plugin version bumped when synopsis changed
+        # If a PR's diff against main touches any generated:commands block, the plugin's
+        # version must also bump in the same diff. Otherwise marketplace consumers won't
+        # see the update — Claude Code caches by version string.
+        if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+        run: |
+          set -euo pipefail
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+          # `actions/checkout` uses default depth, so $BASE (a `main` SHA) usually
+          # isn't local. Fetch both explicitly so `git diff`/`git show` succeed.
+          git fetch --no-tags --depth=1 origin "$BASE" "$HEAD"
+          # Did the generated-commands block change in any SKILL.md? Compare the
+          # block at $BASE vs $HEAD per-file. Any difference inside the markers
+          # (heading, description, argument, blank line) flips SYNOPSIS_CHANGED.
+          # `git cat-file -e` is the explicit existence probe — using `git show`
+          # with `2>/dev/null` would still propagate exit 128 and trip pipefail.
+          extract_block() {
+            local rev="$1" path="$2"
+            if git cat-file -e "$rev:$path" 2>/dev/null; then
+              git show "$rev:$path" \
+                | awk '/<!-- generated:commands:start -->/,/<!-- generated:commands:end -->/'
+            fi
+          }
+          SYNOPSIS_CHANGED=
+          while IFS= read -r f; do
+            base_block=$(extract_block "$BASE" "$f")
+            head_block=$(extract_block "$HEAD" "$f")
+            if [ "$base_block" != "$head_block" ]; then
+              SYNOPSIS_CHANGED=1
+              break
+            fi
+          done < <(git ls-tree -r --name-only "$HEAD" -- packages/boxel-cli/plugin/skills | grep '/SKILL\.md$' || true)
+          if [ -z "$SYNOPSIS_CHANGED" ]; then
+            echo "No generated synopsis changes detected; skipping version-bump check."
+            exit 0
+          fi
+          # Was the plugin manifest version touched?
+          if ! git diff "$BASE" "$HEAD" -- packages/boxel-cli/plugin/.claude-plugin/plugin.json \
+            | grep -qE '^[+-]\s*"version"'; then
+            echo "::error::plugin/skills synopsis changed but plugin.json version was not bumped. Marketplace consumers won't see the update without a new version. Bump 'version' in packages/boxel-cli/plugin/.claude-plugin/plugin.json."
+            exit 1
+          fi
+          echo "Synopsis changed and plugin.json version was bumped — OK."
+        working-directory: .
+      - name: Verify plugin version bumped when boxel-skills content changed
+        # Mirrors the synopsis-bump check above, but gates on changes to skill folders
+        # generated by `pnpm build:skills` (boxel-development/, boxel-design/). Any
+        # content change there requires a plugin.json bump so marketplace consumers
+        # actually pick up the new content — Claude Code caches by version string.
+        if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+        run: |
+          set -euo pipefail
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+          # See note in the previous step — fetch base/head explicitly because
+          # `actions/checkout` uses default depth and $BASE often isn't local.
+          git fetch --no-tags --depth=1 origin "$BASE" "$HEAD"
+          SKILLS_CHANGED=$(git diff --name-only "$BASE" "$HEAD" -- \
+            'packages/boxel-cli/plugin/skills/boxel-development/**' \
+            'packages/boxel-cli/plugin/skills/boxel-design/**')
+          if [ -z "$SKILLS_CHANGED" ]; then
+            echo "No boxel-skills-derived changes detected; skipping version-bump check."
+            exit 0
+          fi
+          if ! git diff "$BASE" "$HEAD" -- packages/boxel-cli/plugin/.claude-plugin/plugin.json \
+            | grep -qE '^[+-]\s*"version"'; then
+            echo "::error::boxel-skills-derived content changed but plugin.json version was not bumped. Marketplace consumers won't see the update without a new version. Bump 'version' in packages/boxel-cli/plugin/.claude-plugin/plugin.json."
+            exit 1
+          fi
+          echo "boxel-skills content changed and plugin.json version was bumped — OK."
+        working-directory: .

.github/workflows/manual-deploy.yml

@@ -37,7 +37,7 @@ jobs:
             echo "environment_url=" >> "$GITHUB_OUTPUT"
           fi
       - id: create
-        uses: actions/github-script@v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const environment = '${{ inputs.environment }}';
@@ -54,7 +54,7 @@ jobs:
             });
             core.setOutput('deployment_id', response.data.id.toString());
       - name: Mark deployment in progress
-        uses: actions/github-script@v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             const deployment_id = Number('${{ steps.create.outputs.deployment_id }}');
@@ -360,7 +360,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Set deployment status
-        uses: actions/github-script@v7
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env:
           NEEDS: ${{ toJson(needs) }}
           DEPLOYMENT_ID: ${{ needs.create-deployment.outputs.deployment-id }}

.github/workflows/observability-diff.yml

@@ -165,10 +165,10 @@ jobs:
           echo "::endgroup::"
 
       - name: Post sticky PR comment
-        # Pinned to SHA (rather than @v7) because this step has
+        # Pinned to SHA (rather than @v9) because this step has
         # pull-requests: write and runs after assuming an AWS role —
         # supply-chain risk is non-negligible.
-        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env:
           DIFF_FILE: ${{ steps.diff.outputs.diff_file }}
         with:

.mise.toml

@@ -1,6 +1,6 @@
 [tools]
 node = "24.13.1"
-pnpm = "10.30.0"
+pnpm = "10.33.4"
 
 [env]
 _.source = "./mise-tasks/lib/env-vars.sh"

README.md

@@ -158,7 +158,8 @@ This sets the following defaults (all individually overridable):
 | Variable                     | Normal | Turbo |
 | ---------------------------- | ------ | ----- |
 | `PRERENDER_COUNT`            | 1      | 3     |
-| `PRERENDER_PAGE_POOL_SIZE`   | 4      | 4     |
+| `PRERENDER_PAGE_POOL_MIN`    | 4      | 4     |
+| `PRERENDER_PAGE_POOL_MAX`    | 4      | 4     |
 | `WORKER_HIGH_PRIORITY_COUNT` | 0      | 4     |
 | `WORKER_ALL_PRIORITY_COUNT`  | 1      | 4     |
 
@@ -221,7 +222,7 @@ In environment mode, this is at `http://worker.environment-name.localhost/_index
 Boxel supports server-side rendering of cards via a lightweight prerender service and an optional manager that coordinates multiple services.
 
 - Prerender server: Handles POST `/prerender-card` (cards) and `/prerender-module` (modules) requests that include user/session permissions and a target URL. It launches a headless browser and maintains a small pool of per-realm pages (LRU-evicted) to speed up subsequent renders. Each page keeps a logged-in session for its realm and reuses the page for repeated renders of that realm.
-- Pooling: Each prerender server maintains up to PRERENDER_PAGE_POOL_SIZE pages (default 4). When the pool is full, the least-recently-used realm is evicted (its browser context is closed). When a page becomes unusable (timeout or explicit unusable signal), the realm is evicted proactively.
+- Pooling: Each prerender server maintains a dynamic page pool sized between `PRERENDER_PAGE_POOL_MIN` and `PRERENDER_PAGE_POOL_MAX` (both default 4 in dev). When the pool is full, the least-recently-used realm is evicted (its browser context is closed). When a page becomes unusable (timeout or explicit unusable signal), the realm is evicted proactively.
 - Prerender manager: When multiple prerender servers are running, a central manager receives `/prerender-card` and `/prerender-module` requests and routes them to a suitable server. The manager tracks which servers are registered and which realms they actively handle. It supports realm affinity, multiplexing the same realm across multiple servers to handle high prerender throughput, capacity-aware selection, and health-based eviction of unreachable servers.
 
 #### Pre-rendering start scripts
@@ -249,8 +250,9 @@ Prerender server:
 - BOXEL_HOST_URL (optional): URL of the host app that serves the /render routes. Defaults to http://localhost:4200 in dev scripts.
 - PRERENDER_MANAGER_URL (optional): Base URL of the prerender manager to register with. Defaults to http://localhost:4222.
 - PRERENDER_COUNT (optional): Number of prerender server instances to start. Each gets its own headless Chrome. Default 1.
-- PRERENDER_PAGE_POOL_SIZE (optional): Max number of per-realm pages to keep open in the pool. Default 4.
-- PRERENDER_AFFINITY_TAB_MAX (optional): Max number of tabs a single realm can use within a prerender server. Defaults to PRERENDER_PAGE_POOL_SIZE (i.e. a realm can use all available tabs).
+- PRERENDER_PAGE_POOL_MIN (optional): Idle floor for the dynamic page pool. The pool boots at this size and contracts back to it after sustained idle. Default 4 in dev (set in `mise-tasks/lib/env-vars.sh`).
+- PRERENDER_PAGE_POOL_MAX (optional): Burst ceiling for the dynamic page pool. The pool expands up to this size under saturation. Default 4 in dev. Setting MIN === MAX disables expansion/contraction (fixed-size pool).
+- PRERENDER_AFFINITY_TAB_MAX (optional): Max number of tabs a single realm can use within a prerender server. Defaults to 5, clamped to the effective pool max (`PRERENDER_PAGE_POOL_MAX` when set, otherwise the fixed `maxPages` pool size).
 - BOXEL_SHOW_PRERENDER (optional): If set to 'true', opens a visible browser (useful for debugging locally). Headless otherwise.
 
 Prerender manager:

docs/aws-operations.md

@@ -14,7 +14,7 @@ Conventions used throughout:
 
 ## Activate the dynamic-pool prerender server
 
-Flips the boxel prerender server's `PagePool` from legacy fixed-size capacity (driven by `PRERENDER_PAGE_POOL_SIZE`) to the dynamic-pool envelope (driven by `MIN` / `MAX` / `HIGH_PRIORITY_MAX`). Use this once the dynamic-pool code is deployed and you're ready to activate the new behaviour on a deployed environment.
+Sets the boxel prerender server's `PagePool` envelope (`MIN` / `MAX` / `HIGH_PRIORITY_MAX`). Use this when first activating dynamic-pool behaviour on a deployed environment, or when re-tuning the envelope after a workload shift.
 
 ### Pre-requisites
 
@@ -98,24 +98,21 @@ If the ECS task is still 4 vCPU / 8 GB, the recommended values would OOM at `HP_
 
 ### Rollback
 
-Restoring legacy fixed-pool behaviour without a code change:
+Restore the previous envelope values via SSM, then force-redeploy. Capture the pre-change values before applying new ones so rollback is a single `put-parameter` per knob — there is no longer a "fall back to a different env var" escape hatch, so the rollback target must be a known-good envelope.
 
 ```sh
-# Reset all dynamic-pool knobs to the SSM placeholder value "0"
-# (which the application code treats as "unset", falling back to
-# the legacy PRERENDER_PAGE_POOL_SIZE path).
-for name in PRERENDER_PAGE_POOL_MIN PRERENDER_PAGE_POOL_MAX \
-            PRERENDER_PAGE_POOL_HIGH_PRIORITY_MAX \
-            PRERENDER_HIGH_PRIORITY_THRESHOLD \
-            PRERENDER_POOL_IDLE_CONTRACTION_MS \
-            PRERENDER_SHARED_CONTEXT_CAP; do
-  aws --profile $PROFILE ssm put-parameter \
-    --name "/${ENV}/boxel/${name}" --value "0" --overwrite
-done
+# Example: restoring a previous envelope. Substitute the values you
+# captured before applying.
+aws --profile $PROFILE ssm put-parameter \
+  --name "/${ENV}/boxel/PRERENDER_PAGE_POOL_MIN" --value <prev-min> --overwrite
+aws --profile $PROFILE ssm put-parameter \
+  --name "/${ENV}/boxel/PRERENDER_PAGE_POOL_MAX" --value <prev-max> --overwrite
+# … repeat for PRERENDER_PAGE_POOL_HIGH_PRIORITY_MAX,
+# PRERENDER_HIGH_PRIORITY_THRESHOLD,
+# PRERENDER_POOL_IDLE_CONTRACTION_MS,
+# PRERENDER_SHARED_CONTEXT_CAP as needed.
 
 aws --profile $PROFILE ecs update-service \
   --cluster $ENV --service boxel-prerender-server-$ENV \
   --force-new-deployment
 ```
-
-The pool re-enters the legacy behaviour driven by `PRERENDER_PAGE_POOL_SIZE` once the rollout finishes.

mise-tasks/dev

@@ -13,13 +13,18 @@
 set -m
 
 cleanup() {
-  trap - EXIT INT TERM
+  trap - EXIT INT TERM HUP
   if [ -n "${SAT_PID:-}" ]; then
     kill_tree "$SAT_PID"
   fi
   sweep_orphaned_services
 }
-trap cleanup EXIT INT TERM
+# HUP is required: when the user hits Ctrl-C in a terminal running `mise run
+# dev`, mise often exits without forwarding SIGINT to this bash script, and
+# bash then receives SIGHUP from the dying parent. Bash's default action on
+# an untrapped SIGHUP is to terminate *without* running the EXIT trap, so
+# without `HUP` here the cleanup never fires and the entire subtree leaks.
+trap cleanup EXIT INT TERM HUP
 
 WAIT_ON_TIMEOUT=7200000 NODE_NO_WARNINGS=1 start-server-and-test \
   'run-p -ln start:pg start:matrix start:smtp start:prerender-dev start:prerender-manager-dev start:worker-development start:development' \

mise-tasks/dev-all

@@ -18,14 +18,19 @@ set -m
 pnpm --filter @cardstack/host start &
 HOST_PID=$!
 cleanup() {
-  trap - EXIT INT TERM
+  trap - EXIT INT TERM HUP
   if [ -n "${SAT_PID:-}" ]; then
     kill_tree "$SAT_PID"
   fi
   kill_tree "$HOST_PID"
   sweep_orphaned_services
 }
-trap cleanup EXIT INT TERM
+# HUP is required: when the user hits Ctrl-C in a terminal running `mise run
+# dev-all`, mise often exits without forwarding SIGINT to this bash script,
+# and bash then receives SIGHUP from the dying parent. Bash's default action
+# on an untrapped SIGHUP is to terminate *without* running the EXIT trap, so
+# without `HUP` here the cleanup never fires and the entire subtree leaks.
+trap cleanup EXIT INT TERM HUP
 
 HOST_TIMEOUT=120
 ELAPSED=0