Merge remote-tracking branch 'origin/main' into feat/bucket-mounting

Author: ghostwriternr

.changeset/loose-bats-cross.md

@@ -0,0 +1,5 @@
+---
+'@cloudflare/sandbox': patch
+---
+
+Update dependencies

.changeset/new-students-accept.md

@@ -0,0 +1,21 @@
+{
+  "extraKnownMarketplaces": {
+    "superpowers-marketplace": {
+      "source": {
+        "source": "github",
+        "repo": "obra/superpowers-marketplace"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "superpowers@superpowers-marketplace": true
+  },
+  "enabledMcpjsonServers": ["cloudflare-docs", "exa"],
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)",
+      "Bash(npm run typecheck:*)",
+      "Bash(npm run check:*)"
+    ]
+  }
+}

.claude/settings.json

@@ -10,15 +10,20 @@ on:
     #   - "src/**/*.js"
     #   - "src/**/*.jsx"
 
+concurrency:
+  group: claude-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   claude-review:
     # Skip review for automated "Version Packages" PRs created by changesets
     if: github.event.pull_request.title != 'Version Packages'
 
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      pull-requests: read
+      pull-requests: write
       issues: read
       id-token: write
 
@@ -33,6 +38,10 @@ jobs:
         uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          plugin_marketplaces: |
+            https://github.com/obra/superpowers-marketplace.git
+          plugins: |
+            superpowers@superpowers-marketplace
           prompt: |
             You are Claude reviewing PRs for the Cloudflare Sandbox SDK.
 
@@ -52,54 +61,101 @@ jobs:
 
             **Then review the diff with that context.**
 
-            ### 2. Check for Previous Review (if this is an update)
+            ### 2. Check for Previous Review (Internal Context Only)
 
-            **Detect if this is a PR update:**
-            - Check for existing claude[bot] comment: `gh pr view ${{ github.event.pull_request.number }} --json comments --jq '.comments[] | select(.author.login == "claude[bot]" or .author.login == "github-actions[bot]")'`
+            Check if you've reviewed this PR before:
+            ```bash
+            gh pr view ${{ github.event.pull_request.number }} --json comments --jq '.comments[] | select(.author.login == "claude[bot]" or .author.login == "github-actions[bot]")'
+            ```
 
-            **If previous review exists:**
-            - Identify what's new: `git log --oneline ${{ github.event.before }}..${{ github.event.after }}` (shows commits since last review)
-            - Check if history was rewritten: `git cat-file -t ${{ github.event.before }} 2>/dev/null` (if fails, force push occurred)
-            - Read the previous review to understand what was flagged
+            If previous review exists:
+            - Read it to understand what you said before
+            - Note what commits have been added since: `git log --oneline ${{ github.event.before }}..${{ github.event.after }}`
+            - Check if history was rewritten: `git cat-file -t ${{ github.event.before }} 2>/dev/null`
+            - Use this context internally when writing your review
 
-            **Your review should cover BOTH:**
-            1. **Incremental**: What changed since last review? Were previous issues addressed?
-            2. **Holistic**: How does the FULL PR look now? Any issues when viewing the complete picture?
+            **Don't announce "Update N" or link to previous reviews** - just write naturally.
 
             ### 3. Gather Context
             - Use `gh pr view ${{ github.event.pull_request.number }}` for PR description
             - Use `gh pr diff ${{ github.event.pull_request.number }}` for FULL diff (not just incremental)
             - Read CLAUDE.md for repo-specific conventions and architecture patterns
             - Use Read tool to examine key changed files
 
-            ### 4. Internal Analysis
+            ### 4. Check Documentation Impact
+            Use `mcp__cloudflare-docs__search_cloudflare_documentation` to check if this PR requires doc updates:
+            - Does it change existing documented behavior?
+            - Does it add new features needing documentation?
+            - Does it have security implications needing best practices docs?
+            - If yes, call out specific doc sections that need updates
+
+            ### 5. Internal Analysis
             Before writing your review, analyze inside <analysis> tags (do NOT include in final comment):
             a. What is this PR accomplishing?
             b. Which packages/layers are affected?
             c. Are there architectural or security implications?
             d. What tests are needed?
             e. Does this need documentation updates?
 
-            ### 5. Check Documentation Impact
-            Use `mcp__cloudflare-docs__search_cloudflare_documentation` to check if this PR requires doc updates:
-            - Does it change existing documented behavior?
-            - Does it add new features needing documentation?
-            - Does it have security implications needing best practices docs?
-            - If yes, call out specific doc sections that need updates
+            ### 6. Fetch Existing Review Threads
 
-            ### 6. Review Focus
+            Before creating your review, fetch existing Claude review threads to enable thread continuity:
 
-            **Prioritize** (things that slip through):
-            - Missing/inadequate tests (especially E2E for container interactions)
-            - Type safety violations (see CLAUDE.md TypeScript standards)
-            - Architecture violations (see CLAUDE.md patterns: client pattern, DI, layer separation)
-            - API design issues (see CLAUDE.md API Design: unclear naming, missing validation, poor error messages)
+            ```bash
+            # Get PR owner and repo name
+            OWNER=$(gh repo view --json owner --jq '.owner.login')
+            REPO=$(gh repo view --json name --jq '.name')
+
+            # Fetch all review threads
+            gh api graphql -f query='
+            query($owner: String!, $name: String!, $pr: Int!) {
+              repository(owner: $owner, name: $name) {
+                pullRequest(number: $pr) {
+                  reviewThreads(first: 100) {
+                    nodes {
+                      id
+                      isResolved
+                      path
+                      line
+                      comments(first: 10) {
+                        nodes {
+                          id
+                          databaseId
+                          body
+                          author { login }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }' -f owner="$OWNER" -f name="$REPO" -F pr=${{ github.event.pull_request.number }}
+            ```
 
-            **Skip**:
-            - Code style/formatting (Biome handles it)
-            - Changeset reminders (bot handles it)
+            **Parse the response** - structure is:
+            ```
+            .data.repository.pullRequest.reviewThreads.nodes[]
+            ```
+
+            Filter for threads where `comments.nodes[0].author.login` is "claude" or "github-actions[bot]". These are your previous review comments.
+
+            **Important notes:**
+            - `line` can be `null` for file-level comments (not line-specific)
+            - Use `id` (format: PRRT_xxx) for resolveReviewThread mutations
+            - Use `databaseId` (format: 2518555173) for comment replies
+
+            ### 7. Execute Review
 
-            ### 7. Post Review
+            Launch superpowers:code-reviewer subagent (Task tool) with the context gathered above:
+            - Full PR diff from step 3
+            - Relevant architecture patterns from CLAUDE.md
+            - Documentation requirements from step 4
+            - Previous review feedback (if incremental update from step 2)
+            - Existing review threads from step 6
+
+            The code-reviewer will analyze correctness, architecture, testing, and code quality.
+
+            ### 8. Post Review
 
             **Writing style**:
             - Be direct. One clear point per issue.
@@ -108,38 +164,75 @@ jobs:
             - If issues found: State the issue, reference location, explain why it matters. Move on.
 
             **Format**:
-            - Reference code with file paths and line numbers (e.g., `packages/sandbox/src/file.ts:123`)
-            - Use markdown headings (### for sections) only if you have multiple distinct categories
+            - **Inline comments**: Use for specific line-by-line code issues (file path, line number, comment)
+            - **Main comment**: Summary only - overall assessment, architectural concerns, testing strategy, verdict. Do NOT duplicate inline comments here.
+
+            **Main comment - write naturally:**
+            - Start with "## Claude Code Review"
+            - If previous review exists, write conversationally: "The encoding issue is fixed. Tests look better too."
+            - Mention what still needs work: "I still see the over-mocking in file-service.test.ts:45"
+            - New concerns: "New issue: error handling in container.ts doesn't cover..."
+            - Overall verdict: "Looks good" or "Needs fixes before merge"
+
+            **Handle existing threads before submitting new review:**
 
-            **For incremental reviews** (when updating existing comment):
-            - Acknowledge fixed issues: "✓ [Previous issue] - addressed"
-            - Flag new issues found in new changes
-            - Flag any issues that emerged from holistic view
-            - Keep unaddressed issues from previous review
+            For each thread from step 6, compare with your new findings:
+            - **Issue is fixed:** Mark for resolution (save thread ID)
+            - **Issue persists but needs update:** Mark for reply (save comment database ID)
+            - **Issue no longer relevant:** Mark for resolution
 
-            **Posting your review**:
+            **Submit review as a single cohesive unit:**
 
-            First, check for existing review comment:
+            1. Get the latest commit SHA:
             ```bash
-            COMMENT_ID=$(gh api repos/${{ github.repository }}/issues/${{ github.event.pull_request.number }}/comments \
-              --jq '.[] | select(.user.login == "claude[bot]") | select(.body | startswith("## Claude Code Review")) | .id' | head -1)
+            COMMIT_SHA=$(gh pr view ${{ github.event.pull_request.number }} --json headRefOid --jq '.headRefOid')
             ```
 
-            If COMMENT_ID exists (previous review comment found):
-            - Update it: `gh api repos/${{ github.repository }}/issues/comments/$COMMENT_ID -X PATCH -f body="YOUR_REVIEW_HERE"`
-            - Make sure your review starts with "## Claude Code Review" to maintain consistency
+            2. Create review.json with ONLY NEW issues (don't duplicate existing thread issues):
+            ```json
+            {
+              "body": "## Claude Code Review\n\nYour overall assessment here...",
+              "event": "COMMENT",
+              "commit_id": "COMMIT_SHA_HERE",
+              "comments": [
+                {
+                  "path": "path/to/file.ts",
+                  "line": 42,
+                  "body": "Your inline comment here"
+                }
+              ]
+            }
+            ```
+
+            3. Post the unified review:
+            ```bash
+            gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/reviews \
+              --method POST \
+              --input review.json
+            ```
 
-            If no existing comment:
-            - Create new: `gh pr comment ${{ github.event.pull_request.number }} --body "YOUR_REVIEW_HERE"`
-            - Start your review with "## Claude Code Review" header
+            4. **Manage existing threads (after review submission):**
 
-            For inline code issues:
-            - Use `mcp__github_inline_comment__create_inline_comment` to highlight specific code issues
+            Resolve fixed issues:
+            ```bash
+            gh api graphql -f query='
+            mutation($threadId: ID!) {
+              resolveReviewThread(input: {threadId: $threadId}) {
+                thread { id isResolved }
+              }
+            }' -f threadId="THREAD_ID_FROM_STEP_6"
+            ```
 
-            Important: Only post GitHub comments - don't submit review text as messages.
+            Reply to threads that need updates:
+            ```bash
+            gh api repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/comments/COMMENT_DATABASE_ID/replies \
+              --method POST \
+              -f body="Update: Issue has been partially addressed but..."
+            ```
 
-            Your goal: Catch real issues. Respect the developer's time - be concise, but don't omit important details.
+            **Important**: This workflow maintains conversation continuity - resolved issues show as "Resolved", ongoing issues have threaded replies, and only new issues create new comment threads.
 
+            Always post a NEW comment - never update previous ones. Natural conversation flow.
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
-          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment,mcp__cloudflare-docs__search_cloudflare_documentation,mcp__exa__get_code_context_exa,mcp__exa__web_search_exa,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh api:*)"'
+          claude_args: '--allowedTools "Task,Skill,Read,Glob,Grep,Write,TodoWrite,mcp__cloudflare-docs__search_cloudflare_documentation,mcp__exa__get_code_context_exa,mcp__exa__web_search_exa,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh repo view:*),Bash(gh api:*),Bash(git log:*),Bash(git cat-file:*),Bash(git rev-parse:*),Bash(jq:*)"'

.github/workflows/claude-code-review.yml

@@ -17,11 +17,12 @@ jobs:
       (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
       (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
       (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     permissions:
-      contents: read
-      pull-requests: read
-      issues: read
+      contents: write
+      pull-requests: write
+      issues: write
       id-token: write
       actions: read # Required for Claude to read CI results on PRs
     steps:
@@ -41,17 +42,60 @@ jobs:
           additional_permissions: |
             actions: read
 
-          # Custom prompt that ensures Claude reads CLAUDE.md first
           prompt: |
             REPO: ${{ github.repository }}
             ISSUE/PR: #${{ github.event.issue.number || github.event.pull_request.number }}
 
-            IMPORTANT: Before starting any work, read the CLAUDE.md file at the root of this repository. It contains critical project conventions, architecture patterns, and development guidelines that you must follow.
+            ## Task Context
 
-            After reading CLAUDE.md, proceed with the following task:
             ${{ github.event.comment.body || github.event.issue.body || github.event.review.body }}
 
-          # Optional: Add claude_args to customize behavior and configuration
+            ## Workflow Instructions
+
+            **STEP 1: Read project conventions**
+            Read CLAUDE.md at the root of this repository. It contains critical project conventions, architecture patterns, and development guidelines.
+
+            **STEP 2: Assess task complexity**
+            Determine if this task requires planning:
+            - **Needs planning**: New features, architectural changes, significant refactoring, adding major functionality
+            - **Direct execution**: Bug fixes, test fixes, investigations, documentation updates, simple one-line changes
+
+            **STEP 3: Execute appropriate workflow**
+
+            **For tasks needing planning:**
+            1. Use the brainstorming skill (`superpowers:brainstorming`) to:
+               - **IMPORTANT**: You are working autonomously (no user to answer questions)
+               - Use Socratic method on yourself: ask questions, explore answers, consider trade-offs
+               - The task context above contains all available information
+               - Explore 2-3 different approaches with pros/cons
+               - Design the solution covering: architecture, components, data flow, error handling, testing
+               - Save design to `${{ runner.temp }}/design.md` (temporary, not committed)
+
+            2. Use the writing-plans skill (`superpowers:writing-plans`) to:
+               - Create detailed, bite-sized implementation plan
+               - Include exact file paths, complete code examples, verification steps
+               - Save plan to `${{ runner.temp }}/implementation.md` (temporary, not committed)
+
+            3. Execute the complete implementation:
+               - Follow TDD for all code changes (write test first, watch fail, implement, verify pass)
+               - Complete the entire implementation
+               - Run all tests and verification steps
+               - **After completion**: Use requesting-code-review skill to review your own work
+               - Fix any issues found in self-review
+               - Commit changes following CLAUDE.md git guidelines
+
+            **For direct execution tasks:**
+            - Use test-driven-development for code changes
+            - Use systematic-debugging for investigations
+            - Use verification-before-completion before claiming done
+            - Follow CLAUDE.md conventions
+
+            **REMEMBER:**
+            - If a superpowers skill applies to your task, you MUST use it (not optional)
+            - Write tests before code (TDD iron law)
+            - Verify with evidence before claiming completion
+            - Create commits following CLAUDE.md git guidelines
+
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://docs.claude.com/en/docs/claude-code/cli-reference for available options
-          # claude_args: '--allowed-tools Bash(gh pr:*)'
+          claude_args: '--allowedTools "Task,Skill,Read,Write,Edit,Glob,Grep,TodoWrite,mcp__cloudflare-docs__search_cloudflare_documentation,mcp__exa__get_code_context_exa,mcp__exa__web_search_exa,Bash(npm test:*),Bash(npm run *),Bash(npm install:*),Bash(npm ls:*),Bash(npm view:*),Bash(docker:*),Bash(git status),Bash(git log:*),Bash(git diff:*),Bash(git rev-parse:*),Bash(git fetch:*),Bash(git add:*),Bash(git commit:*),Bash(git push:*),Bash(git branch:*),Bash(git checkout:*),Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh pr checks:*),Bash(gh pr create:*),Bash(gh issue view:*),Bash(gh issue create:*),Bash(gh issue comment:*),Bash(gh repo view:*),Bash(gh api:*),Bash(find:*),Bash(tree:*),Bash(ls:*),Bash(jq:*)"'

.github/workflows/claude.yml

@@ -12,8 +12,13 @@ on:
       - '!**/*.md'
       - '!.changeset/**'
 
+concurrency:
+  group: pkg-pr-new-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   publish-preview:
+    if: ${{ !contains(github.event.pull_request.title, 'Version Packages') }}
     runs-on: ubuntu-latest
     timeout-minutes: 30