Skip to content

spec(FIX-1927): a local checkout's run starts from the current base - #3198

Merged
jhoffner merged 1 commit into
mainfrom
spec/FIX-1927
Oct 12, 2026
Merged

jhoffner merged 1 commit into
mainfrom
spec/FIX-1927

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Spec for FIX-1927, under specs/issues/FIX-1927/. Merging this PR approves the direction.

Before: a coding run on a project mapped to a local checkout cuts its branch from the checkout's local main with no fetch, so a person who hasn't pulled gets a run that starts stale, and the docs ask them to pull by hand.

After: before cutting a new branch, the server fetches the base's upstream and cuts from whichever of local and upstream is newer, without touching the person's own branch, index or files. If local and upstream have both moved, the run is refused and says to pull or push. If the fetch fails, it compares against the last fetched copy and logs a warning. A branch that already exists is never fetched or moved. No new setting.

Need your sign-off

Let listing a checkout allow fetching its own upstream? (D3) Both local entry points run with an empty remote allowlist, so gating the fetch on remotes.allow would mean the Lab never fetches. Instead, naming the checkout in localRepositories admits fetching that checkout's own upstream URL, still judged before git sees it. The cost: the Lab now contacts the checkout's upstream (GitHub) on each new run, where today it reaches no remote. Recommendation: yes. What would change my mind: a deployment where the server must make no network calls at all; then the fallback is "compare against the last fetched copy only".

Also decided, flip if you disagree: a failed fetch falls back with a warning rather than refusing the run (D2).

How

provisionLocalCheckout in @flow-state-dev/workspace resolves <base>@{upstream}, fetches that one branch non-interactively, compares, and records the commit it cut at as baseCommit. harness-manager's readRunCommits also excludes <base>@{upstream} so upstream commits are never counted as the run's. Docs replace "pull main first" and fix the review command. Single implementation PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GJ9UL2RHLrxJsiGFnkuxjt


Generated by Claude Code

Retained issue spec: before cutting a new run's branch in a listed local
repository, the workspace host fetches the base's upstream branch and cuts
from whichever of local and upstream is newer; a split base is refused as
base-diverged; a failed fetch falls back to the last-fetched copy with a
warning. Listing the checkout admits the fetch, because both local entry
points (the Lab's fsd profile and harness-manager's hostForConfig) allow
no remote. No setting. One PR in workspace, one line in harness-manager.

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

linear-code Bot commented Oct 12, 2026

Copy link
Copy Markdown

FIX-1927

@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 11:54pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 12, 2026 11:54pm UTC
flow-state-dev-ui Ignored Ignored Oct 12, 2026 11:54pm UTC

Request Review

@jhoffner jhoffner self-assigned this Oct 12, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture notes (FIX-1927 spec)

Read the spec set against packages/workspace/src/local-host.ts (provisionLocalCheckout, provisionClonedCheckout) and packages/harness-manager/src/commits.ts. The direction is sound: fetch at the owning layer, local-when-ahead, refuse only on a split, no new setting. The notes below are for the implementer to weigh; none block the direction.

1. S6 / BR-20 can probably be deleted by using baseCommit (the one worth acting on)

The spec makes baseCommit set for local checkouts (BR-8), then separately teaches readRunCommits to exclude local base, origin/<base> and <base>@{upstream}. Those are three heuristics for "what did the base look like when the run was cut". The run's own commits are exactly HEAD --not <baseCommit>, and that is exact whichever copy won, whatever the remote is called, and unaffected by the person later pulling or pushing. It also fixes the existing baseRef === "HEAD" case in readRunCommits, where only origin/HEAD is excluded, so a local-ahead run counts the person's unpushed commits as the run's.
Cost: readRunCommits(cwd, baseRef) is called from manager.ts:2312 with state.baseRef only, so baseCommit has to be carried into harness-manager's run state. That is more plumbing than one line, but it replaces a heuristic with a fact the host already records. Same for the docs: "review with git log -p <branch> --not main origin/main" is a workaround for not having this; the review command could be keyed to the recorded base. If the plumbing is judged too wide for this PR, keep S6 but say in the Plan that it's a stopgap, and file the follow-up.

2. Check what else reads place.repo.baseCommit

Today it's set only on the clone path (provisionClonedCheckout, and base: repo.baseCommit! in the non-held branch). Plan S3 edits the field's doc ("only for a clone") but no surface lists a grep of consumers. Before setting it for local checkouts, confirm nothing treats "baseCommit present" as "this is a clone" (held-work, merge-base fallbacks like repo.baseCommit ?? held?.base ?? mergeBase(...)). Add that as a V-check or an explicit "At implement time" line.

3. D2 leaves the original problem quiet in exactly the offline case

The issue is "quietly stale". D2 makes the failure mode console.warn on the server, which the person who ran the work never sees. The spec is honest about this and flags it as the likeliest flip. Suggested middle path that costs almost nothing: when the fetch failed and the fallback tracking ref is the one used, still cut from the newer of local/last-fetched (as specced), but return the warning as data on the provision result so harness-manager can put one line on the run. If WorkspacePlace has no place for it, that is the real follow-up, and it should be filed now rather than "None filed" in Plan → Follow-ups, since D2's own mind-changer depends on it.

4. Fetch writes into the person's repository

The guardrail ("only the upstream's remote-tracking ref") is good, and V2 checks it. Two things to make explicit for the implementer: (a) fetch by the resolved remote name plus an explicit refspec, never --all or the configured default refspec, so a +refs/heads/* config can't widen what moves; (b) the URL judge must use the URL git would actually use (git remote get-url, which applies insteadOf), not a raw remote.<n>.url read, or an insteadOf rewrite bypasses the shape check. The Plan says "the URL git would use for that remote"; pin the command so it isn't read from config directly.

5. S2 (shape-only judge) — reuse, don't fork, but check the cut line

checkRemote fuses shape rules with the allowlist (remote-not-allowed, file needing allow). Plan says to "reuse checkRemote's rules; don't fork them". The clean refactor is to split checkRemote into checkRemoteShape + the allowlist step inside remotes.ts, with checkRemote calling the former, rather than passing a synthetic allowlist. That is a worthwhile refactor because this PR needs the second consumer; it should be done with the existing remotes tests as the safety net. Also note the local-path-as-file:// rule is new surface in the judge; scoping it to the caller (the fetch) keeps checkRemote unchanged for clones.

6. Scope/size

Single-PR is right. The retained spec is large for a "small" change (20 BRs, 11 checks). BR-13 (no prompt) is "by construction", BR-16 and BR-7 are existing behaviour with existing tests; they read as regression notes, not new rules. Fine to keep for history, but the implementer should not write new tests for rows marked "existing suite".

7. Smaller points

  • Divergence refusal will also hit people whose local main has a commit that was squash-merged upstream (their commit isn't an ancestor of upstream any more). That's the common real-world split. The refusal message should say that in plain words ("your main has a commit that upstream doesn't contain, for example one that was squash-merged: reset or rebase it"), otherwise it reads like a bug.
  • BR-18 (concurrent runs): the place lock is per place and "no lock over the repository" per the existing doc. Two concurrent fetches into the same tracking ref can lose a ref-lock race; BR-11 handles it, but V8 should assert the winner's comparison isn't made against a half-updated ref (read the commit after fetch via rev-parse, not from fetch output).
  • D3's price (the Lab now contacts GitHub per new run) deserves one line in the Lab/host docs and, if cheap, a per-checkout TTL so a burst of runs doesn't fetch N times. Not needed now; just note it as the follow-up if it shows up in practice.

No changes requested to D1/D3. Items 1 and 3 are the ones I'd want a decision on before implementation; 2, 4, 5 are implementer notes.


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.

Problem this spec solves

Stale local main on mapped checkouts makes coding runs branch from the wrong commit. The spec fixes that at the owning layer (provisionLocalCheckout's base callback) with a clear goal, anti-game CI, and honest evolution against FIX-1904/1906.

Verdict: The product approach is the right one for this repo. Alternatives that look simpler on paper (refuse when behind, warn-only, fetch only via remotes.allow, harness-manager-only fetch) either fail the Lab (allow: []) or recreate today's stale PRs. D3 is the unavoidable complexity: two different "what admits network" rules (listing vs allowlist). The spec documents that tradeoff well; I would not block direction on it.

What does feel heavier than the shipped behavior warrants is mostly spec surface area and a couple of implementation plan choices that could be tightened before or during the implementation PR.


Simplification opportunities (recommended, not blocking)

1. Implementation: reuse checkRemote, don't fork rules (S2)

Plan S2 calls for a new shape-only judge in remotes.ts while reusing checkRemote's rules. The reuse reviewer found checkRemote already centralizes invalid-remote logic; the real gap is bare paths → file://. Simpler shape: extract shared validation once; upstream fetch uses shape validation + synthetic allow (the URL's own host) or an internal wrapper — not a parallel public ruleset. Keeps remotes.spec.ts as the single test anchor.

2. Implementation: prefer baseCommit over a second upstream resolution (S6 / BR-20)

S1 pins setting place.repo.baseCommit at cut time. S6 extends readRunCommits with <baseRef>@{upstream} so renamed remotes still exclude the right base. That's defensible, but it re-derives upstream in harness-manager after workspace already chose the cut commit. Consider (implementation-time): when baseCommit is present on the place, exclude that commit (plus existing local/origin/<base> copies) and treat BR-20's "remote renamed to upstream" as a follow-up unless product needs it in v1. One source of truth, smaller harness-manager diff.

3. Spec bulk: BR table vs V1–V11 grid

BUSINESS-RULES and PLAN checks largely duplicate the same matrix. For implementers, maintaining both will drift. Optional spec trim: let BR ids be canonical; collapse V1–V8 into "proved by BR-*" groupings without restating outcomes.

4. Defer or soften low-yield gates

  • BR-18 / V8 (concurrent provisions on one checkout): rare; parallel fetches are acceptable per BR-11. A dedicated CI case is high maintenance — I'd document in guardrails and skip unless you've seen ref-lock pain in production.
  • BR-14 / V5 (fake-clock fetch slice): timeout behavior matters, but nested "slice of remaining budget" is easy to over-spec. Lean on existing provision deadline + one integration slow-fetch case unless a prior bug required the slice formula.
  • Triple control mandate (FAIL on today's main, FAIL with fetch removed, PASS after): valuable anti-game; if CI history already captures the red state, you could require one red/green pair instead of three permanent gates (judgment call).

5. Docs / figures

Four SVG decision panels plus mermaid plus the five-people table tell the same story. Optional: keep what-changes.svg + D3 figure (the non-obvious fork); fold D1/D2 into decision prose already in sign-off. DOCS.md duplicate paragraphs for shift-manager site vs README — one canonical block with "unlink chief of staff" note is enough.

6. Performance (accepted, but name it)

Every new run on a listed checkout with @{upstream} pays a blocking fetch on the provision path (intentional). No cross-run fetch coalescing in spec — fine for v1. If Lab churn grows, a future optimization is repo-scoped fetch dedup/TTL; not needed to solve FIX-1927.

7. Third-party git libraries

Sticking with bounded run("git", …) matches the package today; simple-git would fight argv-level guardrails (BR-9). No change suggested.


What I'd keep as-is

  • D1 (newer-of-two, refuse only on split) and BR-9 immutability of local branches/index/files.
  • Hook only in base for new branches (BR-17 / existing worktree hand-back).
  • Evolution table amending FIX-1906/1904 without reopening Lab clone policy.
  • Review command change (git log … --not main origin/main) tied to D1's lock-in.
  • D2 flagged as the likeliest flip — good honesty; offline quiet staleness is a product call, not a spec defect.

Approval

Directionally correct and implementable. The above are simplify-at-implementation and optional spec tightening suggestions; none change the signed decisions unless you want to amend BR-20/S6 or BR-18 before merge.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread specs/issues/FIX-1927/PLAN.md Resolved
Comment thread specs/issues/FIX-1927/PLAN.md Resolved
Comment thread specs/issues/FIX-1927/PLAN.md Resolved
practice, or runs gaining a place to show a provision warning. Then say so on the run, or refuse.

<a name="d3"></a>
## D3 · Listing a checkout in `localRepositories` admits fetching its own upstream; `remotes.allow` is not asked

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.

D3 is the real complexity budget for this issue (listing admits upstream while remotes.allow stays empty). The reasoning against widening Lab allowlist is convincing. Sign-off reminder: operators who need zero network on the Lab host should weigh in here — that's the one decision I'd treat as genuinely product-facing, not mechanical.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

from: fsd-claude
session: fix-1927
kind: reply

Agreed, this is the product call. It's at the top of the PR description, waiting on the owner.


Generated by Claude Code

Comment thread specs/issues/FIX-1927/BUSINESS-RULES.md Resolved
Comment thread specs/issues/FIX-1927/SPEC.md Resolved
@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-13T00:04:20.370525Z 0bae82d 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 merged commit 9cbbcf6 into main Oct 12, 2026
20 checks passed

@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: 0bae82dfc5

ℹ️ 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".

| | |
|---|---|
| **Instead of** | Fetching only when `remotes.allow` admits the upstream's URL, as the brief said |
| **Because** | Both local entry points run with `remotes: { allow: [] }`: the Lab's `fsd` profile (`teams/devteam/fsd.fsdev.config.mts`) and harness-manager's `hostForConfig`. Under the allowlist rule the case this issue is about never fetches, and adding `github.com` to the Lab is what [FIX-1904 D3](../FIX-1904/DECISIONS.md#d3) rejected: it would clone projects people add. The URL is the operator's repository config, still judged for shape before git sees it |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Keep upstream fetches inside the operator trust boundary

When an earlier coding run edits the checkout's shared remote configuration, this decision lets it redirect the next run's fetch to any shape-valid HTTPS, SSH, or file destination even though remotes.allow is empty; PLAN.md:69 explicitly acknowledges that agents can write this config. An attacker can serve a branch descended from the legitimate base, after which provisioning treats those commits as newer and silently starts the next run from them. Shape validation blocks malformed transports but does not authenticate the destination, so pin the checkout's operator-approved upstream or enforce an operator-controlled destination allowance.

Useful? React with 👍 / 👎.

| S3 | `workspace` · code docs in `src/local-host.ts` | File header (the "Existing work…" rule and the layout comment), `localRepositories` JSDoc ("no clone, no fetch"), `provisionLocalCheckout` doc, `WorkspacePlace.repo.baseCommit` ("only for a clone"), `WorkspaceRefusedError`'s reason list | — |
| S4 | `workspace` · new `test/local-host-upstream.spec.ts` | Real repositories: a bare upstream, the person's `file://` clone, a second clone that pushes. Host built with `remotes: { allow: [] }` and the clone in `localRepositories`, as the Lab builds it | BR-1 to BR-18 |
| S5 | `workspace` · `test/local-host-local.spec.ts` | Re-read the header ("no clone and no fetch") and any git-command counts. These repositories clone from a bare path, so a new run now runs one `fetch`; results don't change | BR-6, BR-17 |
| S6 | `harness-manager` · `src/commits.ts` `readRunCommits` | Also exclude `<baseRef>@{upstream}` when it resolves and `baseRef` isn't `HEAD` | BR-20 |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Preserve the original upstream when baseRef is HEAD

When baseRef is omitted and the checked-out branch tracks a non-default upstream such as upstream/feature, BR-5 records the base as HEAD, but this plan explicitly skips upstream resolution for that value. Once the run worktree exists, HEAD names the run branch, and the current readRunCommits fallback only probes refs/remotes/origin/HEAD; it can therefore report zero commits or count fetched base history as run work, and those subjects feed the harness judge. Carry the resolved base commit or original upstream into commit reporting and cover the omitted-base/custom-remote case.

Useful? React with 👍 / 👎.

Comment on lines +73 to +75
> 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

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Badge Derive the review command from the configured base

In this generic workforce-projects documentation, a checkout may use an arbitrary baseRef and upstream remote, but the proposed command always excludes main and origin/main. For a run based on release or a branch tracking upstream/main, the command either fails because origin/main is absent or displays base commits as if the run created them. Use the configured local base and its actual upstream rather than hard-coding these two refs.

Useful? React with 👍 / 👎.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants