[danielmlr]

What does this PR do?

Names the cause when a configured sandbox runner cannot run plugins. isAvailable() answers only true or false, so a missing worker_loaders binding, a missing PluginBridge export and a workerd binary that does not run all produce the same startup warning and the same SANDBOX_NOT_AVAILABLE refusal.

SandboxRunner gets the optional unavailableReason() the workerd runner already had. The Cloudflare and workerd runners report their cause, and the warning and the four install and update refusals append it after a colon. Runners without the method keep today's text: the noop runner, whose "Sandbox runner is required" already names what is missing, and the Miniflare dev runner, which the factory returns only once Miniflare resolves. The sandbox guide maps each reason to its fix.

Part of #1686 and #1680.

Type of change

• Bug fix
• Feature (requires maintainer-approved Discussion)
• Refactor (no behavior change)
• Translation
• Documentation
• Performance improvement
• Tests
• Chore (dependencies, CI, tooling)

Checklist

• I have read CONTRIBUTING.md
• pnpm typecheck passes
• pnpm lint passes
• pnpm test passes (or targeted tests for my change) (the emdash, @emdash-cms/cloudflare and @emdash-cms/sandbox-workerd suites)
• pnpm format has been run
• I have added/updated tests for my changes (if applicable)
• User-visible strings in the admin UI are wrapped for translation (if applicable). Do not include messages.po changes except in translation PRs — a workflow extracts catalogs on merge to main. (n/a: server-side error and log text, no admin UI strings)
• I have added and reviewed the user-facing changeset (if this PR changes a published package)
• New features link to an approved Discussion: https://github.com/emdash-cms/emdash/discussions/... (n/a: part of Improve diagnostics for missing bindings and sandbox requirements #1686 and Document and harden plugin sandbox operations for Cloudflare and Node #1680 on the 1.0 milestone; requested in Document and harden plugin sandbox operations for Cloudflare and Node #1680 (comment))
• I have included screenshots below if this PR changes the UI (n/a: no UI change)

AI-generated code disclosure

• This PR includes AI-generated code — model/tool: Claude Opus 5

Screenshots / test output

Not applicable for screenshots. These new tests failed before the change:

 × marketplace install appends the reason the runner gives
 × marketplace update appends the reason the runner gives
 × registry install appends the reason the runner gives
 × registry update appends the reason the runner gives
 × names the reason the runner gives in the startup warning
 × names the Worker Loader binding when it is missing
 × names the PluginBridge export when it is missing
 × names both when both are missing
 × names the binary when it does not run

AssertionError: expected 'Sandbox runner is required for market…' to match
  /: the worker has no worker_loaders bi…/
TypeError: runner.unavailableReason is not a function
AssertionError: expected 'workerd is not running' to contain 'binary'

With the change:

pnpm --filter emdash test                        542 files, 6516 tests passed, 10 skipped
pnpm --filter @emdash-cms/cloudflare test         38 files, 422 tests passed, 2 skipped
pnpm --filter @emdash-cms/sandbox-workerd test    14 files, 92 tests passed

pnpm typecheck, pnpm lint, pnpm format and the docs build are clean. pnpm test:e2e was not run.

[changeset-bot]

🦋 Changeset detected

Latest commit: bcb9351

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 17 packages

Name	Type
emdash	Minor
@emdash-cms/cloudflare	Minor
@emdash-cms/sandbox-workerd	Patch
@emdash-cms/fixture-perf-site	Patch
@emdash-cms/perf-demo-site	Patch
@emdash-cms/cache-demo-site	Patch
@emdash-cms/do-demo-site	Patch
@emdash-cms/do-solo-demo-site	Patch
@emdash-cms/admin	Minor
@emdash-cms/auth	Minor
@emdash-cms/blocks	Minor
create-emdash	Minor
@emdash-cms/gutenberg-to-portable-text	Minor
@emdash-cms/x402	Minor
@emdash-cms/auth-atproto	Patch
@emdash-cms/release-service	Patch
@emdash-cms/plugin-embeds	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

PR template validation failed

Please fix the following issues by editing your PR description:

• Feature PRs require a link to an approved Discussion (https://github.com/emdash-cms/emdash/discussions/categories/ideas). Open a Discussion first, get approval, then link it in the PR.

See CONTRIBUTING.md for the full contribution policy.

[pkg-pr-new]

Open in StackBlitz

@emdash-cms/admin

npm i https://pkg.pr.new/@emdash-cms/admin@3041

@emdash-cms/auth

npm i https://pkg.pr.new/@emdash-cms/auth@3041

@emdash-cms/auth-atproto

npm i https://pkg.pr.new/@emdash-cms/auth-atproto@3041

@emdash-cms/blocks

npm i https://pkg.pr.new/@emdash-cms/blocks@3041

@emdash-cms/cloudflare

npm i https://pkg.pr.new/@emdash-cms/cloudflare@3041

@emdash-cms/contentful-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/contentful-to-portable-text@3041

emdash

npm i https://pkg.pr.new/emdash@3041

create-emdash

npm i https://pkg.pr.new/create-emdash@3041

@emdash-cms/gutenberg-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/gutenberg-to-portable-text@3041

@emdash-cms/plugin-cli

npm i https://pkg.pr.new/@emdash-cms/plugin-cli@3041

@emdash-cms/plugin-types

npm i https://pkg.pr.new/@emdash-cms/plugin-types@3041

@emdash-cms/registry-client

npm i https://pkg.pr.new/@emdash-cms/registry-client@3041

@emdash-cms/registry-lexicons

npm i https://pkg.pr.new/@emdash-cms/registry-lexicons@3041

@emdash-cms/registry-moderation

npm i https://pkg.pr.new/@emdash-cms/registry-moderation@3041

@emdash-cms/registry-verification

npm i https://pkg.pr.new/@emdash-cms/registry-verification@3041

@emdash-cms/sandbox-workerd

npm i https://pkg.pr.new/@emdash-cms/sandbox-workerd@3041

@emdash-cms/x402

npm i https://pkg.pr.new/@emdash-cms/x402@3041

@emdash-cms/plugin-ai-moderation

npm i https://pkg.pr.new/@emdash-cms/plugin-ai-moderation@3041

@emdash-cms/plugin-atproto

npm i https://pkg.pr.new/@emdash-cms/plugin-atproto@3041

@emdash-cms/plugin-audit-log

npm i https://pkg.pr.new/@emdash-cms/plugin-audit-log@3041

@emdash-cms/plugin-color

npm i https://pkg.pr.new/@emdash-cms/plugin-color@3041

@emdash-cms/plugin-embeds

npm i https://pkg.pr.new/@emdash-cms/plugin-embeds@3041

@emdash-cms/plugin-field-kit

npm i https://pkg.pr.new/@emdash-cms/plugin-field-kit@3041

@emdash-cms/plugin-forms

npm i https://pkg.pr.new/@emdash-cms/plugin-forms@3041

@emdash-cms/plugin-webhook-notifier

npm i https://pkg.pr.new/@emdash-cms/plugin-webhook-notifier@3041

commit: bcb9351

[github-actions]

Overlapping PRs

This PR modifies files that are also changed by other open PRs:

• fix(workerd): bind bridge access to active plugin credentials #3051 (3 shared files)

This may cause merge conflicts or duplicated work. A maintainer will coordinate.

[emdashbot]

This is a well-scoped, backwards-compatible improvement. Adding an optional unavailableReason() to SandboxRunner and wiring it into the startup warning and the four SANDBOX_NOT_AVAILABLE refusal paths is the right-shaped fix for the issue described in #1680/#1686: today the same opaque message hides several distinct misconfigurations.

I read the full diff, the changed source files, the test files, the changeset, and the docs update. I also checked the existing MiniflareDevRunner and the three SandboxRunner implementations to confirm the optional method does not break third-party runners or the dev runner.

What I checked:

• Approach: the change is additive (optional interface method), keeps existing plain messages for runners that don't implement it, and is consistent across Cloudflare (worker_loaders binding / PluginBridge export) and Node.js (workerd binary check).
• API surface: withUnavailableReason correctly handles a null runner and a runner without unavailableReason; callers use the exact same SandboxRunner | null type they already had.
• Behavior: EmDashRuntime logs the reason when present and falls back to the prior workerd-specific guidance when absent; handlers append the reason for marketplace install/update and registry install/update.
• Tests: new tests pin the Cloudflare runner outputs, the workerd binary failure reason, all four refusal messages, and the startup warning. They exercise observable error messages, not implementation details.
• Docs: the plugin-sandbox troubleshooting section maps each new reason to its fix and matches the implementation.
• Changeset: follows .changeset/README.md — present tense, names the affected error/warning, proportional detail, no unnecessary headings.

I didn't find any logic bugs, regressions, AGENTS.md convention violations, or missing test coverage. The PR is ready to merge as-is.

[ascorbic]

Thanks!