Skip to content

Commit b7d33af

Browse files
t3dotggclaude
andauthored
perf(server): macOS worktrees open 2x faster by cloning a cached checkout (#32927)
Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent f26623f commit b7d33af

19 files changed

Lines changed: 1766 additions & 27 deletions

‎apps/mobile/src/features/settings/ThreadSettingsSections.tsx‎

Lines changed: 44 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import { AutoSettleDaysField } from "./components/AutoSettleDaysField";
99
import { ScreenScrollView as ScrollView } from "../../components/ui/ScreenScrollView";
1010
import { useAtomSet, useAtomValue } from "@effect/atom-react";
1111
import { AsyncResult } from "effect/reactivity";
12+
import type { ComponentProps } from "react";
1213
import { View } from "react-native";
1314
import { useSafeAreaInsets } from "react-native-safe-area-context";
1415

@@ -45,7 +46,20 @@ export function SettingsLabsRouteScreen() {
4546
contentContainerStyle={{ paddingBottom: Math.max(insets.bottom, 18) + 18 }}
4647
>
4748
<ToolCallVisibilitySection />
48-
<BetaSettingsSection />
49+
<MachineBetaSection
50+
title="Linked environments"
51+
icon="link"
52+
capability="peerLinks"
53+
setting="linkedEnvironmentsEnabled"
54+
description="Let agents on a machine work on your other machines, and theirs on it. Turn it on for each machine. While off, nothing new starts over a link; running tasks finish."
55+
/>
56+
<MachineBetaSection
57+
title="Fast worktree checkout"
58+
icon="bolt.circle"
59+
capability="fastWorktreeCheckout"
60+
setting="fastWorktreeCheckout"
61+
description="On a Mac, clone new worktrees from a checkout cached in the T3 home folder instead of writing every file. Uses Git’s normal checkout when it can’t. Turning it off deletes the cache."
62+
/>
4963
<LegacySettingsSection />
5064
</ScrollView>
5165
</SettingsScreen>
@@ -228,48 +242,64 @@ export function NewThreadSettingsSection() {
228242
);
229243
}
230244

231-
/** Per machine, since each machine's own setting decides whether it links and answers links. */
232-
function BetaSettingsSection() {
245+
type MachineBetaSetting = "linkedEnvironmentsEnabled" | "fastWorktreeCheckout";
246+
247+
/** One switch per connected machine that offers the beta, since each machine's own setting decides. */
248+
function MachineBetaSection({
249+
title,
250+
icon,
251+
capability,
252+
setting,
253+
description,
254+
}: {
255+
readonly title: string;
256+
readonly icon: ComponentProps<typeof SettingsSwitchRow>["icon"];
257+
readonly capability: "peerLinks" | "fastWorktreeCheckout";
258+
readonly setting: MachineBetaSetting;
259+
readonly description: string;
260+
}) {
233261
const { environments } = useEnvironments();
234262
const supported = environments.filter(
235263
(environment) =>
236264
environment.connection.phase === "connected" &&
237-
environment.serverConfig?.environment.capabilities.peerLinks === true,
265+
environment.serverConfig?.environment.capabilities[capability] === true,
238266
);
239267
const writable = useEnvironmentsWithScope(supported, AuthSettingsWriteScope);
240268
const updateSettings = useAtomCommand(serverEnvironment.updateSettings, {
241-
label: "linked environments beta update",
269+
label: `${setting} beta update`,
242270
reportFailure: true,
243271
});
244272
if (supported.length === 0) return null;
245273
return (
246274
<View className="gap-3">
247-
<SettingsSection title="Beta: Linked environments">
275+
<SettingsSection title={`Beta: ${title}`}>
248276
{supported.map((environment) => {
249277
const policy = environment.serverConfig?.managedPolicy;
250-
const managed = isManagedSettingPath(policy, "linkedEnvironmentsEnabled");
278+
const managed = isManagedSettingPath(policy, setting);
251279
return (
252280
<SettingsSwitchRow
253281
key={environment.environmentId}
254-
icon="link"
282+
icon={icon}
255283
label={environment.label}
256284
{...(managed ? { subtitle: `Managed by ${policy?.organization}.` } : {})}
257-
value={environment.serverConfig?.settings.linkedEnvironmentsEnabled === true}
285+
value={environment.serverConfig?.settings[setting] === true}
258286
disabled={managed || !writable.has(environment.environmentId)}
259287
onValueChange={(value) =>
260288
void updateSettings({
261289
environmentId: environment.environmentId,
262-
input: { patch: { linkedEnvironmentsEnabled: value } },
290+
input: {
291+
patch:
292+
setting === "linkedEnvironmentsEnabled"
293+
? { linkedEnvironmentsEnabled: value }
294+
: { fastWorktreeCheckout: value },
295+
},
263296
})
264297
}
265298
/>
266299
);
267300
})}
268301
</SettingsSection>
269-
<Text className="px-2 text-sm text-foreground-muted">
270-
Let agents on a machine work on your other machines, and theirs on it. Turn it on for each
271-
machine. While off, nothing new starts over a link; running tasks finish.
272-
</Text>
302+
<Text className="px-2 text-sm text-foreground-muted">{description}</Text>
273303
</View>
274304
);
275305
}

‎apps/mobile/src/features/settings/settings-search.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,8 @@ const SETTINGS_SEARCH_TERMS = {
104104
"beta",
105105
"linked environments",
106106
"link machine",
107+
"fast worktree checkout",
108+
"clone cache",
107109
"tool calls in chat",
108110
"hide tool calls",
109111
"commands edits searches",

‎apps/server/src/config.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ export interface ServerDerivedPaths {
4242
readonly environmentThemesDir: string;
4343
readonly providerStatusCacheDir: string;
4444
readonly worktreesDir: string;
45+
readonly worktreeCheckoutCacheDir: string;
4546
readonly attachmentsDir: string;
4647
readonly browserArtifactsDir: string;
4748
readonly logsDir: string;
@@ -158,6 +159,7 @@ export const deriveServerPaths = Effect.fn(function* (
158159
environmentThemesDir: join(stateDir, "themes"),
159160
providerStatusCacheDir,
160161
worktreesDir: join(baseDir, "worktrees"),
162+
worktreeCheckoutCacheDir: join(providerStatusCacheDir, "worktree-checkouts"),
161163
attachmentsDir,
162164
browserArtifactsDir: join(stateDir, "browser-artifacts"),
163165
logsDir,

‎apps/server/src/environment/ServerEnvironment.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -239,6 +239,7 @@ export const make = Effect.gen(function* () {
239239
projectWorktreeCleanup: true,
240240
settledWorktreeCleanup: true,
241241
worktreesDirectory: true,
242+
...(hostPlatform === "darwin" ? { fastWorktreeCheckout: true } : {}),
242243
threadAutoSettlementScope: true,
243244
threadRestartContinuation: true,
244245
projectSettingsOverrides: true,

‎apps/server/src/git/GitManager.ts‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -750,9 +750,20 @@ export const make = Effect.gen(function* () {
750750
}
751751
return result;
752752
});
753-
const readWorktreesDirectory = serverSettingsService.getSettings.pipe(
754-
Effect.map((settings) => settings.worktreesDirectory),
755-
Effect.orElseSucceed(() => ""),
753+
const readWorktreeCreationSettings = serverSettingsService.getSettings.pipe(
754+
Effect.map((settings) => ({
755+
worktreesDirectory: settings.worktreesDirectory,
756+
fastCheckout: settings.fastWorktreeCheckout,
757+
})),
758+
Effect.orElseSucceed(() => ({ worktreesDirectory: "" })),
759+
);
760+
// Turning fast checkout off deletes its cache right away, not at the next worktree.
761+
yield* serverSettingsService.streamChanges.pipe(
762+
Stream.map((settings) => settings.fastWorktreeCheckout),
763+
Stream.changes,
764+
Stream.filter((enabled) => !enabled),
765+
Stream.runForEach(() => gitCore.clearWorktreeCheckoutCache),
766+
Effect.forkScoped,
756767
);
757768
const createWorktree: GitManager["Service"]["createWorktree"] = Effect.fn(
758769
"GitManager.createWorktree",
@@ -764,9 +775,8 @@ export const make = Effect.gen(function* () {
764775
Effect.map(({ settings }) => settings.worktreeSubmodules),
765776
Effect.orElseSucceed(() => null),
766777
);
767-
const worktreesDirectory = yield* readWorktreesDirectory;
768778
const result = yield* gitCore.createWorktree(input, {
769-
worktreesDirectory,
779+
...(yield* readWorktreeCreationSettings),
770780
...options,
771781
submodules,
772782
});
@@ -3075,7 +3085,7 @@ export const make = Effect.gen(function* () {
30753085
path: null,
30763086
},
30773087
{
3078-
worktreesDirectory: yield* readWorktreesDirectory,
3088+
...(yield* readWorktreeCreationSettings),
30793089
submodules: yield* projectSettingsFor(input).pipe(
30803090
Effect.map(({ settings }) => settings.worktreeSubmodules),
30813091
Effect.orElseSucceed(() => null),

‎apps/server/src/orchestration-v2/testkit/ProviderReplayHarness.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,7 @@ export function makeReplayServerConfig(
147147
settingsPath: path.join(stateDir, "settings.json"),
148148
providerStatusCacheDir,
149149
worktreesDir,
150+
worktreeCheckoutCacheDir: path.join(providerStatusCacheDir, "worktree-checkouts"),
150151
attachmentsDir,
151152
browserArtifactsDir: path.join(stateDir, "browser-artifacts"),
152153
environmentThemesDir,
Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
import * as NodeModule from "node:module";
2+
3+
import * as HostProcess from "@t3tools/shared/HostProcess";
4+
import * as Context from "effect/Context";
5+
import * as Effect from "effect/Effect";
6+
import * as Layer from "effect/Layer";
7+
import * as Schema from "effect/Schema";
8+
9+
export class CheckoutCloneError extends Schema.TaggedError<CheckoutCloneError>()(
10+
"CheckoutCloneError",
11+
{
12+
source: Schema.String,
13+
destination: Schema.String,
14+
errno: Schema.optional(Schema.Number),
15+
cause: Schema.optional(Schema.Defect()),
16+
},
17+
) {
18+
override get message(): string {
19+
return `Could not clone ${this.source} to ${this.destination}${this.errno === undefined ? "" : ` (errno ${this.errno})`}.`;
20+
}
21+
}
22+
23+
/**
24+
* Copies a file or a whole folder copy-on-write in one call, sharing data blocks until either
25+
* copy changes. The destination must not exist. Undefined where the platform has no such call.
26+
*/
27+
export const CheckoutCloner = Context.Reference<
28+
((source: string, destination: string) => Effect.Effect<void, CheckoutCloneError>) | undefined
29+
>("t3/vcs/CheckoutCloner", { defaultValue: () => undefined });
30+
31+
// A single-executable server resolves packages on disk only through `require`.
32+
const requireForFfi = NodeModule.createRequire(import.meta.url);
33+
34+
/** macOS `clonefile(2)`, which clones a folder hierarchy in the kernel; elsewhere nothing. */
35+
export const layer = Layer.effect(
36+
CheckoutCloner,
37+
Effect.gen(function* () {
38+
if ((yield* HostProcess.Platform) !== "darwin") return undefined;
39+
const loadClonefile = yield* Effect.cached(
40+
Effect.try({
41+
try: () => {
42+
const { DataType, load, open } = requireForFfi("ffi-rs") as typeof import("ffi-rs");
43+
open({ library: "t3-libsystem", path: "/usr/lib/libSystem.B.dylib" });
44+
return (source: string, destination: string) =>
45+
load({
46+
library: "t3-libsystem",
47+
funcName: "clonefile",
48+
retType: DataType.I32,
49+
paramsType: [DataType.String, DataType.String, DataType.I32],
50+
// CLONE_NOFOLLOW: clone a symlink itself rather than its target.
51+
paramsValue: [source, destination, 0x0001],
52+
errno: true,
53+
// A large folder takes hundreds of milliseconds; keep it off the event loop.
54+
runInNewThread: true,
55+
});
56+
},
57+
catch: (cause) =>
58+
new CheckoutCloneError({ source: "ffi-rs", destination: "clonefile", cause }),
59+
}),
60+
);
61+
return Effect.fn("CheckoutCloner.clonefile")(function* (source: string, destination: string) {
62+
const clonefile = yield* loadClonefile.pipe(
63+
Effect.mapError(
64+
(error) => new CheckoutCloneError({ source, destination, cause: error.cause }),
65+
),
66+
);
67+
const result = yield* Effect.tryPromise({
68+
try: () => clonefile(source, destination),
69+
catch: (cause) => new CheckoutCloneError({ source, destination, cause }),
70+
});
71+
// ffi-rs types the errno form as a union with the plain return value.
72+
if (typeof result === "number" || result.value !== 0) {
73+
return yield* new CheckoutCloneError({
74+
source,
75+
destination,
76+
...(typeof result === "number" ? {} : { errno: result.errnoCode }),
77+
});
78+
}
79+
});
80+
}),
81+
);

‎apps/server/src/vcs/GitVcsDriver.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ import {
4242
PATCH_RENDER_PREFIX_ARGS,
4343
splitNullSeparatedGitStdoutPaths,
4444
} from "./GitVcsDriverCore.ts";
45+
import * as CheckoutCloner from "./CheckoutCloner.ts";
4546
import * as VcsDriver from "./VcsDriver.ts";
4647
import * as VcsProcess from "./VcsProcess.ts";
4748

@@ -144,6 +145,8 @@ export interface CreateWorktreeOptions {
144145
/** Null or omitted defers to the checkout's t3.json. */
145146
readonly submodules?: WorktreeSubmodules | null;
146147
readonly worktreesDirectory?: string;
148+
/** Clone the checkout from the macOS worktree checkout cache. */
149+
readonly fastCheckout?: boolean;
147150
}
148151

149152
export interface GitCommitProgress {
@@ -373,6 +376,8 @@ export class GitVcsDriver extends Context.Service<
373376
input: VcsCreateWorktreeInput,
374377
options?: CreateWorktreeOptions,
375378
) => Effect.Effect<VcsCreateWorktreeResult, GitCommandError>;
379+
/** Deletes the macOS worktree checkout cache in the background. */
380+
readonly clearWorktreeCheckoutCache: Effect.Effect<void>;
376381
/** Force-updates local `branch` to the primary remote's `ref`. */
377382
readonly fetchRefIntoBranch: (
378383
input: GitFetchRefInput & { readonly branch: string },
@@ -1594,4 +1599,4 @@ export const make = Effect.gen(function* () {
15941599
});
15951600

15961601
export const layerVcs = Layer.effect(VcsDriver.VcsDriver, makeVcsDriver);
1597-
export const layer = Layer.effect(GitVcsDriver, make);
1602+
export const layer = Layer.effect(GitVcsDriver, make).pipe(Layer.provide(CheckoutCloner.layer));

‎apps/server/src/vcs/GitVcsDriverCore.ts‎

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ import { gitCommandDuration, gitCommandsTotal, withMetrics } from "../observabil
4343
import * as GitVcsDriver from "./GitVcsDriver.ts";
4444
import { removeEmptyDirectory, type RemoveEmptyDirectoryError } from "./removeEmptyDirectory.ts";
4545
import { explicitBareRepositoryEnv, gitConfigEnv } from "./VcsProcess.ts";
46+
import { makeWorktreeCheckoutCache } from "./worktreeCheckoutCache.ts";
4647
import { removeLinkedWorktree } from "./worktreeRemoval.ts";
4748
import { resolveWorktreesDirectory } from "../worktreesDirectory.ts";
4849
import {
@@ -945,7 +946,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
945946
const fileSystem = yield* FileSystem.FileSystem;
946947
const path = yield* Path.Path;
947948
const commandSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
948-
const { worktreesDir } = yield* ServerConfig.ServerConfig;
949+
const { worktreesDir, worktreeCheckoutCacheDir } = yield* ServerConfig.ServerConfig;
949950
const isServerInternalPath = yield* makeIsServerInternalPath;
950951
const digest = yield* Digest.Digest;
951952
const hostPlatform = yield* HostProcess.Platform;
@@ -1143,6 +1144,11 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
11431144
input.writesSharedConfig ? withSharedConfigLock(input.cwd, execution) : execution,
11441145
);
11451146

1147+
const checkoutCache = yield* makeWorktreeCheckoutCache({
1148+
cacheDir: worktreeCheckoutCacheDir,
1149+
execute,
1150+
});
1151+
11461152
const executeGit = (
11471153
operation: string,
11481154
cwd: string,
@@ -4259,7 +4265,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
42594265
"git worktree add failed",
42604266
);
42614267
}
4262-
const args = ["worktree", "add", "--", worktreePath, newRefName ?? input.refName];
4268+
const checkoutRef = newRefName ?? input.refName;
42634269
const progress = options?.progress;
42644270
const onCheckoutProgress = progress?.onCheckoutProgress;
42654271

@@ -4274,10 +4280,20 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
42744280
{ concurrency: "unbounded" },
42754281
);
42764282
const checkoutWorkers = configuredCheckoutWorkers ?? "0";
4277-
yield* executeGitWithStableDiagnostics(
4283+
const fastCheckout = checkoutCache !== undefined && options?.fastCheckout === true;
4284+
const cacheGeneration = fastCheckout ? yield* checkoutCache.currentGeneration : 0;
4285+
const stockCheckout = executeGitWithStableDiagnostics(
42784286
"GitVcsDriver.createWorktree",
42794287
input.cwd,
4280-
["-c", `checkout.workers=${checkoutWorkers}`, ...args],
4288+
[
4289+
"-c",
4290+
`checkout.workers=${checkoutWorkers}`,
4291+
"worktree",
4292+
"add",
4293+
"--",
4294+
worktreePath,
4295+
checkoutRef,
4296+
],
42814297
{
42824298
fallbackErrorDetail: "git worktree add failed",
42834299
// Large checkouts and post-checkout hooks can legitimately run for many
@@ -4297,6 +4313,13 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
42974313
}
42984314
: {}),
42994315
},
4316+
);
4317+
yield* (
4318+
fastCheckout
4319+
? checkoutCache
4320+
.create({ cwd: input.cwd, worktreePath, refName: checkoutRef, checkoutWorkers })
4321+
.pipe(Effect.flatMap((cloned) => (cloned ? Effect.void : stockCheckout)))
4322+
: stockCheckout
43004323
).pipe(
43014324
Effect.onError(() =>
43024325
newRefName
@@ -4308,6 +4331,9 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
43084331
: Effect.void,
43094332
),
43104333
);
4334+
if (fastCheckout) {
4335+
yield* checkoutCache.schedule(worktreePath, cacheGeneration);
4336+
}
43114337

43124338
if (progress?.onWorktreeClaimed) {
43134339
yield* progress.onWorktreeClaimed(worktreePath);
@@ -5097,6 +5123,7 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
50975123
Effect.ensuring(invalidateWorktreeCreationCaches(input.cwd)),
50985124
);
50995125
}),
5126+
clearWorktreeCheckoutCache: checkoutCache?.clear ?? Effect.void,
51005127
fetchRefIntoBranch: Effect.fnUntraced(function* (input) {
51015128
return yield* withListRefsInvalidation(input.cwd, fetchRefIntoBranch(input));
51025129
}),

0 commit comments

Comments
 (0)