Plugins own where threads run.

1. Overview

Baseline is main at 06aeaa9949: three core-owned kinds, no environment-provider contract. This is the environment-provider half of the earlier PR #3194.

2. Reviewer’s map

Exact diff: git diff --shortstat origin/main..origin/bb/env-providers-1-environments in the PR worktree. Eleven commits on the requested main baseline; counts include source, tests, documentation, generated migration snapshot, and lockfile.

Reading order

1. packages/plugin-sdk/src/environment-provider.ts → public operations and cancellation/idempotency contract.
2. packages/domain/src/environment.ts and packages/db/drizzle/0113_environment_providers.sql → published model, intent conversion, backfill and status changes.
3. apps/server/src/services/environments/provider-orchestration.ts → launch/retry/cancel/remove ownership; then apps/server/src/services/threads/thread-environment-placement.ts and thread-environment-providers/default-policy.
4. plugins/environment-project-checkout/src, plugins/environment-git-worktree/src, plugins/environment-personal-workspace/src → concrete resource operations; packages/environment-provider-host/src → host primitives.
5. apps/app/src/components/pickers/EnvironmentPicker.tsx → eligibility and inputs; then composer, follow-up, Info and sidebar. Finish with SDK/CLI contracts and their regression tests.

Per-area lines of code

The regenerated 0113_snapshot.json alone adds 4,159 lines. Cross-package renames are charged to the destination area with Git’s rename-aware added/deleted counts; all rows sum to +33,293 / −16,614.

Deleted core paths and responsibilities

The daemon’s environment.provision/destroy operations and host-workspace provisioning responsibilities are removed or reduced inside surviving files. environment.attach inspects an already resolved path. The old cleanup/recovery, decoupling, branch-routing, and host-workspace provisioning tests are replaced by provider-oriented coverage; this is not deletion without replacement.

3. API and data model

Environment contract only. Registration is experimental; the type-only environment-provider entry point exports unprefixed types.

bb.experimental_environments.register({
  id: "git-worktree",
  displayName: "Worktree",
  requires: { gitCheckout: true },
  inputs: inputSchema,
  availability,
  validate,
  policy: { pathKeys: "per-thread", retireGraceMs: 300000 },
  create,
  remove
});

create({ inputs, pathKey, attempt, previous, report, signal, ...facts })
  → { status: "created", path, ownsPath, mergeBaseBranch?, resource? }
  | { status: "failed", failure: "transient" | "terminal", message }

remove({ environment, hostId, path, pathKey, resource, report, signal, attempt })
  → { status: "removed" } | { status: "failed", message }

{ type: "provider", environmentProviderId: "git-worktree",
  machine: { type: "existing", hostId },
  inputs: { branch: { kind: "default" } } }

Hooks in core

For any provider that successfully returns ownsPath: true, core runs the repo’s .bb-env-setup.sh in the created workspace before the thread starts, and .bb-env-teardown.sh before provider removal, including cleanup after setup fails. Ownership defaults to false; a claimed path or failed create alone never authorizes hooks. Attached paths skip both scripts, and missing scripts are skipped. Provider preparation finishes first, including Worktree’s .worktreeinclude copies.

The server orchestrates both hooks through the host daemon on the environment’s machine, with separate 15-minute timeouts. Steps and output appear in the existing provisioning transcript. Setup failure fails the launch; teardown script failure is reported but does not by itself prevent removal. An uncertain running hook does prevent cleanup: the workspace and claim remain reserved until the daemon confirms process-group termination, or confirms the operation never started.

Persisted hook identity lets restart recovery reconcile the original daemon operation instead of running setup twice. Durable daemon operation records and cancellation tombstones handle dropped requests, daemon restarts and delayed dispatch: a cancelled request cannot start later after cleanup. Worktree no longer invokes either hook itself, and the unused SDK exports experimental_killProcessGroup and experimental_supportsProcessGroups are removed.

Published API and composer surfaces

• bb.experimental_environments.register/recheck; sdk.environments.listProviders/list/get/delete; threads.list({ environmentId }).
• bb environment providers|list|show|delete; bb thread spawn --environment-provider --environment-inputs; bb thread list --environment. Inputs without a provider are rejected; unknown provider IDs fail at creation with available choices.
• app.slots.experimental_environmentProviderInputs returns ready value or blocked reason. Shared experimental_useBranches, experimental_useCheckoutState, and seven-prop experimental_BranchPicker support plugin-owned branch controls.
• Dispatch hooks expose environmentIntent as environment/provider; events include thread.unarchived and message.cancelled. Legacy path and create-request shorthand is normalized at the server boundary.

Migration 0113 and model

The latest migration dry run migrated a backup obtained through a read-only transaction; the source database was never opened for writing. 30/30 invariants passed with zero anomalies, including data preservation, provider and intent conversion, unchanged host schemas, false ownership default, the empty hook table, migration 0113 only, foreign keys, domain parsing and integrity. The temporary copy was deleted.

Provider inputs are persisted and readable by plugins, including after destruction; use non-secret inputs. Credentials belong in plugin settings. Private resource state stays outside public responses.

Primary code: packages/plugin-sdk/src/environment-provider.ts · packages/sdk/src/areas/environments.ts · packages/db/drizzle/0113_environment_providers.sql

4. Before / after screenshots

Supplied captures reused, not recaptured. PR 1 screenshots were captured at 3ecc3228fc, before the seven review rounds; screenshot labels retain that SHA. Rounds 5–7 change hook execution and recovery; the pictured UI is unchanged. Desktop main is 1280×800; PR 1 is mostly 1280×1000, with earlier composers at 1280×800. Compact Chromium is 390×844; iOS Safari has separate captures. This compares behavior/layout, not pixels. Compact/expanded changes report card size and notes, not application state.

Black rectangles remove identifying text; machine labels are replaced with HOST. Public fixture titles and functional labels remain. Click an image for its full-resolution PNG.

5. User-facing changes and decisions

Later decisions override intermediate #3194 proposals. The report uses the PR 1 body and captured surfaces to scope the plan’s CURRENT and Decisions log.

6. Bugs found and fixed during review

Applicable history from #3194, not newly observed defects in main. These are intermediate failures fixed or superseded by the extracted implementation. Machine-only Modal/SSH/suspend/checkpoint rounds are excluded. The fresh PR 1 review finished CLEAN at b738452cc6, with no remaining actionable findings. The final reviewer passed 40 server, 12 daemon, 52 migration and 3 recovery tests, including independent tombstone/recovery probes; one transient EPERM passed on retry.

Bugs found and fixed · seven PR-1 review rounds

• Round 1 · Concurrent checkout launches could mutate the same branch before attachment; durable host/path claims now precede mutation, directory switching reuses same-project environments, independent cleanup sweeps avoid stalled resources blocking others, scoped requires filtering omits ineligible rows, and unshipped machine-provider documentation claims are removed.
• Round 2 · Reuse, directory switching or restored dispatch could bypass claims, aliases could evade exclusion, and failed-launch cleanup could delete a newer workspace; canonical claims now guard every admission and remain held through failed-launch cleanup.
• Round 3 · Attachment could lose canonical identity and allow alias-based branch changes beneath a live thread; the environment row now persists the canonical key for every attached-path comparison, and claim_path is folded into the single migration 0113.
• Round 4 · One inaccessible or symlink-loop legacy path could block healthy listings and launches; backfill now isolates each row, retries unresolved keys and conservatively refuses unresolved equal/prefix conflicts.
• Round 5 · Hooks tied to Worktree could be skipped by other owned-path providers; core now runs setup after successful owned creation and teardown before removal.
• Round 6 · Failed creation could run teardown in the original checkout, a lost setup RPC could let cleanup remove a workspace under a running script, and restart recovery could run setup twice; false ownership defaults, persisted hook identity and daemon-confirmed termination close those gaps.
• Round 7 · Unknown operation IDs could block cleanup forever and delayed requests could run after cancellation; durable daemon records and cancellation tombstones resolve both, while folding the hook schema into 0113 avoids colliding with PR 2’s migration slot.

Verification supplied with rounds 5–7

The final worker report records 95/95 typecheck/lint tasks, 3,967 app tests, 2,320 server tests, 57 integration tests, 445 DB tests and 575 daemon tests passing; the remaining-package sweep passed 85/85 tasks with capped workers. Live checks covered owned-workspace setup/removal, checkout retention, a server restart during setup, dropped dispatch with claim retention and release, rejection of delayed dispatch, and daemon-crash process-group recovery. These are supplied verification results, not suites rerun for this report update.

Verification supplied with PR 1 · original capture revision

History: #3194 review rounds, plan Decisions/Rounds logs, and supplied pr1-report.md and surface-report.md. Raw private evidence is not published.

7. Breaking changes and known issues

Compatibility limits and rollout constraints for this eleven-commit PR.

8. Deferred follow-ups

The split plan is future scope, not a claim that those implementations ship in #3227.