Skip to content

feat(FIX-1906): coding runs for mapped projects work in worktrees of your checkout - #3185

Merged
jhoffner merged 5 commits into
mainfrom
claude/project-thread-wefsi0
Oct 12, 2026
Merged

jhoffner merged 5 commits into
mainfrom
claude/project-thread-wefsi0

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator

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 equals remote, 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 in project/ beside the worktree. Every other project runs as before.

How:

  • workspace: the local-repository mode of localWorkspaceHost now takes kept files, using the checkout/ + project/ layout. Without kept files it is unchanged. It gains no new option.
  • workforce: projectWorkspace gains the checkouts option. It is validated when built, and it matches the stored row and the run's server-set organization and tenant.
  • Tests: two projects on one checkout, run concurrently over 10 iterations, with a one-place control that must fail and a planted git lock. Organization, tenant and private-twin cases. A mapped run's retry stays on its recorded checkout.
  • Goal: goals/projects/a-mapped-project-works-in-your-checkout uses 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. Controls no-mapping, ignore-org and detach each FAIL on their named assertion, and today's main fails a:in-checkout.
  • Docs and release notes: apps/docs/docs/workforce/projects.md, the workspace and workforce READMEs, and one patch changeset.

Checks run locally:

  • workspace 227/227, workforce 1248/1248 and harness-manager 260/260 tests.
  • typecheck for workspace, workforce, harness-manager, shift-manager and goals.
  • the root validators and knip:ci.
  • the goal and each of its controls.

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 optional checkouts (remote, absolute checkout, projects by org/id/tenant, optional baseRef). Matching uses the session’s verified org/tenant and the project row’s repository; private projects, other orgs, and unlisted projects stay on the normal remote path. Invalid config fails at build time.

Workspace: localWorkspaceHost with localRepositories now allows kept project files next to a local repo using the same checkout/ + project/ layout as remote runs (no-kept-files local places are unchanged). Local provisioning validates baseRef, 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.

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
@vercel

vercel Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 12, 2026 8:47pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 12, 2026 8:47pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 12, 2026 8:47pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 12, 2026

Copy link
Copy Markdown

FIX-1906

@cursor

cursor Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot 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)

@jhoffner

Copy link
Copy Markdown
Collaborator Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-12T20:45:07.741761Z 315f7f3 Manual request
ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@jhoffner jhoffner self-assigned this Oct 12, 2026

Copy link
Copy Markdown
Collaborator Author

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 principalFromContext, shared-only, exact repository === remote) follows BP-031. I found no blocking issues. Everything below is optional, ordered by value.

1. Two config places must agree, with no check between them (worth a decision, not necessarily a change)

projectWorkspace({ checkouts }) and localWorkspaceHost({ localRepositories }) both have to list the same absolute path. checkedCheckouts validates the path is absolute, but nothing catches a checkout that's mapped and not in localRepositories. That surfaces only at run time, as the host refusing a bare path, far from the config mistake. Options, leanest first:

  • Keep as is, and make the host's refusal message mention "if this came from projectWorkspace({ checkouts }), list it in localRepositories too". A one-line change.
  • Have projectWorkspace expose the paths it maps (for example a .checkouts property on the returned source) so the host can fail at construction. This adds surface, so only worth it if the mismatch is reported in practice.

I'd take the first option unless the spec already settled this.

2. localWorkspaceHost: the new local-with-files branch duplicates the remote branch's shape

The local-with-files block (lock at join(dir, LOCK_SUFFIX), provision checkout, provisionFiles(dir, PROJECT_DIR, …), build the place with filesDir/holder) repeats the tail of the remote branch near the end of provision. That tail is provisionFiles + place.filesDir + place.holder. Two places now have to agree on the checkout/ + project/ layout and the holder wiring. A small shared helper such as withKeptFiles(place, dir, answer), used by both, would make the layout live in one spot. This is a refactor of code the PR is already touching, so it fits the "refactor while implementing" bar. It's also safe to skip.

3. Held-work (heldPrefix) is silently ignored for a local repository

The remote branch routes a heldPrefix answer through provisionHolding. A local repository never does, and it didn't before this PR either. It's more reachable now that local places can carry project files. The only source in this PR (projectWorkspace) never sets heldPrefix, so this isn't a bug today. Either assert "a local repository can't hold work" when heldPrefix is present, or add one line to the localRepositories doc saying so. Otherwise a future source answering both gets a run that quietly loses held work.

4. Small notes

  • checkoutFor is exported "for its tests" but isn't re-exported from index.ts. That's correct, since it's module-internal. Make sure knip doesn't need an ignore for it (you said knip:ci passed, so this is probably fine).
  • checkedCheckouts validates remote via repositoryProblem. Rows store the remote verbatim, so a trailing .git or case difference between config and row silently means "not mapped". That's the documented exact-match contract. A one-line example in the docs showing the remote copied from the project row would save an operator a confusing "why isn't my project mapped" session.
  • The changeset is patch. The new public option checkouts plus the exported types is arguably a minor for a pre-1.0 package under BP-022. The repo's convention decides, so I'm flagging it only.

Not recommended

I considered folding the local-repository mode into the remote path, as a clone whose "remote" is a local path. I'm recommending against it. That would bring back fetch and clone semantics the spec deliberately excludes ("no fetch, never touch the operator's working tree"), and the PR's separate path keeps that guarantee obvious.


Generated by Claude Code

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

  1. Dual operator config — projectWorkspace({ checkouts }) and localWorkspaceHost({ 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 derives localRepositories from checkouts[].checkout — not required to merge this PR.

  2. Local repo + kept files — Mapped answers always carry projectId + files, so first provision pays provisionFiles (rm + hydrate) on every new place. That is the intended trade (remote fetch vs local hydrate), not a bug.

  3. Parallel local provisions — Dropping the repo-wide lock on provisionLocalCheckout is 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

  • checkedCheckouts at source build time (absolute path, repositoryProblem, duplicate project keys).
  • checkoutFor gating: shared only, verified org/tenant, exact remote match.
  • 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.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread packages/workspace/src/local-host.ts Resolved
Comment thread packages/workspace/src/local-host.ts Resolved
Comment thread apps/docs/docs/workforce/projects.md Resolved

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread .changeset/project-checkout-mapping.md Resolved
…orkspace refusal

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013uVA1pkZu3CXS5ZeEP8xNo
@cursor

cursor Bot commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot 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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants