Jujutsu support after V2: direction and scope for a focused stack

[omarshaarawi]

@juliusmarminge when you closed #2461 you said to port jj to V2 once #2829 merged, and to ping you. #2829 merged on Oct 2. Since then you closed #13816 for missing approval, and #16380 has had no commits since Oct 6 and now conflicts with main. I'm picking this up and will stay on it through review. Before I write code, I'd like your sign-off on the direction and scope below, per the prior-approval rule in CONTRIBUTING.

Every PR in the stack keeps the original authorship from Jacob Sanderson's #11373, #11382, #11383 and #11384, knocking4thcylinder's #13816, and gergesh's #16380. The tracking issue is #1126.

Scope

In scope:

• Colocated jj repositories only. jj manages the working copy and git stores the objects in the colocated .git, so diffs, checkpoint refs and hosting keep using git. When a jj repo has no reachable .git or jj is older than 0.42, the driver reports the repo as unsupported and gives the reason. It never falls back to treating the repo as git.
• The features the clients already have, implemented with jj commands. That covers status, bookmarks wherever the UI says branches, jj workspaces wherever it says worktrees, commit, push, PR create and checkout, checkpoints, and review diffs. A jj repo runs jj for each of these, and none of them is a disabled git button.
• Web, desktop and mobile terminology and controls. The only wire change is an optional vcs: { kind, unsupportedReason? } field on status. The server omits it for git, so a newer client treats an older server's status as git.

Out of scope unless you want it:

• Converting an existing git repo with jj git init --colocate. It's a new workflow, and your close note on feat(jj): support colocated Jujutsu repositories #13816 named it. It can be its own proposal.
• Non-colocated repositories.
• jj-specific UI such as the op log, evolog, split, squash and undo. Each needs product design first.

Architecture

This section answers the four blockers from your second review on #2461.

A typed jj service. VcsDriver stays the generic driver for detection, files, remotes, ignores, checkpoints and diff preview. jj gets its own service, which includes everything in VcsDriver and adds jj operations. Code that needs jj behavior yields JjVcsDriver directly, so the compiler enforces it and no capability flag is involved.

export class JjVcsDriver extends Context.Service<
  JjVcsDriver,
  VcsDriver["Service"] & {
    readonly capabilities: VcsDriverCapabilities & { readonly kind: "jj" };
    /** Fails with VcsUnsupportedOperationError when jj is missing, below 0.42, or not colocated. */
    readonly ensureUsable: (
      operation: string,
      cwd: string,
    ) => Effect.Effect<JjRepoPaths, VcsError>;
    /** `@`, after snapshotting the working copy. */
    readonly currentChange: (cwd: string) => Effect.Effect<JjChange, VcsError>;
    readonly changeAt: (cwd: string, revset: string) => Effect.Effect<JjChange | null, VcsError>;
    /** `heads(::@ & bookmarks())::@`, newest first. A push or PR acts on these changes. */
    readonly currentSegment: (cwd: string) => Effect.Effect<ReadonlyArray<JjChange>, VcsError>;
    readonly listBookmarks: (cwd: string) => Effect.Effect<ReadonlyArray<JjBookmark>, VcsError>;
    readonly listWorkspaces: (cwd: string) => Effect.Effect<ReadonlyArray<JjWorkspace>, VcsError>;
  }
>()("t3/vcs/JjVcsDriver") {}

The workflow layer above the drivers stays as it is. Git and jj each implement VcsWorkflowOps, which already defines every action the clients send, and the workflow service picks an implementation per call from the detected kind. When a call names a workspace path, the path's kind wins over the project's, so a git worktree created before jj detection stays removable. Op log and evolution methods go on JjVcsDriver when a feature needs them, and not before.

Capability flags. Nothing on main reads supportsWorktrees, supportsBookmarks, supportsAtomicSnapshot or supportsPushDefaultRemote. I'd delete them in the first PR instead of adding jj values to flags with no API behind them. kind and ignoreClassifier stay.

Ignore rules. JjVcsDriver.filterIgnoredPaths runs git check-ignore --no-index against the colocated git dir and reports ignoreClassifier: "git-compatible-fallback". In a colocated repo jj and git read the same .gitignore files, so the result matches jj's own rules. No other jj code calls git for ignores.

Effect services. The driver uses FileSystem, Path and the shared VcsProcess. Every jj call sets git.abandon-unreachable-commits=false, so a background read can never abandon a commit. Reads that don't need a fresh snapshot pass --ignore-working-copy.

Landing plan

Each PR targets main, merges on its own, and runs focused tests against a real jj binary that CI installs with a setup-jj action. Line counts come from the #16380 diff and include tests. The server-side jj code alone is about 9k lines, so I split it into five PRs.

1. The jj driver, detection, process wrapper and version check, plus deleting the unused capability flags and adding setup-jj. Auto-detection keeps preferring git, so users see no change.
2. Checkpoints and review diffs, wired through CheckpointStore.supportsCheckpoints in orchestration-v2/CheckpointService. About 1.6k lines.
3. Status, bookmarks, workspaces and remotes, routed by kind, and jj-first auto-detection for colocated repos. jj repos start behaving as jj here. currentChange snapshots the working copy, so every status poll of an open jj repo spawns jj. This PR will include a measured comparison against git's poll cost, and will poll with --ignore-working-copy if snapshotting on every poll costs too much.
4. Commit, push, PR create, PR checkout and stacked actions. PRs 3 and 4 together are about 6.6k lines.
5. Web, desktop and mobile terminology, the jj init option, and the unsupported-repo state. About 1.4k lines.

Ask

Please approve or decline this direction and scope. One design point needs your call before PR 1. Your second review on #2461 asked for "a typed JJ extension service or extension registry shape". This proposal uses the first. If you want a registry of per-kind extensions instead, I'll build that.

[THEjacob1000]

@juliusmarminge @omarshaarawi this is mostly my original #11373 to #11384 stack, rebased onto current main and corrected against what's changed since and the review feedback on #13816 and #16380, now up as draft PRs: #20749 #20750 #20751 #20752 #20753 #20754 #20755 #20756. It follows Omar's plan here, and knocking4thcylinder's and Omar's fixes are credited on the commits that use them. Omar, this isn't meant to step on you picking it up, happy for you to drive review or take over any of the PRs.

Where it differs from the proposal:

• 8 PRs, not 5. The GitManager extraction that lets jj reuse text generation and PR creation is its own behaviour-neutral PR (refactor(server): extract the change-request step #20752), so the git side can be checked without jj in the diff. jj-first detection moved out of PR 3 into a one-line last PR (feat(server): prefer jj in colocated repositories #20756), so 1 to 7 land dormant and any prefix is safe to merge. feat(server): clean up idle jj workspaces #20755 adds idle jj workspace cleanup to match worktree cleanup, it's droppable.
• Minimum is jj 0.46, not 0.42. 0.46 changed workspace forget/remove and push remote patterns, and supporting both meant compat code we'd only delete later.
• No jj init option in the clients, conversion stays out of scope like the proposal says.
• The unused capability flags are still there. Deleting them touches shared git code, so I left them for a separate PR unless you'd rather it go in feat(server): add the jj driver and version checks #20749.
• Status polling: a jj local refresh spawns 4 jj + 2 git processes, background fetch goes into private refs/t3/remotes/ so polling never moves a bookmark.

Typed JjVcsDriver service as proposed, not an extension registry. Looking for a yes/no on scope before I mark any of them ready.

[omarshaarawi]

@THEjacob1000 did a pass over all 8 against jj 0.46 in scratch colocated repos. Left comments on each PR. I didn't run the repo's test suite, only jj itself. Short version:

Must fix

• feat(server): add jj commit, push and PR workflows #20753: commit with @ mid-stack picks main as the bookmark, moves it, and pushes it. The commit message overwrites a description already on @. Auto-pull's jj new <bookmark> orphans edits made between the clean check and the new.
• feat(server): clean up idle jj workspaces #20755: cleanup's jj git fetch moves the user's local main, and jj workspace remove deletes files over 1 MiB. It also drops the .jj keep guard while detection is still off, so a git worktree with a .jj gets .jj/ deleted. That breaks "any prefix is safe to merge". feat(server): route jj status and workspace operations #20751 has ungated .jj checks too.
• feat(server): add jj checkpoints and review diffs #20750/feat(server): prefer jj in colocated repositories #20756: restoring a checkpoint captured before activation leaves a t3 checkpoint commit visible in jj log for good.
• feat(server): route jj status and workspace operations #20751: jj failures in status come back as a clean repo.
• feat(web,mobile): use jj terminology and shared vcs actions #20754: Publish stays enabled for unsupported repos, and the server creates the GitHub repo before it finds out.

I'd split #20755 out of the stack. Nothing else depends on it and it carries two of the bugs above.

Changing my position on missing jj. The proposal says a jj repo with jj missing or too old is reported unsupported and never falls back to git. I had that wrong. 0.46 colocates by default, so anyone who has ever run jj git init in a repo loses diffs, checkpoints and history there the day #20756 lands if jj isn't on PATH (or is older than 0.46). The only opt-out is .t3code/vcs.json, which jj then snapshots into their change and pushes. I'd rather a colocated repo without a usable jj fall back to the git driver with a notice saying why. @juliusmarminge @maria-rcks flagging since it's a change from what I proposed.

Poll cost, since I said I'd measure it. 300-file repo, mean of 10 runs: jj commands take 8-11 ms each against 1-3 ms for git. A local refresh is about 120-140 ms on jj vs about 20 ms on git. Segment and workspace list each run twice per refresh, so there's an easy cut. 400 snapshotting polls racing 80 agent commits produced no divergence.

Main is about 300 commits ahead. #20752 is the risky rebase: a mechanical one drops either #20412 or #19605, because the extracted step can't express either change.

[THEjacob1000]

@omarshaarawi thanks for actually driving these against jj, every must-fix item reproduced for me too. All 8 are rebased on current main and force-pushed, with each fix in the PR it belongs to and a real jj 0.46 test that fails without it.

On missing jj I went with your version. A colocated repo where jj is missing, older than 0.46 or broken now falls back to git with a notice that includes jj's actual error line. Non-colocated repos stay unsupported. A git linked worktree with jj git init --colocate inside it also falls back to git, that one was showing as unsupported before.

The bigger changes from your review:

• feat(server): clean up idle jj workspaces #20755 moved to the top of the stack so it can wait. Cleanup fetches into refs/t3/remotes/, refuses workspaces with unsnapshotted, oversized or ignored files or a described @, and keeps the .jj guard unless the repo is detected as jj.
• feat(server): add jj commit, push and PR workflows #20753 fixes all three: no main mid-stack, existing @ descriptions kept, pull rebases @. I also found fresh workspaces got a t3:<ref> description that would have become every first commit message, that's gone.
• refactor(server): extract the change-request step #20752 is re-extracted from main into sourceControl/ChangeRequestStep.ts, so fix(server): a branch on the only remote is not a fork when there is no origin #20412 and perf(server): skip unused diffs for user-written commit messages #19605 are both in.
• The rest (feat(server): add the jj driver and version checks #20749, feat(server): add jj checkpoints and review diffs #20750, feat(server): route jj status and workspace operations #20751, feat(web,mobile): use jj terminology and shared vcs actions #20754) are fixed as you described, details are in each PR.

I kept JJ_REPOSITORY_DETECTION_ENABLED and its off paths on purpose since a user toggle seems worth having later.

For git parity I compared process spawns for plain git on main vs the stack across 68 cases (status, workspace create/remove, thread launch, linked worktrees) and they're identical down to the arguments. A jj refresh is 5 jj + 2 git now. I also tested by hand on web and the Android emulator with real agent turns, screenshots are going into the PR bodies.

Also worth noting that I'm probably going to be only doing a rebase every 1-2 days, so anything "out of date" you can assume will be updated with conflicts resolved within 48hrs (probably for the next fortnight, whilst we wait for attention from maintainers)

[THEjacob1000]

Further update: I've actually gone through and conducted quite a bit of testing and attached the relevant screenshots to the PRs now in <details> blocks. I didn't originally do so because was waiting for approval to proceed before polishing, but just so I'm not wasting your time I've gone ahead and done that. Hopefully that helps in getting this through as I can't see myself using t3code properly till this is actually supported. Especially since after there's first class git-like support, we can take the steps necessary to get agents to use JJ how it's meant to be used which would be great. Also, my intent was to keep force pushing to keep 1 change per PR as it just makes it way easier to do the rebasing and keeps the history clean, if you find this problematic Omar please lmk as GitHub doesn't have stable tracking for the change IDs that JJ uses

[omarshaarawi]

@THEjacob1000 I reran everything on the 20:13 heads against jj 0.46. Most of it holds up. Notes are on #20751, #20753, #20754, #20755 and #20756. #20749, #20750 and #20752 have nothing left from me.

Verified fixed by running it:

• tracked fetch no longer touches main. I tried it diverged and behind, and with odd remote names
• main no longer gets pushed from mid-stack
• pull keeps @'s change id and description
• fresh workspaces have no t3:<ref> description
• a late 2 MB untracked file, a late edit, and a late description all block workspace removal
• broken, missing and too-old jj all fall back to git, and the notice text is right
• checkpoint recovery leaves no stray heads
• refactor(server): extract the change-request step #20752 has fix(server): a branch on the only remote is not a fork when there is no origin #20412 and perf(server): skip unused diffs for user-written commit messages #19605

On force-pushing: fine by me for a draft stack, and git range-diff covers what I need. A short per-push note listing which commits changed would save each reviewer a pass.

On JJ_REPOSITORY_DETECTION_ENABLED: I'd still drop it. It's a const true with 13 dead branches in 9 files, and none of those off paths have tests, so they'll rot before anyone builds the toggle. If a toggle is wanted later, it should be a setting read at the one detection point in VcsDriverRegistry, not a flag spread across nine files. Maintainers' call, though.

Two numbers to correct for the PR bodies. A remote status tick is 7 jj + 2 git, not 5 + 2 (5 + 2 is the local tick), and a cold status() is 9 jj + 4 git. On a 300-file repo here that's about 80-105 ms per tick for jj vs about 33 ms for git. I also couldn't find the 68-case spawn comparison in the tests. If it's a script, putting it in the PR would let others rerun it.

[THEjacob1000]

@omarshaarawi thanks for rerunning all of it, everything from your recheck is addressed and force-pushed. Everything except #20752 changed (it only rebased), and each behaviour fix has a real jj 0.46 test I ran red without the fix.

You were right about JJ_REPOSITORY_DETECTION_ENABLED, it's gone with all the off paths. The only switch is detection in VcsDriverRegistry: commits 1 to 6 only register git, and #20756 adds jj there. I checked each of 1 to 6 in a real colocated repo with no pin and they all pick git with zero jj processes.

#20751:

• Behind is bookmark..remote now, so your main <- x1(@) <- x2[feat] case is 0/0, and empty remote commits count. Ahead still counts from @, since moving it to the bookmark hid unpushed agent commits and disabled Push.
• jj never auto-pulls, the kind check runs before any jj call.
• -- before every positional remote.

#20753:

• Typed message wins, then the existing @ description, then generated, and the bookmark name comes from the same text.
• Pull uses -s @ and pulls a dirty @ when nothing's ahead. It still refuses when there are local commits ahead, otherwise an agent's jj commit fell out of the working copy. A clean pushed @ ends up on a new empty child of the pulled commit, and an amended pushed commit says to push rather than rebase.
• The two jj diff -r @ calls were already sequential, Effect.all without concurrency defaults to 1, so I left that.

#20754:

• The fallback notice is in ChatView's banner lane next to the unsupported reason, dismissible per repo on web and mobile, and comes back if the notice text changes.
• The matrix is named states now, including plain git, the git fallback and jj. Mobile no longer enables Create PR while Push is blocked on a dirty jj working copy.
• Mocks are down from 188 to 140 (72 to 46 in vcs.render.test.tsx) and the deep relative imports are gone. That's a partial cut, a lot of what's left still mocks app modules (preferences, entities, ThreadComposer, ThreadFeed and so on), not just native ones. Going further meant rendering the real app screens under vitest, which falls over on react-native-svg's Flow source, so I stopped there.
• Subagent rows read the noun from context instead of subscribing each, the copy and MCP descriptions are fixed, and the server bits moved to the PRs they belong to. The Workspaces section moved to feat(server): clean up idle jj workspaces #20755 and supportsCleanupBaseBranch is gone.

#20755:

• Cleanup skips the stale retry and keeps a stale workspace with "workspace is stale". I left the status poller alone since it only runs while the thread's open, happy to change that too if you think it should.
• tracked-changes matches git now, but nothing's deleted until forget succeeds, so a refusal or failed forget leaves the workspace untouched.
• -- before the remote.

#20756:

• A successful probe gets rechecked when jj's path or mtime changes, with a 5 minute TTL as a backstop.
• The fallback notice mentions the detached HEAD, an unreadable .jj/repo pointer shows the unsupported reason, and the vcs.json docs say jj tracks and pushes the file.

Re-measured at the tip: a local tick is 4 jj + 2 git, a remote tick is 6 jj + 2 git, and a cold status() is 13 jj + 10 git, where 11 of the cold ones are cache fills (version probe, remote and default bookmark lookups, PR lookup). jj git remote list runs twice on a cold read, I haven't chased that down yet.

The 68-case comparison is a script outside the repo, here's the bundle with exact rerun commands: https://evidence.jacobdevelops.com/pr-evidence/2026-10-21/afbb650cf11a-t3-jj-parity-harness.tar.gz (README: https://evidence.jacobdevelops.com/pr-evidence/2026-10-21/cce833ff585a-README.md).

Also right about the screenshots, the "tip" actions one was a copy of commit 6's and nothing showed the fallback notice. I'm recapturing on web and Android and will swap them into #20754 and #20756.

[jeprecated]

I've proposed a much smaller opt-in alternative in #21171, in case native jj takes a while. Happy to drop it if your stack lands first.

[omarshaarawi]

👀