Repository navigation
spec(FIX-1906): coding runs for mapped projects work in worktrees of your checkout #3177
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| # FIX-1906 · Business rules | ||
|
|
||
| [Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) | ||
|
|
||
| The cases, written as rules. Each says what a person or the system does and what happens. The | ||
| *proved by* column is the check the plan runs. Epic rules are cited as ER-n | ||
| ([FIX-1903](../../epics/FIX-1903/BUSINESS-RULES.md)); this issue owns ER-3 and ER-4. | ||
|
|
||
| ## Which projects get your checkout | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-1 | A run's project is shared, an entry names its id with the run's session's `orgId` (and `tenantId`, exactly: an entry without one matches only a session with none), and its row's repository equals the entry's `remote` | The source answers the checkout path, with the project's kept files and the mapping's `baseRef` | CI · goal leg a | | ||
| | BR-2 | A private project with the same id and remote as a mapped one runs | Not mapped: private projects never are. The source answers the row's remote, as today, and the host clones it or refuses it by its allowlist | CI · goal leg b | | ||
| | BR-21 | A shared project with the same id and remote runs in another organization, or another tenant, or in a session with no `orgId` | Not mapped, as BR-2. The organization is the session's server-set one, never anything on the task (BP-031) | CI · goal leg b, failing under `ignore-org` | | ||
| | BR-3 | A named project's row names a different remote, or none | Not mapped. Its remote goes the remote way; with none, the run works on its files alone, as today | CI | | ||
| | BR-4 | A project the mapping doesn't name has the mapped remote on its row | Not mapped (ER-13) | CI | | ||
| | BR-5 | The mapping names a checkout the host doesn't list in `localRepositories` | The host refuses the run as `invalid-remote` before any git process, naming the path. Never a clone, never a silent fallback | CI | | ||
| | BR-6 | The mapping is built with a relative checkout path, a remote a row couldn't store, or one project (organization, tenant and id) named twice | Refused when `projectWorkspace()` is called, naming the entry | CI | | ||
| | BR-7 | No `checkouts` option is given | Every answer is exactly today's | Existing suite | | ||
|
|
||
| ## The place and the branch | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-8 | A mapped run starts | Its place is `checkout/`, a worktree of the operator's checkout on the run's own branch, with `project/` beside it, never inside it. `git worktree list` in the checkout names it (ER-3) | CI · goal leg a | | ||
| | BR-9 | The mapping has no `baseRef` | The branch is cut from the checkout's `HEAD`, whatever it is checked out on. Nothing is fetched | CI | | ||
| | BR-10 | The mapping's `baseRef` names a branch the checkout doesn't have | The provision fails naming the ref; nothing is left behind | CI | | ||
| | BR-11 | The run writes in `project/` | Saved to `project-files/<projectId>/` and absent from `git status` in the worktree (FIX-1762 BR-28, BR-29) | CI · goal leg a | | ||
| | BR-12 | A fixed `sourceRepo` app, or any local repository answered with no kept files, runs | Unchanged: the place is the checkout itself (FIX-1762 BR-22) | Existing suite | | ||
| | BR-13 | A settled run continues, after an answered question or a person's turn | The same worktree is handed back on the same branch, with its uncommitted work and its kept files. The branch was never detached (D3) | Goal leg c, failing under `detach` · the harness-manager continuation goals, rerun (a fixed `sourceRepo`) | | ||
| | BR-14 | A person ran `git worktree remove` on a settled run's worktree, then the run continues | The worktree is added again on the run's existing branch | CI | | ||
| | BR-15 | A person checked the run's branch out in their own tree, then the run continues | The provision fails: git won't check a branch out twice. Nothing is reset | CI | | ||
| | BR-16 | The mapping changes or is removed while a run is in flight | The run keeps the repository its record names. New runs follow the new mapping | CI | | ||
|
|
||
| ## Two projects on one checkout | ||
|
|
||
| | # | When | Then | Proved by | | ||
| |---|---|---|---| | ||
| | BR-17 | Two runs on two projects mapped to one checkout start at once | Two places, two worktrees, two branches; both commit, both save their own kept files under their own key prefix, and both settle (ER-4) | CI, ten iterations, with the control below | | ||
| | BR-18 | The same two runs are given one place, the control | The second provision is refused: the live checkout is on the other branch. The "both settle" assertion fails | CI | | ||
| | BR-19 | Git finds one of its own lock files held (`*.lock` exists) during a provision | That provision fails loudly, naming git's error. It is not retried by the host, and no repository-wide lock is taken | CI, a planted lock | | ||
| | BR-20 | Both runs commit at the same moment | Separate indexes and separate refs, so neither waits on the other | CI, inside BR-17 | | ||
|
|
||
| One path crosses into your checkout, at the gate the mapping defines; every other approach stays | ||
| outside. The same fence is drawn in [SPEC.md](SPEC.md#what-changes). | ||
|
|
||
| ```mermaid | ||
| flowchart LR | ||
| A["shared fsd · named · same remote"] -->|"the gate · BR-1"| K["the operator's checkout"] | ||
| B["private fsd · same remote"] -.->|"never mapped · BR-2"| K | ||
| O["another org's shared fsd · same remote"] -.->|"other org · BR-21"| K | ||
| C["unnamed project · same remote"] -.->|"not named · BR-4"| K | ||
| D["named project · other remote"] -.->|"remote differs · BR-3"| K | ||
| E["path not in localRepositories"] -.->|"refused · BR-5"| K | ||
| ``` | ||
|
|
||
| ## Failure taxonomy | ||
|
|
||
| Nothing here retries. A refusal (BR-5) is the host's existing `WorkspaceRefusedError` and fails | ||
| the run before any agent is paid. A bad mapping (BR-6) fails at boot. A git failure (BR-10, | ||
| BR-15, BR-19) fails that provision with git's message, leaving the checkout and every other | ||
| worktree as they were. A project that isn't mapped is not an error: it is today's behaviour. | ||
|
|
||
| ## Acceptance criteria this issue owns | ||
|
|
||
| [The goal](SPEC.md#the-goal-and-how-well-know-its-met): on this repository's checkout, a named | ||
| project's run is a worktree there that installs and builds and continues after it settles, a | ||
| twin in another organization or a private one is not, and each leg fails under its control. ER-3 and ER-4 are proved here and consumed by FIX-1904 and the closure. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,127 @@ | ||
| # FIX-1906 · Decisions | ||
|
|
||
| [Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) · [Docs](DOCS.md) · [Evolution](EVOLUTION.md) | ||
|
|
||
| What was considered, what was chosen, why, and what each choice locks in. The epic already | ||
| decided that worktrees come from your checkout, that the row keeps naming a remote, and that the | ||
| mapping is the operator's and bound to project ids ([FIX-1903 D3](../../epics/FIX-1903/DECISIONS.md#d3), | ||
| [ER-13](../../epics/FIX-1903/BUSINESS-RULES.md#what-no-child-may-do)). These three are what that | ||
| costs on the real code. All three are engineering calls; D1 refines the epic's wording; the epic | ||
| coordinator accepted it as a stricter reading of ER-13, with no epic amendment needed ([ER-17](../../epics/FIX-1903/BUSINESS-RULES.md#how-the-set-is-run)). | ||
|
|
||
| ## The tree | ||
|
|
||
| ```mermaid | ||
| flowchart TD | ||
| I["FIX-1906"] --> D1["D1 · the mapping is a projectWorkspace option<br/>bound to a shared project's org and id"] | ||
| D1 -.->|"rejected · a bare id matches a twin in another scope"| X1["the workspace host maps by projectId"] | ||
| I --> D2["D2 · the shared pnpm store<br/>the coding agent installs"] | ||
| D2 -.->|"rejected · tests import the checkout's sources"| X2["node_modules linked from the checkout"] | ||
| D2 -.->|"rejected · a new host option for 6 seconds"| X3["the host installs after provisioning"] | ||
| I --> D3["D3 · a settled run keeps its branch checked out"] | ||
| D3 -.->|"rejected · every continuation is refused"| X4["detach the branch on settle"] | ||
| ``` | ||
|
|
||
| Solid edges are what you're signing. Dashed edges lost, and the label says why. | ||
|
|
||
| <a name="d1"></a> | ||
| ## D1 · The checkout mapping is an option of `projectWorkspace()`, bound to a shared project's organization and id, not the workspace host's | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | The epic's wording, "the workspace host gains that mapping": a `localWorkspaceHost` option from a remote and project ids to a checkout | | ||
| | **Because** | The host sees only the source's answer, and its `projectId` is a bare id. A project's address, `{ visibility, id }`, is relative to the run too: shared projects live in the current organization's scope and private ones in the current user's (`packages/workforce/src/projects/collections.ts`, `projectAddressSchema`). So a bare id, or even the address, matches a twin: any user who creates a private `fsd` with the same remote, or, on a server serving several organizations, another organization's shared `fsd`, would get a worktree of the operator's checkout, which ER-13 forbids. `projectWorkspace()` reads the stored row at its visibility (`answer()` in `project-workspace.ts`) and holds the run's context, so it can match the row's id and repository against the session's organization, `orgId` and `tenantId` as `principalFromContext` reads them from a verified principal (`packages/workspace/src/scope-identity.ts`), never the task's payload (BP-031). The host keeps the allowance it has: a path not in `localRepositories` is refused, as today | | ||
| | **Locks in** | Only shared projects map. A private project lives in one user's scope and the epic needs none mapped; this flips if a person needs their private project in their checkout. A session with no organization matches no entry. Workforce gains one option; the workspace host gains none, stricter than [ER-9](../../epics/FIX-1903/BUSINESS-RULES.md#what-no-child-may-do) allows. An operator names the checkout twice, once in the mapping and once in `localRepositories`, and a mismatch is a loud refusal. A run source other than `projectWorkspace()` gets no mapping; it answers the path itself | | ||
|
|
||
|  | ||
|
|
||
| It comes down to a twin, private or in another organization: a bare id can't tell it from the shared project, so the host would hand it your checkout. | ||
|
|
||
| **What would change my mind:** the source's answer carrying the project's full address and organization. Then | ||
| the host could bind it safely, and every run source would get the mapping for free. | ||
|
|
||
| <a name="d2"></a> | ||
| ## D2 · A fresh worktree gets its dependencies from the machine's shared pnpm store, installed by the coding agent | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | `node_modules` linked from the checkout · the host running the install after it provisions the place | | ||
| | **Because** | pnpm's store is per user and content-addressed, so every worktree on the machine already shares it: an offline install took 6 to 7 s and hard-linked every file ([the POC](poc/kill-line/README.md)). Linked from the checkout, pnpm's relative workspace links (`../../../core`) resolve to the checkout's sources, so the agent's tests import code it didn't edit, silently. A host install needs a new workspace or harness option for six seconds the agent already spends: this repository's agent docs tell it to run `pnpm install` | | ||
| | **Locks in** | A run's first build waits for one install, about 6 s on a warm store; on a machine whose store is cold, the first worktree pays a network install. An agent that skips it fails its first build loudly, with no `node_modules`; it is never silently wrong. The epic's kill line is met | | ||
|
|
||
|  | ||
|
|
||
| It comes down to what the tests import: linked dependencies run the checkout's code, not the agent's edits. | ||
|
|
||
| **What would change my mind:** coding agents skipping the install in practice. Then the host | ||
| runs it, through one generic option. | ||
|
|
||
| <a name="d3"></a> | ||
| ## D3 · A settled run's branch stays checked out in its worktree | ||
|
|
||
| | | | | ||
| |---|---| | ||
| | **Instead of** | Detaching the worktree's `HEAD` when the run settles, so a person can check the branch out in their own tree | | ||
| | **Because** | A settled run continues: an answered question and a person's turn both re-provision the run's live place. `goals/harness-manager/answered-run-continues-its-session` and `a-persons-turn-continues-its-session` show it for a fixed `sourceRepo` with no kept files; the mapped path, `checkout/` plus `project/`, is this issue's goal check, leg c. The host hands back a checkout only when it is on the run's branch (`handBack` in `packages/workspace/src/worktree.ts`), so a detached one is refused, and every continuation would fail | | ||
| | **Locks in** | Git won't check the branch out in your own tree while its worktree exists. A person reviews in the worktree or with `git diff main...<branch>`, which the epic's shared docs already say. `git worktree remove` frees the branch; a later continuation adds the worktree again on the same branch | | ||
|
|
||
|  | ||
|
|
||
| It comes down to continuation: a detached worktree is refused, so the run's next turn never starts. | ||
|
|
||
| ## Decided, not asked | ||
|
|
||
| - **The mapping carries an optional `baseRef`.** Absent means `HEAD`, as local mode does today, | ||
| with no fetch. A checkout may sit on any branch, so FIX-1904's profile names `main`. | ||
| - **With kept files, a local checkout's place is `checkout/` plus `project/`**, the remote | ||
| layout ([FIX-1762 BR-28](../FIX-1762/BUSINESS-RULES.md#the-projects-files-either-kind)). Without | ||
| them the place is the checkout itself, so a fixed `sourceRepo` app is unchanged (BR-12). | ||
| - **`tenantId` is matched exactly**: an entry that names one matches only a session in that | ||
| tenant, and one that names none only a session with none. That is narrower than the org scope, | ||
| which is keyed on `orgId` alone (`scopeComponents` in `scope-identity.ts`). | ||
| - **The remote is matched exactly as the row stores it**; a named project on another remote is | ||
| not mapped. **The mapping is checked when built**: absolute path, a storable remote, no project named twice. | ||
| - **No repository-wide lock.** Places and branches are distinct per run, and git keeps | ||
| concurrent worktrees apart ([Settled](#settled)). A git lock error fails loudly, never retried. | ||
| - **A mapped run is never held across machines**, as no local repository is today. | ||
| - **The run's record names the checkout path** as its repository, as a fixed `sourceRepo` | ||
| run's does today. That is the host's run record, not a project row ([ER-11](../../epics/FIX-1903/BUSINESS-RULES.md#what-no-child-may-do) holds). | ||
| - **No trusted single-user host mode.** ER-13 allows one; the goal doesn't need it. | ||
| - **Wiring the Lab's host is FIX-1904's**, including the answer-task host beside it. | ||
|
|
||
| ## Considered and dropped | ||
|
|
||
| | Alternative | Why not | | ||
| |---|---| | ||
| | A `file://` remote on the row | Epic D3: a machine path in a shared row, and a hidden clone | | ||
| | Resolve the checkout from a row's remote alone | ER-13: any project's owner can set a remote | | ||
| | A host option keyed by bare `projectId` | D1: a twin, private or in another organization, matches | | ||
| | A lock over the whole checkout | Git's own locks suffice; a lock would make two projects wait on each other, which ER-4 forbids | | ||
| | Normalising remotes before matching | Two spellings of one remote is config the operator fixes; a fuzzy match widens who gets the checkout | | ||
|
|
||
| ## Settled | ||
|
|
||
| - **A fresh worktree of this repository installs and builds** (the kill line) — **CONFIRMED** | ||
| on `main` at `be18f487`, node 22.22.0, pnpm 10.4.1; commands and results in | ||
| [poc/kill-line/](poc/kill-line/README.md): | ||
| - `git worktree add -b <branch> <dir> origin/main`, then `pnpm install --frozen-lockfile --offline`: exit 0, 6 to 7 s; with an empty store it fails, so the shared store supplied it | ||
| - `pnpm packages:build`: exit 0, 30 of 30 tasks, 86 s with no cache | ||
| - `pnpm --filter @flow-state-dev/workspace test`: 216 of 216, 49 to 52 s | ||
| - `pnpm --filter @flow-state-dev/shift-manager typecheck`: exit 0, 12 s | ||
| - **The build cost is paid once per change, not per worktree** — **CONFIRMED**: turbo 2.9.16 | ||
| keeps one local cache for every worktree of a repository; a second worktree's full build took | ||
| 2 s. (The design brief said turbo's cache was per worktree. It isn't.) | ||
| - **Concurrent worktrees of one repository don't collide** — **CONFIRMED**: 36 concurrent | ||
| `git worktree add -b`, every directory named `checkout`, 0 errors; a second worktree on a held | ||
| branch is refused, which is the control. | ||
|
|
||
| ## How it got here | ||
|
|
||
| - **Draft (2026-10-12)** — built on the FIX-1906 thread's spike. D1 moved the mapping from the | ||
| host to the run source after reading what the host can see; raised to the epic coordinator as a | ||
| refinement of epic D3, and accepted there with no epic amendment. The shared turbo cache found while re-running the spike. | ||
| - **Review round 1 (2026-10-12)** — Cursor approved with optional notes. Codex: bind the mapping to | ||
| the run's organization, shared projects only (D1, BR-21); prove continuation on the mapped path | ||
| (goal leg c); make the POC's collision control check its own setup; one `patch` changeset. | ||
|
|
||
| **Open: none.** |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.