Repository navigation
feat(FIX-1906): coding runs for mapped projects work in worktrees of your checkout - #3185
Conversation
A repository the operator lists in localRepositories, answered with kept files, now gets the remote layout: the worktree in <place>/checkout/ and the files in <place>/project/, provisioned and saved as a remote run's are, and locate() agrees. Without kept files nothing changes: the place is the checkout, marker and lock beside it. A baseRef the repository lacks now fails naming it before anything is made. Tests: two projects on one checkout, concurrent, ten iterations, with the one-place control; a planted git lock; base ref, removed worktree and branch-checked-out-elsewhere cases. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
…to a local checkout A shared project an entry names by organization and id (tenant matched exactly), whose stored repository equals the entry's remote, is answered with the entry's checkout path and baseRef. The organization and tenant are the run session's verified principal, never the task. Private projects, other organizations and tenants, and sessions with no org are never mapped. Entries are checked when built: absolute path, a storable remote, no project named twice. Tests on the real engine for both visibilities, two organizations, tenants, a payload naming another org, remote mismatch, unnamed project; harness-manager: a mapped run's retry stays on its recorded checkout. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
Model-free, in process on the real engine: a harness manager on
localWorkspaceHost over this repository's checkout with
projectWorkspace({ checkouts }). Leg a: the run is a worktree of the
checkout, installs offline and builds there, leaves its branch in it, and
saves a note kept beside it. Leg b: another organization's shared project
and a private one with the same id and remote get no worktree. Leg c: the
parked run's second turn continues in the same worktree and branch with
its kept files. Controls no-mapping, ignore-org and detach each fail
their named assertion; today's main fails a:in-checkout.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
The projects guide gains a subsection on projectWorkspace({ checkouts }):
the host config, who gets the checkout, the place layout, reviewing a
run, and installs in a fresh worktree. The workspace README describes a
local repository with kept files beside it; the workforce README
documents the option and ProjectCheckout. One patch changeset for both
packages.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: d5d8c856-1954-4d70-9ffd-93e46ab2e01a) |
|
@codex review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Second-look + architecture review (read-only, for the implementing agent to triage)Overall: the approach is sound and matches the merged spec. The change is mostly additive, the no-kept-files local path is preserved byte-for-byte, and the security-relevant matching (org/tenant from 1. Two config places must agree, with no check between them (worth a decision, not necessarily a change)
I'd take the first option unless the spec already settled this. 2.
|
There was a problem hiding this comment.
Simplify review (FIX-1906)
Verdict: The workforce / workspace split is the right boundary: mapping and BP-031 gating belong in projectWorkspace; worktree layout and localRepositories enforcement belong in localWorkspaceHost. I do not see a materially smaller design that still delivers org/tenant/project-scoped mapping with kept files beside the worktree. A “path-only” shortcut (map when repo equals a listed local path) would drop the security model this PR and the docs describe.
What feels heavy is mostly evidence, not accidental abstraction: unit tests, harness BR-16, workspace concurrency specs, and the goal script. That layering matches a security-sensitive path.
Where complexity is real (worth keeping an eye on)
-
Dual operator config —
projectWorkspace({ checkouts })andlocalWorkspaceHost({ localRepositories })must agree on the same absolute paths. Docs explain it and tests cover refusal; it is still a footgun at runtime (invalid-remote). Optional later: a small composer (e.g. fsdev profile helper) that deriveslocalRepositoriesfromcheckouts[].checkout— not required to merge this PR. -
Local repo + kept files — Mapped answers always carry
projectId+files, so first provision paysprovisionFiles(rm + hydrate) on every new place. That is the intended trade (remote fetch vs local hydrate), not a bug. -
Parallel local provisions — Dropping the repo-wide lock on
provisionLocalCheckoutis consistent with the existing concurrent-local design; more parallel git work on one checkout is possible. Specs cover it.
Simplify follow-ups (non-blocking)
| Area | Suggestion | Confidence |
|---|---|---|
project-workspace.ts |
The Answer callback type + threading through fromWorkstream / fromProject could be dropped in favor of passing checkouts and calling answerFor directly. |
Should simplify readability; behavior unchanged. |
checkoutFor export |
Fine for tests; if it stays public, one line in the module doc that it is a supported matching helper (or test-only) would set expectations. | Optional API hygiene. |
local-host.ts |
Local + files branch (~787–807) mirrors remote repo+files (~830+). A private provisionRepoPlaceWithFiles would reduce drift risk. |
Worth doing when touching this file again. |
local-host.ts |
Missing baseRef on a local repo throws plain Error (712) while clone path uses WorkspaceRefusedError. Align if callers normalize on refusal reasons. |
Minor consistency; I am not sure all callers distinguish today. |
| Tests / goal | git worktree list --porcelain parsing is copy-pasted in two workspace specs and the goal — listWorktreePaths in git-fixtures.ts would be a small win. |
Clear duplication. |
| Third-party git | Do not add simple-git; existing exec + worktree deadline model is the established stack. |
Strong recommendation. |
| Goal size (~440 lines) | Heavy but appropriate for anti-game grading; shrinking without losing controls would weaken evidence. | Would not trim in this PR. |
What reads clean
checkedCheckoutsat source build time (absolute path,repositoryProblem, duplicate project keys).checkoutForgating: shared only, verified org/tenant, exactremotematch.- Reusing remote place layout (
checkout/+project/) for local mapped runs. - Changeset and user docs match the public contract.
No changes requested for merge; inline notes on a few spots below.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
Code Snob — already tight. No POC.
I read packages/workspace/src/local-host.ts, packages/workforce/src/projects/project-workspace.ts, packages/workspace/test/local-host-local.spec.ts, packages/workspace/test/local-host-shared-checkout.spec.ts, packages/workforce/test/project-workspace-task.test.ts, and goals/projects/a-mapped-project-works-in-your-checkout/run.mts.
A helper around the two provisionFiles(dir, PROJECT_DIR, …) tails is longer than the four lines it replaces. The local-with-files branch and the no-files branch differ on lock, marker, and cwd; folding them into one function with ternaries hides the on-disk layout the no-files path has to keep. Passing checkouts into fromWorkstream / fromProject is the same length as the answer closure. checkoutFor stays exported because a session with no organization never reaches the source, and that test is the three expects. worktrees and worktreesOf are six lines in two specs; a shared helper is a new export. The goal is this check's three legs and its worktree cleanup. The continuation goals use a real model and a different host.
A rewrite would not shrink the contract.
Sent by Cursor Automation: Code Snob
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 315f7f3a1f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…orkspace refusal Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: b04f98db-cf9a-4036-9d9f-9672c0dbd081) |


Requested by Jake · project thread
Implements FIX-1906 to its merged spec,
specs/issues/FIX-1906/(#3177).Before: a project's coding run always cut its branch in a clone the host made. A repository on the host's machine couldn't keep the project's files beside its worktree.
After: an operator can pass
projectWorkspace({ checkouts: [{ remote, checkout, projects: [{ orgId, id }], baseRef }] }). Each run on a named shared project, in that organization, whose stored repository equalsremote, is then a fresh worktree of the operator's checkout. The run's branch is kept in the checkout, and the project's files sit inproject/beside the worktree. Every other project runs as before.How:
localWorkspaceHostnow takes kept files, using thecheckout/+project/layout. Without kept files it is unchanged. It gains no new option.projectWorkspacegains thecheckoutsoption. It is validated when built, and it matches the stored row and the run's server-set organization and tenant.goals/projects/a-mapped-project-works-in-your-checkoutuses this repository as the checkout and runs without a model. Leg a installs and builds in the worktree, leg b checks that projects outside the mapping stay out, and leg c continues a settled run. Controlsno-mapping,ignore-organddetacheach FAIL on their named assertion, and today'smainfailsa:in-checkout.apps/docs/docs/workforce/projects.md, the workspace and workforce READMEs, and onepatchchangeset.Checks run locally:
knip:ci.Not run: the real-model harness-manager continuation goals (V6). They cover the unchanged no-kept-files path, whose tests still pass.
What's asked of you
Nothing new. The design is the merged spec. The only thing this PR needs from you is the merge.
🤖 Generated with Claude Code
https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
Generated by Claude Code
Note
Medium Risk
Changes core workspace provisioning and run-source resolution for git-backed coding runs; misconfiguration could refuse runs or create worktrees in the wrong checkout, though org/tenant guards and build-time validation limit blast radius.
Overview
Operators can map shared coding runs to an existing git checkout on the server instead of always using a host-managed clone.
Workforce:
projectWorkspace()gains optionalcheckouts(remote, absolutecheckout,projectsby org/id/tenant, optionalbaseRef). Matching uses the session’s verified org/tenant and the project row’srepository; private projects, other orgs, and unlisted projects stay on the normal remote path. Invalid config fails at build time.Workspace:
localWorkspaceHostwithlocalRepositoriesnow allows kept project files next to a local repo using the samecheckout/+project/layout as remote runs (no-kept-files local places are unchanged). Local provisioning validatesbaseRef, avoids locking the whole repo for concurrent worktrees, and does not touch the operator’s main working tree.Verification: New/expanded tests (concurrent mapped projects, harness retry on mapped checkout), a model-free goal against this repo’s checkout, and docs/changeset for FIX-1906.
Reviewed by Cursor Bugbot for commit ccaa814. Configure here.