[2026-10-15] eagle: personal/projects/balda/execution-broker.md personal/projects/balda/setup.md work/projects/vscode-migration/tech-design-xcode-build-server.md work/projects/vscode-migration/xcode-build-server.md

work/projects/vscode-migration/tech-design-xcode-build-server.md

@@ -31,11 +31,10 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 
 **What a developer gets**
 - Completion, jump-to-definition, references and live errors for app, test and package code, on macOS or iOS. One platform is chosen per worktree and can be switched.
-- Tasks to build any scheme and run unit tests; errors and failed tests show in the Problems panel.
+- Tasks to build any scheme and run unit tests; errors and failed tests show in the Problems panel. launch.json/tasks.json aren‘t committed.
 - Debugging with breakpoints:
   - the macOS app, launched from the editor;
-  - the iOS app on a simulator, by running the app and then attaching.
-- **Shared with Xcode.** Builds and the index live in the worktree's usual Xcode DerivedData folder. Whatever Xcode built or indexed is ready in VS Code, and the other way round.
+  - the iOS app on a simulator: one launch builds, installs and starts the app, and attaches the debugger.
 - Optional background indexing of worktrees while no editor is open.
 
 **How it works**
@@ -43,13 +42,13 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 - Builds and tests go through `xcodebuild` with the same settings Xcode uses.
 - The build server is installed locally by a script that builds it from source at a pinned commit of our fork (see below).
 
-**The build server needed fixes.** On our workspace it gave no results in test files, broke on the DMG/App Store variants and took hours to index. Four small changes fix this (see Appendix), and a worktree now indexes in about 5 minutes. They're general improvements, so we'll offer them upstream. We don't depend on upstream accepting them: we fork the build server into a DuckDuckGo repository, keep our changes there and pull upstream changes manually after reviewing them.
+**The build server needed fixes.** On our workspace it gave no results in test files, broke on the DMG/App Store variants and took hours to index. Four small changes fix this (see Appendix), and a worktree now indexes in about 5 minutes. They're general improvements, so we'll open a PR for the upstream. We don't depend on upstream accepting them: we fork the build server into a DuckDuckGo repository, keep our changes there and pull upstream changes manually after reviewing them.
 
 **Steps**
 1. Fork sourcekit-xcode-bsp into a DuckDuckGo repository with our changes.
 2. Land the setup in the repository, plus a short README.
 3. Offer the changes upstream as PRs.
-4. A few early adopters on macOS and iOS try it for a couple of weeks; then we decide whether to announce it more widely.
+4. Document the setup in the [Apple Documentation](https://app.asana.com/1/137249556945/project/1202500774821704/list/1203980668089483) project and in the onboarding docs.
 
 ### Pros
 
@@ -57,14 +56,13 @@ Add an opt-in VS Code setup to the repository: a workspace file and a few script
 - **Same build as Xcode.** swift-build reads the projects, so per-configuration settings and dependencies, resources, macros and plugins behave like in Xcode.
 - **Nothing to maintain in the app code.** No lint rules or checks to keep the setup working.
 - **Both platforms**, so it doesn't add a gap between macOS and iOS.
-- **No cost for Xcode users**, and those who use both tools share one build and one index.
+- **No cost for Xcode users.** Builds and the index live in the worktree's usual Xcode DerivedData folder, so those who use both tools share one build and one index: whatever Xcode built or indexed is ready in VS Code, and the other way round.
 
 ### Cons
 
 - **A young third-party tool** (version 0.1.0, "early-stage" by its authors) that we fork and maintain ourselves.
 - **Some rough edges:**
   - one platform per worktree at a time;
-  - iOS debugging is two steps (run, then attach);
   - the first index of a new worktree takes ~5 minutes.
 - **Someone has to own it.** I will; the setup is small (a workspace file and ~6 scripts), and it's documented.
 - **Maintenance as Xcode, swift-build and the build server move.** Xcode updates or upstream changes can need updates to the fork or the setup. Mitigation: the people who use the setup do the updates, mostly with AI agents (the setup is small and has a README and tests). Xcode-only users and CI never depend on it.

work/projects/vscode-migration/xcode-build-server.md

@@ -23,7 +23,7 @@ An alternative to the [[projects/vscode-migration/tech-design-spm-browser-packag
 - `xcode_derived_data.py` — Xcode's DerivedData folder for the worktree (MD5 → 28 letters; honors a custom location).
 - `sourcekit-xcode-bsp.sh` — `argv` of buildServer.json. Editor's server stops a running background indexer and waits for it; the indexer's server refuses to start next to an editor's. Pid files in `.build/bsp/`, checked to be sourcekit processes.
 - `xcodebuild.sh <build|test> <scheme> [destination]` — Debug into Xcode's DerivedData with Xcode's settings (no `-derivedDataPath`: passing it changes build parameters and makes Xcode and VS Code rebuild after each other). `DDG_WORKTREE_CACHE=1`: `.build/xcodebuild` + shared CAS with `/^wt` `/^dd` maps. `.build/products` → products folder. xcbeautify + raw `path:line: error:` lines for failed tests.
-- `simulator.sh [--build-only|--no-build] [device]` — builds iOS Browser for a concrete simulator, installs, `simctl launch --wait-for-debugger`, pid to `.build/simulator.pid`.
+- `simulator.sh [--build-only|--no-build] [device]` — builds iOS Browser for a concrete simulator, installs, `simctl launch --wait-for-debugger`, writes `process attach --pid N` to `.build/simulator-attach.lldb`.
 - `index-in-background.py [--all] [--if-idle]` — headless indexing; `background-indexing.sh install` = launchd agent every 30 min.
 - `install-build-server.sh` + `sourcekit-xcode-bsp.patch` + `sourcekit-xcode-bsp.Package.resolved` — reproducible build of the patched BSP.
 
@@ -38,7 +38,7 @@ An alternative to the [[projects/vscode-migration/tech-design-spm-browser-packag
 7. **CAS doesn't help the language server** (prepare-for-index doesn't cache; cold vs warm the same).
 8. **Index shared with Xcode works:** with Xcode's DerivedData layout (index store = `Index.noindex/DataStore`, `INDEX_REGULAR_BUILD_*` = `Build/…`), units written by an xcodebuild build count as up to date: after building `macOS Browser`, indexing skipped all app files (2,150 files left vs 3,972). BSP prepares in `Index.noindex/SourceKitBuild` so it never shares a build DB with an open Xcode.
 9. **Xcode-compatible builds:** `xcodebuild` without `-derivedDataPath` and the wrapper don't rebuild after each other (no-op 26–31 s). With `-derivedDataPath` pointing to the same folder they do.
-10. **iOS simulator:** generic destination fails (`fix_libswiftWebkit_simulator.sh` needs `TARGET_DEVICE_OS_VERSION`) → build for a concrete simulator. Debugging: `simctl launch --wait-for-debugger` + lldb-dap attach by **pid** works (breakpoint in `AppDelegate`). lldb-dap with `attachCommands` or with `program` + pid never stops at breakpoints (CLI lldb does) → launch config uses `${command:pickProcess}` (newest first). VS Code substitutes variables before `preLaunchTask`, so run the task first.
+10. **iOS simulator:** generic destination fails (`fix_libswiftWebkit_simulator.sh` needs `TARGET_DEVICE_OS_VERSION`) → build for a concrete simulator. Debugging in one launch: `preLaunchTask` runs `simulator.sh` (launch `--wait-for-debugger`, writes the attach command), the config attaches with `attachCommands: command source .build/simulator-attach.lldb` (read at attach time, after the task). Earlier failures of `attachCommands`/`program` were caused by the wrong `sourceMap` (10a), not by lldb-dap.
 10a. **Gray breakpoints in VS Code (macOS app):** the launch configs had `sourceMap` `/^wt → worktree` for all builds. lldb also applies it in reverse when setting breakpoints, so `<worktree>/…/File.swift` became `/^wt/…/File.swift`, which regular (Xcode-mode) debug info doesn't contain → "no locations". Fix: no `sourceMap`; `xcodebuild.sh` writes `.build/debug.lldbinit` per build (source map only for `DDG_WORKTREE_CACHE=1`), launch configs `command source` it in `initCommands`. Confirmed fixed in VS Code 2026-10-15.
 11. Index sharing between worktrees: rejected (absolute paths + mtime-based staleness).
 12. `workspace/_pollIndex` isn't in release sourcekit-lsp → indexer waits for "Indexing" progress end + 60 s quiet; gives up after 5 min without progress.