Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs: a local checkout fetches its upstream before a new run (FIX-1927)
Shift Manager overview and README, Workforce projects guide, workspace
README (base-diverged refusal), Lab profile comments, and the changeset
(workspace minor, harness-manager patch).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GJ9UL2RHLrxJsiGFnkuxjt
  • Loading branch information
claude committed Oct 13, 2026
commit 2348dbd6b9cb7bca7892a8a08d94062016ef66fc
6 changes: 6 additions & 0 deletions .changeset/local-checkout-starts-from-upstream.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
"@flow-state-dev/workspace": minor
"@flow-state-dev/harness-manager": patch
---

A repository listed in `localRepositories` now fetches the base's upstream before it cuts a new run's branch, and cuts from whichever of local and upstream is newer. A base whose local and upstream copies have each moved is refused as `base-diverged`; a failed fetch falls back to the last-fetched copy with a warning. `place.repo.baseCommit` is now set for these repositories, and `readRunCommits` also leaves out the base's upstream (FIX-1927).
8 changes: 6 additions & 2 deletions apps/docs/docs/shift-manager/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,13 @@ If the Lab fails to start after a save, the error prints and Shift Manager waits

In this repository, `pnpm shift-manager:dev` opens the `fsd` profile: a Lab for working on this repository with Shift Manager itself. It has two projects from the start. **FSD** is the framework packages, and **Shift Manager** is this app. Both are shared with everyone in the Lab, and both point at this repository. Inbox is empty until a worker asks you something.

Ask the [chief of staff](../workforce/chief-of-staff.md) for work on either project, and say which one, for example "on Shift Manager, make the empty Inbox say who to ask". A coding agent picks it up in a fresh worktree of your checkout, on a branch of its own cut from your local `main`. It doesn't fetch first, so pull `main` when you want the run to start from the latest. Review the work in that worktree, or from your checkout with `git diff main...<branch>`. The branch stays checked out in its worktree, so git won't check it out a second time in yours.
Ask the [chief of staff](../workforce/chief-of-staff.md) for work on either project, and say which one, for example "on Shift Manager, make the empty Inbox say who to ask". A coding agent picks it up in a fresh worktree of your checkout, on a branch of its own. Before cutting that branch, the Lab fetches `main` from GitHub and starts from whichever is newer: that, or your local `main`. So you don't need to pull first, and commits you haven't pushed are kept. Your own `main`, its files and your index aren't touched.

Only those two projects get a worktree of your checkout. The Lab reaches no git remote, so a coding run on a project you add yourself, even one on this repository, is refused, naming the repository, and nothing is fetched.
If your `main` and `origin/main` each have commits the other lacks, the run is refused before anything is made, and the refusal names both commits. Pull or rebase, or push, then ask again. If the fetch fails, because you're offline for instance, the run starts from the `origin/main` you last fetched, and a warning prints where you started Shift Manager.

Review the work in that worktree, or from your checkout with `git log -p <branch> --not main origin/main`. That shows only the run's commits, whichever of the two it started from. The branch stays checked out in its worktree, so git won't check it out a second time in yours.

Only those two projects get a worktree of your checkout. Apart from that fetch, the Lab reaches no git remote, so a coding run on a project you add yourself, even one on this repository, is refused, naming the repository, and nothing is cloned.

The coding agent is Claude Code. Sign in to Claude Code, or set `ANTHROPIC_API_KEY`, before you start. Without either, the Lab refuses to start and says so. To run the scripted coder (`stub`) instead, which writes one file and costs nothing, set `DEVFORCE_LAB_HARNESS=stub`. A `Coder:` line at start names the coder it started with. The chief of staff answers on a model of its own, so its turns need `ANTHROPIC_API_KEY` or `AI_GATEWAY_API_KEY`.

Expand Down
15 changes: 13 additions & 2 deletions apps/docs/docs/workforce/projects.md
Original file line number Diff line number Diff line change
Expand Up @@ -543,11 +543,22 @@ Only shared projects can be listed, each by its organization and id. A run uses

The checkout also has to be in the host's `localRepositories`. That list is what lets the host touch a folder on its machine at all. If the two disagree, the run is refused with `invalid-remote`, naming the path, before git runs. A relative `checkout` path, a `remote` a project couldn't store, or a project listed twice is refused when `projectWorkspace()` is called, naming the entry.

Each run's place has the worktree in `checkout/` and the [project's files](#the-projects-own-files) in `project/` beside it, as for any other repository. The branch is cut from `baseRef`, or from whatever your checkout has checked out when `baseRef` is left out. Nothing is fetched, so `main` is whatever you last pulled. The server never switches, resets or cleans your own working tree.
Each run's place has the worktree in `checkout/` and the [project's files](#the-projects-own-files) in `project/` beside it, as for any other repository. The branch is cut from `baseRef`, or from whatever your checkout has checked out when `baseRef` is left out.

Before the server cuts a new branch, it fetches that base's upstream, the remote branch it tracks, such as `origin/main`. Then it starts from whichever is newer: upstream when you haven't pulled, your own branch when it has commits you haven't pushed. Only the remote-tracking copy is updated. The server never switches, resets or cleans your working tree, and never moves your branch.

A few cases go differently:

- **Your branch and its upstream have each moved.** The run is refused with `base-diverged`, naming both commits, and nothing is made. Pull or rebase, or push, and the next run starts.
- **The fetch fails**, because you're offline, a credential is refused, or it times out. The run starts from the copy you last fetched, and the server logs a warning naming the checkout and git's error.
- **The base has no upstream**, such as a tag, a commit, or a branch that tracks nothing. It is used as it is, with no fetch.
- **The run already has its branch**, on a retry or a later turn. It's handed back as it was, and nothing is fetched.

Listing the checkout is what allows the fetch, so the upstream doesn't need to be in `remotes.allow`. That list still decides which remotes the host clones. The upstream's URL is checked before git sees it: one that uses a transport helper such as `ext::`, starts with `-`, or uses a scheme other than `https`, `ssh` or `file` isn't fetched, and the server logs why.

Several projects can share one checkout, and their runs work side by side, each in its own worktree on its own branch.

To review a run, open its worktree, or run `git diff main...<branch>` from your checkout. The branch stays checked out in the run's worktree, because a run can be continued later, after a question is answered or when you send it another turn, and it picks up in the same place. So git won't check that branch out a second time in your own tree. When you're done with a run, `git worktree remove <path>` frees the branch.
To review a run, open its worktree, or run `git log -p <branch> --not main origin/main` from your checkout. That shows only the run's commits, whether it started from your `main` or from `origin/main`. `git diff main...<branch>` would also show upstream commits your `main` doesn't have yet. The branch stays checked out in the run's worktree, because a run can be continued later, after a question is answered or when you send it another turn, and it picks up in the same place. So git won't check that branch out a second time in your own tree. When you're done with a run, `git worktree remove <path>` frees the branch.
Comment thread
jhoffner marked this conversation as resolved.
Resolved

A fresh worktree has no `node_modules`. The coding agent installs them the way your repository tells it to. With pnpm that comes from the machine's shared store and takes seconds once the checkout has been installed.

Expand Down
8 changes: 6 additions & 2 deletions packages/shift-manager/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,13 @@ If the Lab fails to start after a save, the error prints and Shift Manager waits

In this repository, `pnpm shift-manager:dev` opens the `fsd` profile, at `teams/devteam/fsd.fsdev.config.mts`: a Lab for working on this repository with Shift Manager itself. It has two projects from the start. **FSD** is the framework packages, and **Shift Manager** is this app. Both are shared with everyone in the Lab, and both point at this repository. It raises no ask and opens no workstream, so Inbox is empty until a worker asks you something.

Ask the chief of staff for work on either project, and say which one, for example "on Shift Manager, make the empty Inbox say who to ask". A coding agent picks it up in a fresh worktree of your checkout, on a branch of its own cut from your local `main`. It doesn't fetch first, so pull `main` when you want the run to start from the latest. Review the work in that worktree, or from your checkout with `git diff main...<branch>`. The branch stays checked out in its worktree, so git won't check it out a second time in yours.
Ask the chief of staff for work on either project, and say which one, for example "on Shift Manager, make the empty Inbox say who to ask". A coding agent picks it up in a fresh worktree of your checkout, on a branch of its own. Before cutting that branch, the Lab fetches `main` from GitHub and starts from whichever is newer: that, or your local `main`. So you don't need to pull first, and commits you haven't pushed are kept. Your own `main`, its files and your index aren't touched.

Only those two projects get a worktree of your checkout. The Lab reaches no git remote, so a coding run on a project you add yourself, even one on this repository, is refused, naming the repository, and nothing is fetched.
If your `main` and `origin/main` each have commits the other lacks, the run is refused before anything is made, and the refusal names both commits. Pull or rebase, or push, then ask again. If the fetch fails, because you're offline for instance, the run starts from the `origin/main` you last fetched, and a warning prints where you started Shift Manager.

Review the work in that worktree, or from your checkout with `git log -p <branch> --not main origin/main`. That shows only the run's commits, whichever of the two it started from. The branch stays checked out in its worktree, so git won't check it out a second time in yours.

Only those two projects get a worktree of your checkout. Apart from that fetch, the Lab reaches no git remote, so a coding run on a project you add yourself, even one on this repository, is refused, naming the repository, and nothing is cloned.

The coding agent is Claude Code. Sign in to Claude Code, or set `ANTHROPIC_API_KEY`, before you start. Without either, the Lab refuses to start and says so. To run the scripted coder (`stub`) instead, which writes one file and costs nothing, set `DEVFORCE_LAB_HARNESS=stub`. A `Coder:` line at start names the coder it started with. The chief of staff answers on a model of its own, so its turns need `ANTHROPIC_API_KEY` or `AI_GATEWAY_API_KEY`.

Expand Down
3 changes: 2 additions & 1 deletion packages/shift-manager/teams/devteam/fsd-checkouts.mts
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ const CHECKOUT = resolve(fileURLToPath(new URL("../../../..", import.meta.url)))

/**
* Where the two projects' runs work: worktrees of {@link CHECKOUT}, each on a
* branch cut from local `main`, never fetched. Only the two shared projects
* branch cut from the newer of local `main` and its freshly fetched upstream
* (the workspace host's rule for a listed checkout). Only the two shared projects
* of the Lab's organization are named, so a project a user makes on the same
* remote is not mapped, and is refused.
*/
Expand Down
10 changes: 6 additions & 4 deletions packages/shift-manager/teams/devteam/fsd.fsdev.config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -19,11 +19,13 @@
* what to set. `DEVFORCE_LAB_HARNESS=stub` runs the scripted coder instead.
* - **Runs work in this checkout.** A coding run on FSD or Shift Manager gets
* a fresh worktree of the checkout this file sits in, on a branch of its
* own cut from local `main` ({@link CHECKOUTS}, in `fsd-checkouts.mts`). The
* checkout's location is worked out from that file's, never written down.
* - **No remote is reached.** The workspace hosts allow none, so a run the
* own cut from the newer of local `main` and its upstream ({@link CHECKOUTS},
* in `fsd-checkouts.mts`). The checkout's location is worked out from that
* file's, never written down.
* - **No remote is cloned.** The workspace hosts allow none, so a run the
* mapping misses (a project a user made, or one in another organization) is
* refused, naming the remote, and nothing is fetched.
* refused, naming the remote, and nothing is cloned. The one remote reached
* is the checkout's own upstream, fetched before a new run's branch is cut.
* - **Its own store**: SQLite at `FSD_STORE` or
* `packages/shift-manager/.fsdev/fsd.sqlite`. DevTeam's rows never show
* here. Delete the file for a fresh start.
Expand Down
5 changes: 3 additions & 2 deletions packages/workspace/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,7 @@ const host = localWorkspaceHost({
});
```

The run's branch is cut from `baseRef` (or `HEAD`) and stays in that repository. Nothing is fetched, on the first run or a retry, and the repository's own working tree is never touched. When the source names no kept files, the place directory is the checkout itself, with no `checkout/` level. When it names kept files, the place is laid out like a remote run's: the worktree in `checkout/` and the kept files in `project/` beside it. Any bare path not on the list is still refused as `invalid-remote`, before git runs.
The run's branch is cut from `baseRef` (or `HEAD`) and stays in that repository. For a new branch whose base tracks an upstream, the host first fetches that one upstream branch, which updates only its remote-tracking ref, then cuts from whichever of the two is newer. Listing the repository allows the fetch; `remotes.allow` isn't asked. The URL is still checked as any remote is, with an absolute path read as `file://`. When local and upstream have each moved, the provision is refused as `base-diverged` before anything is made. A failed fetch isn't a refusal: the host compares with the last-fetched copy and logs a warning. A base with no upstream fetches nothing, and neither does a branch that already exists. `place.repo.baseCommit` is the commit the branch was cut at. The repository's own branches, index and working tree are never touched. When the source names no kept files, the place directory is the checkout itself, with no `checkout/` level. When it names kept files, the place is laid out like a remote run's: the worktree in `checkout/` and the kept files in `project/` beside it. Any bare path not on the list is still refused as `invalid-remote`, before git runs.

Runs in one repository don't share a lock. Each has its own place and branch, and git keeps concurrent worktrees apart. If git finds one of its own lock files held, that provision fails with git's message and isn't retried. A `baseRef` the repository doesn't have fails the provision, naming it, before anything is made.

Expand Down Expand Up @@ -440,9 +440,10 @@ interface HeldWorkStore {
| `invalid-remote` | The value starts with `-`, uses a transport helper like `ext::`, has a host starting with `-`, carries a password or an `https` login, or is a bare path rather than a URL |
| `remote-not-allowed` | Its host isn't listed, it's `file://` and `"file"` isn't listed, or its scheme isn't `https`, `ssh` or `file` |
| `remote-unreadable` | The host is allowed but git couldn't read it, or it has no branch to cut from |
| `base-diverged` | A repository on this machine: the base and its upstream each have commits the other lacks. Nothing is made |
| anything else | The source answered `refused`, with that reason |

Git itself runs with `GIT_ALLOW_PROTOCOL` set to the listed schemes, with `--` before every remote, and without a terminal prompt. A refusal names the remote without its credential. None of these clears on a retry, so fail the run with the reason.
Git itself runs with `GIT_ALLOW_PROTOCOL` set to the listed schemes, with `--` before every remote, and without a terminal prompt. A refusal names the remote without its credential. None of these clears on a retry by itself, so fail the run with the reason. `base-diverged` clears once someone pulls or rebases, or pushes, in that repository.

## API

Expand Down
Loading