Repository navigation
feat(workspace): FIX-1762 local workspace host and scoped projection (1/4) - #2737
Conversation
…IX-1762) A scoped mount lists its collection with the scope as a separator-bounded prefix, strips the scope inside the place, and keys every read, write, delete and claim back under it. Unscoped mounts are unchanged. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5
Adds the RunSource type (repo, files or a refusal, from the block context alone) and localWorkspaceHost: provision, save and release over a host directory, with checkpoint and restore declared as no-ops for the next slice. A remote is judged against the operator's allowlist before any git process starts; git runs with -- before the remote and GIT_ALLOW_PROTOCOL limited to the listed schemes. One bare clone per remote, made under a per-clone queue and moved into place whole; a new branch is cut after a fetch and a fresh read of the default branch, and an existing checkout is handed back without a fetch. Kept files are hydrated into project/ beside the checkout, or workspace/ when there is no repository, through a scoped mount, and saved back by flush. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5
…side the clone queue (FIX-1762) A bad projectId is refused before any checkout or git process exists, two provisions of one place at once share one checkout instead of the second failing in worktree add, and the clone identity check compares real paths. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
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. |
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: b2f1e1e2-d8a9-49c2-b777-f4f8663dc056) |
Second look + architecture pass (read-only, no edits)Reviewed Worth doing in this PR (cheap now, costly after PR 3/4 build on it)
Real, if narrow, behaviours to decide on
Architecture (refactor-while-here opportunities)
Not recommended
Priority for the implementing agent: 1, 3, 4 (shape and contract, cheapest now), then 5's wording and 7 as a PR 3 note. The rest can wait. Generated by Claude Code |
There was a problem hiding this comment.
Simplify / architecture read
Verdict: The shape matches FIX-1762 PR 1 (S1 run source + S2 scoped mount + S3 local host) on purpose — not accidental scope creep. Scoped Mount.scope is a hard dependency for kept files under projectId; splitting host from scope would ship a host that cannot do multi-tenant project files yet. A ~1.7k-line PR is still a large review surface, but the alternative (types-only PR 1) would delay the only consumer until PR 3 without much payoff.
Could this have been simpler? A few paths I considered:
| Alternative | Trade-off |
|---|---|
Third-party git wrapper (simple-git, etc.) |
Repo consistently uses execFile + explicit args; allowlist/GIT_ALLOW_PROTOCOL/-- hardening still needs custom parsing. Not a win here. |
| Smaller PR 1 (scope only, host later) | Matches PLAN only if you reinterpret the stack; PLAN pins S1–S3 together in PR 1. Host without scope cannot hydrate project/ / workspace/ correctly. |
Drop checkpoint/restore from WorkspaceHost until slice 2 |
Smaller public API; keeping named no-ops matches EVOLUTION.md and documents the seam — reasonable product call either way. |
| Move git subprocess + worktree logic into harness-manager only | Would duplicate what harness already has; D2 is explicitly “git only through workspace host.” This PR is the dedup direction, not extra complexity. |
What looks appropriately complex: remotes.ts as pure validation before spawn; exec.ts as a single mockable spawn site; serially() per clone key; hand-back vs cut-branch policy; scoped rowsOf() with prefix list() (BP-033). Tests (spawn counting, scoped listCalls, git fixtures) match the security/retry claims.
Follow-ups worth considering (non-blocking):
provisionFilesconcurrency — clone work usesserially(); kept-files provisioning does not. Two overlappingprovision()calls for the samefilesDircan both miss the cache and race onrmSync/hydrate unless callers guarantee single-flight per place.handBackidentity — inlinerealpathSync+--git-common-dirparallelsidentityFromCommonDirin harness-manager. When S4 wires harness to this host, share one definition (tiny shared helper or export from workspace) so the two paths cannot drift.hasBranchbarecatch— any git failure reads as “no branch” and may push down the refresh/cut path; narrowing to expected exit codes would avoid masking transient errors.RepoRunSourceshape —projectId/filesvalidated together at runtime; a discriminated union (checkoutOnlyvswithProjectFiles) would shrinkprovisionbranches when the API stabilizes.- Performance (later) — full
refresh()fetch on each new branch cut and syncreaddirSyncwalks increateHostPlaceare acceptable for slice 1; worth revisiting if DevForce runs get large trees or hot remotes.
Ran pnpm --filter @flow-state-dev/workspace test on this branch: 147/149 passed; two local-host-repo cases timed out in this environment (likely flake under parallel git), not assertion failures.
Direction looks right; approving with the notes above as optional tighten-ups before or during harness-manager integration (PR 3).
Sent by Cursor Automation: Review For Best Approach
| return { remote: remote.url, clone, branch, created: false }; | ||
| } | ||
|
|
||
| const defaultBranch = made.fresh ? made.defaultBranch! : await refresh(clone, remote); |
There was a problem hiding this comment.
Performance note (deferrable): Every new branch cut on an existing clone calls refresh(), which ls-remotes and then fetches all heads. That matches BR-17 (follow renamed default branch) but is the main latency cost under burst provisioning. If this shows up in practice, options are caching default branch with a TTL, or fetching only baseRef when the caller pins it — without weakening the rename behavior for the default case.
| /** The key prefix of the kept files. Required together with `files`. */ | ||
| projectId?: string; | ||
| /** The collection of kept files. Required together with `projectId`. */ | ||
| files?: RunFiles; |
There was a problem hiding this comment.
Type simplification (maybe later): projectId and files are optional independently but provision rejects unless both are set or both omitted. A discriminated union on kind: "repo" (e.g. files: undefined vs { projectId, files }) would make invalid states unrepresentable and drop the runtime pairing Error in local-host.ts. Worth it once Workforce’s projectWorkspace shape is frozen.
| const readable = identity.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[-.]+/, "").slice(0, 80); | ||
| const hash = createHash("sha256").update(identity).digest("hex").slice(0, 12); | ||
| return `${readable}-${hash}`; | ||
| } |
There was a problem hiding this comment.
Approach check: Custom URL/scp parsing instead of a git library is the right fit for this repo — you need refusal before spawn and GIT_ALLOW_PROTOCOL alignment. I would not swap this for simple-git.
Nit: exporting checkRemote only from the package root (or a workspace/security subpath) could help integration tests in PR 3 assert the same rules without reaching into ./remotes — only if you want that coupling explicit.
There was a problem hiding this comment.
Code Snob — already tight. No POC.
Read packages/workspace/src/local-host.ts, remotes.ts, run-source.ts, exec.ts, the scope changes in projection.ts, and the new specs (local-host-repo, local-host-files, scoped-mount, remotes) plus git-fixtures.ts.
A rewrite would not shrink this contract:
rowsOfkeeps two strips. An unscoped mount still strips the mount prefix off an unfilteredlist(). A scoped mount strips the pattern prefix, lists"<scope>/", and checks the separator again. One loop is the same length.placeDirandassertScopeare different checks. A place segment may not start with.or contain NUL. A scope is several/-separated segments and rejects./... A shared validator with those switches is longer.seriallychains one clone's git.provisionFilesreplaces one directory's projection. Same "drop this promise if it is still current" tail, different job. One queue helper is longer.entryKeyis already the single seam for claim, read, write, and delete.checkpoint/restoreas named no-ops, andsourcekept on the host, are the slice-2 seam and thehost.source(ctx)call the spec already pins. Dropping them changes what PR 3 builds on.- Copying
exec.tsinstead of moving harness-manager'srun()is the split this PR recorded for PR 3. The two copies already differ (signal, buffer). - The refusal table, the clone-key specs, and the "no git process" specs pin different layers. The file headers restate the README and are not a smaller host.
Head 72c01f88.
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: 72c01f8842
ℹ️ 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".
…rmed file escapes (FIX-1762) - redactRemote strips userinfo through the last @ before the path, so a credential holding an @ is never printed in a refusal. - A non-default port is part of the clone identity; :22 (ssh) and :443 (https) stay the same clone as no port. - A file:// path with a malformed %-escape is an invalid-remote refusal rather than a thrown URIError. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5
…ross hosts (FIX-1762) - A place is marked while `git worktree add` runs. A marked checkout whose tree only has tracked files missing (or no .git) is a killed add and is rebuilt; a marked tree with any other change is refused and kept. Ported from harness-manager's looksHalfBuilt / everyChangeIsADeletion. - Provisioning a place and working on a clone take a lock file on disk (src/lock.ts, ported from harness-manager's checkout lease), so two hosts or processes sharing a root wait instead of racing `worktree add -b`. The holder refreshes the lock; one left by a dead process is taken once stale. The in-process queue stays in front of it. Lock and marker names start with "." so no place segment can name over them. The place lock also serialises the kept-files hydrate. - hasBranch reads only git's "no such ref" exit as false and raises any other failure. - Real-git host tests get a 30s per-test timeout for monorepo-wide runs. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5


Requested by Jake · project thread
The problem
A coding run gets its files from one repository that the operator sets at boot. A project cannot name its own repository. A project with no repository has no place to keep its files. One project's files must never go into another project's run.
What this does
This is PR 1 of a 4-PR stack for FIX-1762. It adds the shared layer only, in
@flow-state-dev/workspace. PRs 3 and 4 stack on it. PR 2 (Workforce) goes offmainon its own.repo, optionalbaseRef), a set of kept files (files,projectId), or a refusal with a reason.Mountcan have ascope. The projection then lists, reads, writes and deletes only the keys under<scope>/. The collection does the filter (list("<scope>/")), so the run does not read other keys.localWorkspaceHost({ root, remotes: { allow }, source })givesprovision · save · release.checkpointandrestoreexist and do nothing (slice 2).<root>/.clones/. Before it cuts a new branch, it fetches and reads the default branch again. It makes the branch incheckout/. If a checkout already exists, the host gives it back with no fetch, reset or rebase.project/next tocheckout/, or inworkspace/when the project has no repository. The host fills them from one key prefix andsavewrites them back.This PR builds the right half of the figure only: the host and the scoped mount. No caller uses it yet. Harness-manager starts to use it in PR 3. The Lab wiring and the goal check come in PR 4.
What's asked of you
Nothing new. This PR implements the approved spec. One small call is listed under Engineering calls:
baseRefis optional on a repository answer.Parts worth reviewing closely
For the code reviewer.
provisionFilesinlocal-host.ts). If this process did not fill aproject/orworkspace/directory, for example after a restart, the host clears it and fills it again from the collection. If the host kept those files, a later flush could put back a file that another run deleted. The cost: edits that the run did not save before a crash are lost. This is my weakest call. Slice 2 is where uncommitted work becomes durable.remotes.ts). It refuses-…,ext::and other<x>::helpers, ssh and scp hosts that start with-, whitespace, passwords, an https login, bare paths,http,git://, andfile://unless"file"is listed. Git also runs withGIT_ALLOW_PROTOCOLset to the listed schemes and--before the remote.Fixes nothing alone. Part of FIX-1762 · spec:
specs/issues/FIX-1762/onmain· spec PR #2723 · goal check: none in this PR (it runs in PR 4,goals/devforce-lab/it-codes-in-the-projects-repository/). This PR can merge alone. Nothing calls the new code until PR 3.How to review this — altitude, what's in scope, what's deliberately unsettled
Engineering calls
baseRefis optional on a repository answer. The spec shows{ kind: "repo", repo, baseRef }. A Workforce source cannot know the remote's default branch, and BR-17 needs a fresh read. So ifbaseRefis missing, the host uses the default branch. If wrong: a caller must give a base, and the default-branch read moves to the caller.files: { collection, collectionId }. A collection ref comes from the context, and the host is built at boot with no context. If wrong: the answer shape changes before PR 4 uses it.projectIdand theproject/directory names stay as the spec pins them. The workspace layer treatsprojectIdonly as a key prefix. It does not know about Workforce. The guardrail "never says project" applies to the concept, not to these two pinned names.exec.tsis copied, not moved, in this PR. The plan says the gitrun()moves here. Harness-manager is out of scope until PR 3, so PR 3 removes its copy.sourceRepopath is not a remote. The host refuses bare paths. PR 3 must give it as afile://URL with"file"allowed, and it gets clone semantics (branches go in the host's clone, not insourceRepo). PR 3 must keep BR-22 ("unchanged behaviour") with this in mind."file"turns onfile://. No entry turns onhttporgit://... So no place can use the name.clones.minor, as PLAN S12 says. The change only adds things, and.changeset/README.mdwould allowpatch.Everything else — verification and files
Checks
alists with"a/"at the source, never reads, writes or deletes ab/orab/key, and deletes only what it hydrated. A bad scope is refusedpackages/workspace/test/scoped-mount.spec.tsfile://not listed,ext::,ssh://-o…, scpgit@-o…:, a value with a leading-, a host or scheme not listed, a bare path, a credential (not printed).GIT_ALLOW_PROTOCOL= the listed schemes.--before every remote. One clone when two first runs start at once. A renamed default branch is followed. A retry and a lost checkout do no fetch. Another branch or another remote is refused and the checkout is keptpackages/workspace/test/local-host-repo.spec.ts,test/remotes.spec.tsworkspace/. A write is in<projectId>/…after save. The next run sees it. A delete goes through. Another project's run sees nothing. A lost place is filled again. Two runs that edit one file get a conflict, not an overwritepackages/workspace/test/local-host-files.spec.tsRepository tests use real bare git repos over
file://. Every git process is counted throughvi.mockofsrc/exec.Red before green. S2: 15 of 16 new tests failed before the change. S3: all 40 host tests failed against a stub that threw "not implemented". The review fixes (same place provisioned twice at once; bad
projectIdrefused before anything is made) failed against the previous host.Negative controls (I broke the property, then restored it):
/and no re-check →ab/leaks, 2 fail. Scope not used on writes and deletes → 5 fail.filegate off → only "file:// not listed" fails.GIT_ALLOW_PROTOCOLnot limited → only "limits transports" fails. No--→ only "puts --" fails. No clone lock → only "one clone at once" fails. Default branch fixed tomain→ only "renamed default branch" fails. Retry fetches → only "retry never fetches" fails. Repository identity check off → only "another remote" fails.no-sync-back) → 7 fail. Mount not scoped → 8 fail. Old handle used after the place is lost → only "lost place" fails. First run seeded → 5 fail.project/put insidecheckout/→ only thegit statustest fails.In each case all other tests stayed green.
Runs on the pushed head:
pnpm --filter @flow-state-dev/workspace test→ 8 files, 149 tests pass.pnpm --filter @flow-state-dev/workspace typecheckpasses. The tests also typecheck withtsc. Dependents:pnpm --filter @flow-state-dev/tools typecheckandpnpm --filter @flow-state-dev/claude-code typecheckpass, andtools testpasses (470).Files
src/run-source.ts(new) — S1 types.src/types.ts,src/projection.ts—Mount.scopeand the scoped list, read, write, delete and claim.src/remotes.ts(new) — allowlist, clone key, redaction.src/exec.ts(new) —run()with a timeout and env.src/local-host.ts(new) —localWorkspaceHost,WorkspaceRefusedError.src/index.ts— exports.README.md— "Scoping a mount to one key prefix" and "Workspace hosts and run sources" (DOCS.md workspace section), plus API rows..changeset/workspace-host-and-scoped-mount.md—minor.test/*— new specs, and the fake collection now filterslist(prefix)like the engine does.🤖 Generated with Claude Code
https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5
Generated by Claude Code
Note
High Risk
Introduces git remote parsing, child-process execution, and tenant isolation via scoped collection access—security- and data-integrity sensitive paths with deliberate tradeoffs (e.g. rebuilding unsaved kept files after restart).
Overview
Adds the shared
@flow-state-dev/workspacelayer for FIX-1762: a local workspace host that turns a run source answer into an on-disk workspace, plus scoped mounts so multi-tenant file collections only hydrate and flush one key prefix.Scoped projection.
Mountgains optionalscope. Hydrate/flush/list/read/write/delete and claims all use keys underscope/…, withcollection.list("scope/")at the source so other owners’ rows are never read. Invalid scopes are rejected viaassertScope.Run source & host. New types describe repo runs (optional
baseRef, optional kept files viaprojectId+files), files-only runs, or explicit refusals.localWorkspaceHost({ root, remotes, source })implementsprovision·save·release(and no-opcheckpoint/restore). Repo runs get shared bare clones under.clones/, a per-run branch incheckout/, and kept files inproject/outside git; files-only runs useworkspace/ascwd. Remotes are validated inremotes.tsbefore any git runs, with allowlisted hosts/schemes, credential redaction, andWorkspaceRefusedErroron failure. Retries reuse existing checkouts without fetch/reset; lost directories rebuild kept files from the collection.Docs, exports, a minor changeset, and broad tests (scoped mount, remotes, files-only host, real-git repo host with process mocking) ship with the implementation. Nothing in-repo calls the host yet—that wiring is later PRs.
Reviewed by Cursor Bugbot for commit 72c01f8. Configure here.