Support .worktreeinclude files for new worktrees by SawyerHood · Pull Request #1029 · get-bb/bb

SawyerHood · 2026-08-05T19:58:46Z

Summary

A new worktree checks out tracked files only, so a local .env or a credentials directory stays behind in the source checkout. Today the only escape hatch is to hand-write the copy inside .bb-env-setup.sh.

This adds a repo-root .worktreeinclude file that lists what a worktree needs, matching the semantics Claude Code already ships:

.env
.env.*
!.env.example
certs/

bb copies every matching untracked file from the source checkout after git worktree add and before .bb-env-setup.sh, so the setup script can read the copied files.

Implementation

packages/host-workspace/src/worktree-include.ts — copyWorktreeIncludeFiles. Matching runs through git ls-files --others --ignored --exclude-from=.worktreeinclude -z. Passing the include file as the only exclude source makes git's own matcher decide every pattern, so directory patterns, **, and ! negation behave exactly as in .gitignore — and the feature needs no new dependency.
packages/host-workspace/src/provisioning.ts — copyIncludedFiles runs inside createWorktree and writes each copy and each skip into the provisioning transcript.
Files only. bb skips a symlinked source instead of copying its target, and refuses any destination that leaves the worktree through a committed symlink.
Nothing here fails provisioning. A pattern that matches nothing, an unreadable file, or a failed copy is reported and the thread still starts.

Two deliberate differences from Claude Code: bb accepts any untracked file rather than only gitignored ones, because listing a path is already explicit intent; and bb reports into the provisioning transcript instead of a debug log, so the result is visible in the app.

Tests

6 new tests in packages/host-workspace/test/worktree-include.test.ts cover pattern matching, ! negation, symlink refusal, comment-only files, ordering against the setup script, and the missing-file case.

pnpm exec turbo run test --filter=@bb/host-workspace --force — 178 passed
pnpm exec turbo run typecheck --filter=@bb/domain --filter=@bb/host-workspace --filter=@bb/templates --filter=@bb/server — passed

Docs

docs/worktrees.md, docs/platform-support.md, the bb guide environments template (regenerated), and the bb-cli skill.

Notes

No HOST_DAEMON_PROTOCOL_VERSION bump: this adds no field to any session payload, WebSocket message, or host RPC command.

Large directories such as node_modules are copied file by file, which is slow. The docs point users at .bb-env-setup.sh for dependency installation instead.

🤖 Generated with Claude Code

A new worktree checks out tracked files only, so a local .env or a credentials directory stays behind in the source checkout. Add a repo-root .worktreeinclude file that lists what a worktree needs. It uses gitignore pattern syntax. bb copies every matching untracked file from the source checkout after `git worktree add` and before .bb-env-setup.sh, so the setup script can read the copied files. Matching runs through `git ls-files --others --ignored --exclude-from`, which makes git's own matcher decide every pattern. Directory patterns, `**`, and `!` negation behave exactly as they do in .gitignore, and the feature needs no new dependency. bb copies files only. It skips symlinks rather than copying their targets, and it refuses any destination that leaves the worktree through a committed symlink. No failure here fails provisioning: each copy and each skip goes to the thread's provisioning transcript. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

SawyerHood · 2026-08-05T20:02:03Z

🚨 SLOP COP 🚨 · review

I am the SlopCop. I am reviewing this pull request under the review rule.

Stack: PR #1029 only. The second stack check found no later pull request. I skipped no pull requests.

I will run security, code quality, architecture, performance, and end-to-end checks.

SawyerHood · 2026-08-05T20:06:49Z

🚨 SLOP COP 🚨 · review

Security review completed.

The review found a high-impact destination symlink defect at packages/host-workspace/src/worktree-include.ts:136. The real createWorktree path followed a tracked destination symlink and wrote the copied secret outside the worktree.

The same copy step can replace a tracked destination file when the source checkout and target base branch differ. I will include the exact fix and evidence in the final review.

SawyerHood · 2026-08-05T20:07:09Z

🚨 SLOP COP 🚨 · review

Performance review completed.

The matcher runs git ls-files without a pathspec. It walks the complete untracked tree for every new worktree, even when the include file names one small file. A 3.3 GB checkout produced 109,768 candidate paths and took 0.48–0.87 seconds with a warm cache.

Large result sets also create unbounded transcript text and can exceed the existing 16 MB Git output buffer. I will include the actionable performance finding in the final review.

SawyerHood · 2026-08-05T20:09:30Z

🚨 SLOP COP 🚨 · review

Code-quality and architecture review completed.

The review confirmed the destination symlink and tracked-file overwrite defect. It also found three contract gaps: Git listing failures become a false zero-copy success, transcript output has no size limit, and cancellation does not stop the file-copy loop.

The repository scan found no substantial duplicate implementation. The new helper is the correct ownership boundary, but it needs the safety and failure controls above.

SawyerHood · 2026-08-05T20:09:49Z

🚨 SLOP COP 🚨 · review

End-to-end review completed.

This change has no browser route, so a dev-browser test cannot exercise it. I tested the real host boundary instead.

Turbo ran the @bb/host-workspace test and typecheck tasks. All 178 tests passed, including the six worktree-include tests. The integration test created a real Git worktree and verified that the setup script received the copied file.

A separate real createWorktree fixture reproduced the destination symlink escape. The passing suite does not cover that target-side case.

SawyerHood · 2026-08-05T20:10:53Z

+
+  const copied: string[] = [];
+  const skipped: string[] = [];
+  for (const relativePath of relativePaths) {


🚨 slopcop/review — P2: Stop the copy loop after cancellation

The abort signal controls the Git command only. A large copy continues after cancellation, and cleanup later deletes all copied data.

Check the signal during each loop step. Throw the existing provision_cancelled error so the caller keeps the correct behavior.

SawyerHood · 2026-08-05T20:10:53Z

+    { cwd: sourcePath, allowFailure: true, signal },
+  );
+  if (result.exitCode !== 0) {
+    return [];


🚨 slopcop/review — P2: Report Git listing failures

This return converts every Git error into a false zero-match result. It also hides the existing 16 MB output-buffer error.

Provisioning then reports a successful zero-file copy. Throw the error or return a clear skip reason with the Git error text.

The read helper also hides non-ENOENT file errors at line 47. Report those errors as the documentation promises.

SawyerHood · 2026-08-05T20:10:53Z

+  sourcePath: string,
+  signal: AbortSignal | undefined,
+): Promise<string[]> {
+  const result = await runGit(


🚨 slopcop/review — P2: Avoid the full untracked-tree scan for narrow patterns

This command has no pathspec. It walks the complete untracked tree before it returns one narrow match.

A 3.3 GB checkout had 109,768 paths. The warm scan took 0.48–0.87 seconds, compared with 0.023 seconds for a pathspec scan.

Use safe pathspec pruning for patterns that permit it. Add a time limit for the remaining full scans.

Not taking this one. The measured cost is 0.48–0.87s warm on a 3.3 GB checkout, and it is paid once, only when the repo actually commits a .worktreeinclude, inside an operation that already runs git worktree add over the same tree and then usually a dependency install. Against that baseline the scan is not the bottleneck.

Safe pathspec pruning is also narrower than it looks. A pattern only yields a usable path prefix when it is anchored to a directory segment. The dominant real-world config is .env, which is unanchored and matches at any depth, so it prunes to nothing — the optimization would miss exactly the case it is meant to help while adding a second matching path that can disagree with git's matcher. Handing every pattern to git ls-files --exclude-from is what makes the semantics correct by construction, and I would rather not trade that for a speedup that does not apply to the common case.

A time limit would change a slow copy into a silent partial copy, which is worse than slow for something that provisions secrets.

The other five findings are fixed in 5ccf703.

SawyerHood · 2026-08-05T20:10:53Z

+    emitOutput(
+      args.onProgress,
+      "worktree-include",
+      `Copied ${result.copied.length} file(s): ${result.copied.join(", ")}`,


🚨 slopcop/review — P2: Limit transcript path lists

A broad pattern can put thousands of paths in this one entry. The skipped-path loop also emits one entry for each file.

The daemon keeps and sends the full transcript. Limit each list, show the first paths, and report the remaining count.

SawyerHood · 2026-08-05T20:10:53Z

      keySuffix: "target",
      cwd: args.targetPath,
    });
+    await copyIncludedFiles({


🚨 slopcop/review — P1: Increase the host daemon protocol version

This behavior runs in the host daemon. An old enrolled daemon stays connected at protocol version 71 and silently omits this copy step.

The new transcript entries also cross the daemon connection. Increase HOST_DAEMON_PROTOCOL_VERSION and update its contract test.

SawyerHood · 2026-08-05T20:10:53Z

+        skipped.push(`${relativePath}: destination escapes the worktree`);
+        continue;
+      }
+      await fs.copyFile(sourceFile, targetFile);


🚨 slopcop/review — P1: Do not follow an existing destination symlink

The parent check does not validate targetFile. fs.copyFile follows a destination symlink and writes outside the worktree.

I reproduced this through createWorktree with a tracked symlink on the base branch. It replaced a host file with the copied secret.

The same call replaces an existing tracked regular file. The documentation promises that bb never does this.

Use an exclusive or no-follow destination open. Skip every destination that exists, and add a target-side symlink test.

SawyerHood

🚨 SLOP COP 🚨 · review

Review result: I found two P1 defects and four P2 defects.

Stack: PR #1029 only. I skipped no pull requests.

P1 findings:

The copy follows a tracked destination symlink. A real createWorktree test wrote a copied secret outside the worktree.
The change does not increase HOST_DAEMON_PROTOCOL_VERSION. Old enrolled daemons stay connected and silently omit the feature.

P2 findings:

Git listing and pattern-file read errors become false zero-match results.
Cancellation does not stop the file-copy loop.
Transcript path output has no size limit.
Narrow patterns still scan the complete untracked tree.

The repository scan found no substantial duplicate implementation. The helper has the correct package owner.

Turbo test and typecheck tasks passed for @bb/host-workspace. All 178 tests passed.

The feature has no browser route. I tested the real Git worktree and setup-script path instead.

I used a comment-only review. I did not approve or request changes.

Two defects and three contract gaps from the review of #1029: - Never write through a destination that already exists. fs.copyFile followed a symlink tracked by the base branch and wrote the copied secret outside the worktree; it also replaced an existing tracked file, which the docs promised bb would not do. bb now skips any present destination, using lstat plus COPYFILE_EXCL to close the race. - Bump HOST_DAEMON_PROTOCOL_VERSION to 72. The copy step runs in the host daemon. An old daemon stays connected, skips the copy, and emits no such transcript entry, so a repo that lists its .env silently gets a worktree without it. - Stop the copy loop on cancellation instead of copying every remaining file and then deleting all of it during cleanup. - Report git ls-files failures and non-ENOENT include-file read errors rather than converting them into a false zero-match success. - Cap the paths named in one transcript entry. A broad pattern could put thousands of paths into the transcript the daemon keeps and forwards. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

SawyerHood commented Aug 5, 2026

View reviewed changes

SawyerHood merged commit da88763 into main Aug 5, 2026
10 checks passed

SawyerHood deleted the bb/support-worktreeinclude-files-thr_8s2p9ww2b9 branch August 5, 2026 20:21

Uh oh!

Conversation

SawyerHood commented Aug 5, 2026

Summary

Implementation

Tests

Docs

Notes

Uh oh!

SawyerHood commented Aug 5, 2026

Uh oh!

SawyerHood commented Aug 5, 2026

Uh oh!

SawyerHood commented Aug 5, 2026

Uh oh!

SawyerHood commented Aug 5, 2026

Uh oh!

SawyerHood commented Aug 5, 2026

Uh oh!

SawyerHood Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SawyerHood Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SawyerHood Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SawyerHood Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

SawyerHood Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SawyerHood Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SawyerHood Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SawyerHood left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

SawyerHood Aug 5, 2026 •

edited

Loading

SawyerHood Aug 5, 2026 •

edited

Loading

SawyerHood Aug 5, 2026 •

edited

Loading

SawyerHood Aug 5, 2026 •

edited

Loading

SawyerHood Aug 5, 2026 •

edited

Loading

SawyerHood Aug 5, 2026 •

edited

Loading