Let plugins seed native New thread environments and worktrees

[tobi]

Human comments

What was wrong

PluginSidebarThreadActions.openNewThread() can select a project, reuse an environment, or select a machine, but cannot select a fresh worktree with a base branch or pass environment-provider inputs. Plugins such as Bots Sidebar therefore need an embedded composer to supply defaults that BB's native New thread screen already knows how to submit.

What changed

Add experimental_environment using NewThreadRequest's environment shape:

actions.openNewThread({
  projectId,
  experimental_environment: {
    type: "host",
    hostId,
    workspace: {
      type: "managed-worktree",
      baseBranch: { kind: "named", name: "main" },
    },
  },
  focusPrompt: true,
});

The native composer waits for its catalogs, applies the seed once per navigation, and keeps all pickers editable. Existing environmentId takes precedence, followed by the full environment seed, then hostId. The action validates before changing the project or navigating; route state is validated independently. Host seeds require an explicit machine, including personal workspaces. The shared composer owns seed application. Provider inputs are scoped to the environment seed so a repeated opening cannot inherit stale branch overrides, while model-default changes preserve branch edits.

Update the Plugin Guide and API audit inventory. This is a selection API, not a plugin submission callback or bot-binding mechanism. No server/daemon wire change or protocol bump; bb.sdk.threads.spawn and bb thread spawn --project ... --machine ... --new-environment worktree --base-branch ... already support the underlying creation request.

How you verified

• pnpm exec turbo run typecheck --filter=@bb/app --filter=@get-bb/plugin-sdk --filter=bb-plugin-plugin-api-docs passed.
• App tests passed: 208 tests across plugin-sidebar-hooks, RootComposeView, PluginNewThreadComposer, new-thread-environment-seed, and useThreadCreationOptions, run through Turbo.
• SDK app-harness tests passed: 55 tests, run through Turbo.
• Plugin Guide surface tests passed: 13 tests, run through Turbo.
• Added coverage for actual native-composer submission of fresh remote worktrees (host shorthand and provider forms), branch inputs, environment reuse, late catalog loading, repeated identical opens, picker overrides, project changes, later host-only navigation, default resets, precedence, malformed seeds, failed-creation retries, unavailable-machine reconciliation, and branch-edit retention when model defaults change. Native seed lifecycle tests run under React StrictMode.
• Confirmed the branch-edit/model-default regression test fails when the previous input scope is restored; the passing implementation was restored byte-for-byte afterward.
• No live BB deployment or manual mobile-device check was performed.

AGENT GENERATED

[github-actions]

Thanks @tobi for the PR. This repo needs approval before a PR. Join the #contributors channel in Discord (https://discord.gg/kvBU6tJhcJ) and explain what you want to open a PR for and why. A maintainer then adds you to the allow list. This PR now closes on its own. Reopen it or open a new one after approval.