Skip to content

fix(harness-manager): keep one person's runs in two organizations apart (FIX-1926) - #3199

Merged
jhoffner merged 1 commit into
mainfrom
claude/project-thread-umr44o
Oct 13, 2026
Merged

jhoffner merged 1 commit into
mainfrom
claude/project-thread-umr44o

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

The problem

A person who works in two organizations on one host got the same coding-run checkout folder and the same git branch in both, for the same board and issue-phase, when the request had no tenant header. The second organization's run opened a tree that held the first one's commits and uncommitted work. A pull request on the shared branch could satisfy the other run's completion check, so one organization's run could report success on another organization's work.

What this does

The checkout folder and the branch now include the organization the request was admitted under (the verified one on the request identity, not a header). The layout is <tenant>/<org>/<user>/<board>/<issue>--<phase>, and the branch is conductor/ plus the same segments.

A run that started before this change keeps its place. Its run record names the older branch, and the manager continues on that branch and that checkout, so a retry does not lose its work. The run record is kept per user and organization, so another organization never reads it and never gets the older place through it.

What's asked of you

Nothing here is yours to decide. This is a bug fix; this PR is the review.

Parts worth reviewing closely

  • packages/harness-manager/src/workspace.ts → locationFor: the bridge for in-flight runs. It uses the older derivation only when the run's own record already names the older branch.
  • packages/harness-manager/src/manager.ts: the open step now reads the run record before it derives the branch. The provision step derives from the branch the open step chose, so the two steps always agree.
  • packages/harness-manager/src/run-owner.ts → runPrincipal: reads orgId from ctx.request.identity (the user-scope identity has no org) and refuses a request with no organization, as it already does for a missing user.

Links

Linear: FIX-1926. Found while building FIX-1906 (#3185), under epic FIX-1903. Bug route, so no spec. This PR merges.

Engineering calls
  • Org segment between tenant and user. Each is its own digest segment, so the derivation stays injective (a test swaps org and user ids).
  • Run owner record unchanged. The owner record on an organization's board carries no org: the row belongs to one organization's board, so the owner's org is the board's. Old owner records keep matching (BP-030).
  • Two organizations that already shared one older tree before this change keep sharing it until those runs finish. Separating them mid-run would orphan one of them, which is the harm the bridge exists to prevent. New runs never share.
  • minor changeset. RunPrincipal now requires orgId, and new runs derive new paths. A host that builds a RunPrincipal itself has to pass the org.
  • fixed-board-parity.snapshot.json was regenerated once, deliberately. The values it held before are now pinned literally in org-place.spec.ts as the place an in-flight run keeps. derivation-snapshot.json is unchanged: board-id.spec.ts compares it against the older derivation, which in-flight runs still use.
Verification
  • New test/org-place.spec.ts runs the real manager on one store:
    • one user, two orgs, no tenant, same board and issue-phase: different checkouts, branches and run records, and the first run's commit is absent from the second tree. Red without the org segment (checked by removing it: "the second organization's run was handed the first one's checkout").
    • a run whose record names the pre-change branch and checkout continues there. Red without the bridge (checked: the run moved to the new path).
  • Unit tests in workspace.spec.ts: two orgs derive different paths and branches; locationFor picks the older place only on a matching record.
  • pnpm vitest run in packages/harness-manager: 266 passed. labs/conductor: 154 passed. harness-manager typecheck clean; goals tsc --noEmit clean.
  • packages/shift-manager: one failure in command.test.ts because its pages are not built in this container ("the pages are not built at …/dist-client"); not related.

🤖 Generated with Claude Code

https://claude.ai/code/session_0155MhTh7kAjLFSg9Wq6ggab


Generated by Claude Code


Note

Medium Risk
Changes filesystem/git isolation and requires org on every new run; migration logic must keep in-flight runs on legacy branches, and callers building RunPrincipal must supply orgId.

Overview
Coding-run checkout paths and git branches now include the organization the request was admitted under, so the same user working in two orgs on one host no longer shares a worktree or branch for the same board/issue-phase.

RunPrincipal requires orgId, resolved from ctx.request.identity (not user-scope identity); requests without a resolved org are refused like missing user id. Path/branch layout becomes <tenant>/<org>/<user>/… with matching conductor/… refs.

In-flight compatibility: locationFor keeps the pre-change (orgless) derivation when the run record’s stored branch matches the old shape; the manager reads the record before deriving branch/place so open and provision steps stay aligned. Docs, goal checks, and tests (including new org-place.spec.ts) reflect the layout and migration behavior.

Reviewed by Cursor Bugbot for commit 90ed00b. Configure here.

…rt (FIX-1926)

The coding run's checkout folder and branch were derived from the tenant and
the user, with no organization. The tenant is optional and header-supplied, so
one user in two organizations on one host, with no tenant header, derived one
checkout and one branch for the same board and issue-phase.

The organization the request was admitted under is now a segment of the place
and the branch. A run whose record already names the branch derived without it
keeps that branch and its checkout, so in-flight work is not stranded.

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

linear-code Bot commented Oct 12, 2026

Copy link
Copy Markdown

FIX-1926

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

Request Review

@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: 71156d32-6dcf-43d4-97fd-71ca6f98400d)

@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:01:34.759262Z 90ed00b 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.

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (read-only review; no changes pushed)

Verdict: the approach is sound and proportionate. Org as its own injective segment is the right fix, and runPrincipal reading orgId from the request identity (not user-scope, not a header) matches BP-031. The findings below are refinements, none blocking. Ordered by value.

1. The bridge is a permanent legacy branch with no exit (worth a decision)

RunLocation.orgless + locationFor + the principalSegments fork keep the pre-change derivation alive forever. Nothing says when it can be deleted, and the two-orgs-already-sharing-one-tree case (acknowledged in the PR) stays shared until those runs finish.

  • Suggest: a one-line comment on orgless / locationFor naming the removal condition (e.g. "delete once no run record on a live board names an orgless branch"), so it doesn't fossilize. Without it the flag reads as a supported shape.
  • Alternative considered: pin to the record's branch + workspacePath directly (like pinned already does for remote/baseRef/filesOnly) instead of re-deriving via a flag. That would make every future derivation change bridge for free and drop the orgless field from the public RunLocation type. I'd still keep the current approach here: the recordedBranch === branchFor(orgless) equality check is what stops a stored branch string from being trusted blindly, and the provision step's locate(...).cwd !== state.workspacePath guard relies on a derivation. So this is a note, not a request. If a second derivation change ever lands, revisit and generalise at that point rather than now.

2. orgless leaks onto an exported type

RunLocation.orgless?: true is a legacy discriminator on a type that branchFor, checkoutPathFor, placeFor all accept, so any caller can set it. The doc says "never set for a new run", but nothing enforces it. Cheap tightening: only locationFor constructs it (it already does). Tests in board-id.spec.ts set it directly, which is fine, but consider not re-exporting beyond the package barrel if it currently is. Check src/index.ts; if RunLocation is exported, orgless becomes API (and a minor changeset already covers the RunPrincipal break, so mentioning it there is free).

3. Two patchState calls in the open step

manager.ts now does patchState({issue, phase, topic, taskId, attempt}), reads the row, then patchState({ branch }), then another patchState({...pinned, ...}). The branch patch could be folded into the existing second patch (the pinned/place/recordedPlace one) so state is written once after derivation. Pure tidy-up, but it also removes a window where state has issue/phase but no branch.

4. Stale comment in manager.ts

The block "One location, three derivations. ... Building them from one object is what stops a discriminator reaching one and missing another" (~L1881) now sits above only const topic = ...; the location object and branch it describes were moved ~25 lines down. The invariant it states is still the important one (and is now more load-bearing, since open and provision derive from locationFor separately, both from the branch). Move or reword it next to locationFor, and say there that open and provision must agree because both go through locationFor with the same branch.

5. Provision step agreement relies on state.branch

provision derives via locationFor(..., state.branch). That is correct because open patches branch before returning. A test pinning exactly that (open on an orgless record, then provision, same cwd) exists in org-place.spec.ts, which is good. Worth one more case: record names an orgless branch but for a different issue/phase/epic than the topic (corrupt/mismatched record). recordedBranch === branchFor(orgless) would fail the equality and fall through to the new derivation, which is the safe outcome; a one-line test would lock that.

6. Docs surface

labs/conductor/README.md is updated. I found no other doc stating the <tenant>/<user> layout (the tools README and apps/docs/docs/tools/bash.md hits are a different workspace layout). Two goal docs (goals/devforce-lab/it-commits-from-the-seats-own-file/goal.md) show conductor/t0/<user>/... as historical run evidence; leave them, they're dated entries.

Not worth doing

  • Splitting runPrincipal into a separate org resolver: one caller path, three lines.
  • Adding orgId to RunOwner: the PR's reasoning (board belongs to one org) holds, and it keeps BP-030 dual-read free.

Security/isolation reading: the org comes from the verified request identity; per-segment encoding keeps path derivation injective; empty/missing org is refused loudly. I found no path where a caller-controlled value picks the org.


Generated by Claude Code

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Another round soon, please!

Reviewed commit: 90ed00b38c

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

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

Files: packages/harness-manager/src/workspace.ts (principalSegments, RunLocation.orgless, locationFor, branchFor, placeFor), src/manager.ts (open and provision), src/run-owner.ts (runOwnerFor, runPrincipal), test/org-place.spec.ts, test/workspace.spec.ts, test/board-id.spec.ts, test/claim-host.ts, labs/conductor/README.md, .changeset/org-in-run-checkout.md.

locationFor is the one comparison: the recorded branch equals branchFor of that place with orgless. principalSegments is the one fork, so the path and the branch stay one derivation. A second segment function repeats tenant, user, epic, and leaf. Passing the recorded branch into branchFor and placeFor separately is how open and provision can disagree.

The ternary is the two recorded orders (tenant, org, user, or tenant, user). A conditional spread of the org segment is more lines. The two locationFor calls are the two steps: open reads the row, provision uses state.branch. A helper that takes epic, issue, phase, and branch spends the function to save the braces.

runPrincipal's organization check matches the user check. The wording differs (user identity / principals, organization / organizations), so one throw helper is the same length. runOwnerFor leaves organization off the owner record; the board is the organization. The request-identity comment is why orgId comes from ctx.request.

putRecord is the scoped write the in-flight test uses; records is the read. That file is one handler per action. inOrg keeps the default organization's session id. Always prefixing the id is one line shorter and changes every session id in the harness.

The swap test is the separate-digest check. locationFor's unit cases are null, undefined, the new branch, and the old branch. org-place.spec.ts is the manager on one store. The snapshot loop passes orgless because derivation-snapshot.json is the older derivation.

The orgless field comment is the warning that setting it on a new run shares a checkout. locationFor's second paragraph is why another organization's run cannot inherit that place through the record. The README paragraph is the path. Folding the lone patchState({ branch }) into the pin write is two lines and changes when branch is committed.

A rewrite would not shrink this contract.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@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-1926)

Problem framing: One person on one host in two organizations must not share checkout, branch, or conflated git state. That is a real isolation gap: the framework partitions boards/records by org, but derived filesystem/git paths did not.

Verdict on approach: Putting orgId on RunPrincipal, encoding it as its own segment (same as user/tenant), and reading it from ctx.request.identity (admitted org, BP-031) is the straightforward fix and matches how the engine already thinks about org (createExecutionMetadata). I would not try to infer org from board metadata alone without proving it is the same trusted admission path.

Where complexity landed: Almost all of the extra surface area is backward compatibility for runs that already have a pre-org branch on the record — RunLocation.orgless plus locationFor(..., recordedBranch) comparing against branchFor(orgless). That is defensible (retries must not strand work), but it is also the main place a simpler design could have lived:

Alternative Trade-off
Current (branch equality) No migration; one function owns the rule; inference edge cases (e.g. branch missing but workspacePath still legacy) are implicit.
Explicit placeVersion / legacyPlace on the run record Slightly more storage and a write on open; clearer than string matching; easier to test partial records.
Cutover only (no compat) Simplest code; unacceptable for in-flight harness retries unless you accept stranded trees.

I am not sure the branch-equality approach is wrong for production, but if this compat window is long-lived, an explicit record field may age better than keeping orgless on the public RunLocation type (tests can call branchFor({ orgless: true }) and bypass the “never for new runs” invariant).

Smaller simplifications (optional, not blockers):

  • Validate org with isValidOrgId from @flow-state-dev/core in runPrincipal (same rule as transport/engine) instead of typeof + non-empty.
  • On the open path, hoist one runPrincipal(ctx) instead of calling it again for locationFor (owner check already computed principal in the same block).
  • Consider merging the post-read patchState({ branch }) into the next patch to avoid an extra sequencer write (minor).
  • locationFor always computes branchFor(orgless) when recordedBranch != null; a cheap shape check might skip that on the common new-branch path (micro-optimization only).

What reads well: org-place.spec.ts + claim-host.inOrg() is the right level of proof (two orgs → two trees, legacy record → same checkout). Conductor README path diagram update is clear. Reusing harness-manager encodeSegment (not engine’s unrelated homonym) is correct.

Tests: I ran pnpm --filter @flow-state-dev/harness-manager test locally and saw 7 failures (mostly lock/path ENOENT around workspace provisioning tests). That may be environment flake rather than this PR; worth confirming CI on your side.

No changes requested for merge — this is feedback on simplification and alternatives. Happy to approve on a follow-up pass if you want a clean approve after addressing any of the optional items.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

Comment thread packages/harness-manager/src/manager.ts Resolved
@jhoffner
jhoffner merged commit 2375ef5 into main Oct 13, 2026
21 of 23 checks passed
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