The best way to control Claude Code, Codex and more from any computer or phone
fix(server): t3_thread_launch refuses an explicit branch that already exists (#31279)
Julius Marminge committed
Nov 16, 2026 at 17:37 UTC
4ffa1da7cfe7f2181439569f011ad767950a62b3
5 files changed
+140
-18
apps/server/src/mcp/toolkits/project/handlers.test.ts
+33
-13
@@ -582,36 +582,56 @@ it.effect("a launch into a new worktree creates nothing when its base ref has no
582
runtimeModeCeiling: "auto",
583
launched,
584
checkWorktreeBase: ({ projectId, workspaceStrategy }) =>
585
- workspaceStrategy.type === "worktree" && workspaceStrategy.baseRef === "t3/renamed"
586
- ? Effect.fail(
587
- new ThreadLaunch.ThreadLaunchBaseRefError({
588
- projectId,
589
- projectTitle: "Client target",
590
- workspaceRoot: "/projects/client-target",
591
- baseRef: workspaceStrategy.baseRef,
592
- }),
593
- )
594
- : Effect.void,
585
+ workspaceStrategy.type !== "worktree"
586
+ ? Effect.void
587
+ : workspaceStrategy.baseRef === "t3/renamed"
588
+ ? Effect.fail(
589
+ new ThreadLaunch.ThreadLaunchBaseRefError({
590
+ projectId,
591
+ projectTitle: "Client target",
592
+ workspaceRoot: "/projects/client-target",
593
+ baseRef: workspaceStrategy.baseRef,
594
+ }),
595
+ )
596
+ : workspaceStrategy.branch === "feature/taken"
597
+ ? Effect.fail(
598
+ new ThreadLaunch.ThreadLaunchBranchExistsError({
599
+ projectId,
600
+ projectTitle: "Client target",
601
+ branch: workspaceStrategy.branch,
602
+ }),
603
+ )
604
+ : Effect.void,
605
});
606
const toolkit = yield* ProjectToolkit.pipe(
607
Effect.provide(
608
McpToolAccess.HandlersLayer.layer(ProjectHandlers.layer).pipe(Layer.provide(dependencies)),
609
),
610
);
601
- const launchFrom = (baseRef: string) =>
611
+ const launchFrom = (baseRef: string, branch?: string) =>
612
toolkit
613
.handle("t3_thread_launch", {
614
title: "Fix",
615
projectId,
606
- workspaceStrategy: { type: "worktree", baseRef, startFromOrigin: false },
616
+ workspaceStrategy: {
617
+ type: "worktree",
618
+ baseRef,
619
+ ...(branch === undefined ? {} : { branch }),
620
+ startFromOrigin: false,
621
+ },
622
})
623
.pipe(Stream.unwrap, Stream.runCollect, Effect.provide(dependencies));
624
625
const refused = (yield* launchFrom("t3/renamed")).at(-1)?.result;
626
expect(refused).toMatchObject({ code: "invalid_request" });
627
expect((refused as { message: string }).message).toContain(
613
- 'Base ref "t3/renamed" does not resolve to a commit in project "Client target" (/projects/client-target). No thread was created.',
628
+ 'Base ref "t3/renamed" does not resolve to a commit in project "Client target" (/projects/client-target). No thread was created. Pass a branch, tag, or commit that exists there',
629
);
630
+ expect((yield* launchFrom("main", "feature/taken")).at(-1)?.result).toMatchObject({
631
+ code: "invalid_request",
632
+ message:
633
+ 'Branch "feature/taken" already exists in project "Client target". No thread was created. Pass a branch name that does not exist yet, or omit branch to get a generated name.',
634
+ });
635
expect(launched).toHaveLength(0);
636
637
expect((yield* launchFrom("main")).at(-1)?.result).toMatchObject({ projectId });
apps/server/src/mcp/toolkits/project/handlers.ts
+3
@@ -51,12 +51,15 @@ function projectFailure(error: Project.ProjectServiceError) {
51
function worktreeCheckHint(
52
error:
53
| ThreadLaunch.ThreadLaunchBaseRefError
54
+ | ThreadLaunch.ThreadLaunchBranchExistsError
55
| ThreadLaunch.ThreadLaunchBranchConflictError
56
| ThreadLaunch.ThreadLaunchNotRepositoryError,
57
strategy: { readonly startFromOrigin?: boolean | undefined },
58
) {
59
if (error._tag === "ThreadLaunchNotRepositoryError")
60
return `Use workspaceStrategy: {type: "root"}, or pass the projectId of a Git repository.`;
61
+ if (error._tag === "ThreadLaunchBranchExistsError")
62
+ return "Pass a branch name that does not exist yet, or omit branch to get a generated name.";
63
if (error._tag === "ThreadLaunchBranchConflictError") {
64
const sibling = error.branch.replaceAll("/", "-");
65
return `Use a name that does not nest under or contain an existing branch${
apps/server/src/orchestration-v2/ThreadLaunchService.test.ts
+70
@@ -1312,6 +1312,7 @@ it.effect.each(["stable", "upstream/release"])(
1312
git: {
1313
resolveWorktreeBaseRemote: (input) => git.resolveWorktreeBaseRemote({ ...input, cwd }),
1314
hasRefNamed: () => Effect.succeed(false),
1315
+ listLocalBranchNames: () => git.listLocalBranchNames(cwd),
1316
},
1317
fetchWorktreeBaseCommit: (input) => git.fetchWorktreeBaseCommit({ ...input, cwd }),
1318
createWorktree: (input, options) =>
@@ -3227,6 +3228,75 @@ it.effect.each([
3228
}),
3229
);
3230
3231
+it.effect("refuses a new worktree whose explicit branch already exists", () =>
3232
+ Effect.gen(function* () {
3233
+ const fs = yield* FileSystem.FileSystem;
3234
+ const git = yield* GitVcsDriver.GitVcsDriver;
3235
+ const directory = yield* fs.makeTempDirectoryScoped({ prefix: "launch-branch-exists-" });
3236
+ const cwd = `${directory}/repo`;
3237
+ const temporaryBranch = "t3code/0b5e7a1c-3f2d-4e8a-9b6c-1d2e3f4a5b6c";
3238
+ yield* fs.makeDirectory(cwd);
3239
+ const command = (args: string[]) => git.execute({ operation: "launch-test", cwd, args });
3240
+ yield* command(["init", "-b", "main"]);
3241
+ yield* command(["config", "user.name", "Test"]);
3242
+ yield* command(["config", "user.email", "test@example.test"]);
3243
+ yield* command(["commit", "--allow-empty", "-m", "initial"]);
3244
+ yield* command(["branch", "feature/idle"]);
3245
+ yield* command(["branch", temporaryBranch]);
3246
+ // Resolves as `refs/heads/feature/tagged` although no such branch exists.
3247
+ yield* command(["tag", "refs/heads/feature/tagged"]);
3248
+ yield* command(["worktree", "add", "-b", "feature/taken", `${directory}/taken`]);
3249
+ const harness = makeHarness({
3250
+ hasCommit: ({ refName }) =>
3251
+ command(["rev-parse", "--verify", `${refName}^{commit}`]).pipe(
3252
+ Effect.as(true),
3253
+ Effect.orElseSucceed(() => false),
3254
+ ),
3255
+ git: { listLocalBranchNames: () => git.listLocalBranchNames(cwd) },
3256
+ });
3257
+ yield* Effect.gen(function* () {
3258
+ const launches = yield* ThreadLaunch.ThreadLaunchService;
3259
+ const check = (branch: string, baseRef = "main") =>
3260
+ launches
3261
+ .checkWorktreeBase({
3262
+ projectId,
3263
+ workspaceStrategy: { type: "worktree", baseRef, branch },
3264
+ })
3265
+ .pipe(
3266
+ Effect.match({
3267
+ onSuccess: () => [branch, "accepted"],
3268
+ onFailure: (error) => [branch, error._tag],
3269
+ }),
3270
+ );
3271
+ assert.deepEqual(
3272
+ yield* Effect.forEach(
3273
+ ["feature/idle", "feature/taken", temporaryBranch, "feature/fresh", "feature/tagged"],
3274
+ (branch) => check(branch),
3275
+ ),
3276
+ [
3277
+ ["feature/idle", "ThreadLaunchBranchExistsError"],
3278
+ ["feature/taken", "ThreadLaunchBranchExistsError"],
3279
+ [temporaryBranch, "ThreadLaunchBranchExistsError"],
3280
+ ["feature/fresh", "accepted"],
3281
+ ["feature/tagged", "accepted"],
3282
+ ],
3283
+ );
3284
+ // A `:/text` base skips the base check but not the branch check.
3285
+ assert.deepEqual(yield* check("feature/taken", ":/initial"), [
3286
+ "feature/taken",
3287
+ "ThreadLaunchBranchExistsError",
3288
+ ]);
3289
+ }).pipe(Effect.provide(harness.layer));
3290
+ }).pipe(
3291
+ Effect.provide(
3292
+ GitVcsDriver.layer.pipe(
3293
+ Layer.provide(ServerConfig.layerTest(process.cwd(), { prefix: "launch-branch-exists-" })),
3294
+ Layer.provideMerge(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer)),
3295
+ ),
3296
+ ),
3297
+ ),
3298
+);
3299
+
3300
it.effect.each([
3301
{ requested: "werkstatt/baseline", blocking: "werkstatt" },
3302
{ requested: "foo", blocking: "foo/bar" },
apps/server/src/orchestration-v2/ThreadLaunchService.ts
+27
-5
@@ -176,6 +176,19 @@ export class ThreadLaunchBaseRefError extends Schema.TaggedError<ThreadLaunchBas
176
}
177
}
178
179
+export class ThreadLaunchBranchExistsError extends Schema.TaggedError<ThreadLaunchBranchExistsError>()(
180
+ "ThreadLaunchBranchExistsError",
181
+ {
182
+ projectId: ProjectId,
183
+ projectTitle: Schema.String,
184
+ branch: Schema.String,
185
+ },
186
+) {
187
+ override get message(): string {
188
+ return `Branch "${this.branch}" already exists in project "${this.projectTitle}".`;
189
+ }
190
+}
191
+
192
export class ThreadLaunchBranchConflictError extends Schema.TaggedError<ThreadLaunchBranchConflictError>()(
193
"ThreadLaunchBranchConflictError",
194
{
@@ -220,7 +233,10 @@ export class ThreadLaunchService extends Context.Service<
233
},
234
) => Effect.Effect<
235
void,
223
- ThreadLaunchBaseRefError | ThreadLaunchBranchConflictError | ThreadLaunchNotRepositoryError
236
+ | ThreadLaunchBaseRefError
237
+ | ThreadLaunchBranchExistsError
238
+ | ThreadLaunchBranchConflictError
239
+ | ThreadLaunchNotRepositoryError
240
>;
241
/** True only when the project's folder is known not to be a Git repository. */
242
readonly isNonGitProject: (projectId: ProjectId) => Effect.Effect<boolean>;
@@ -374,8 +390,7 @@ const make = Effect.gen(function* () {
390
if (project === undefined) return;
391
const cwd = project.workspaceRoot;
392
const { baseRef, branch } = strategy;
377
- const checksBranch = branch !== undefined && !isTemporaryWorktreeBranch(branch);
378
- // Errors keep their order below: missing repository, then base ref, then branch conflict.
393
+ // Errors keep their order below: missing repository, then base ref, then branch exists or conflicts.
394
const [repositoryRoot, hasBaseCommit, localBranches] = yield* Effect.all(
395
[
396
git.repositoryRoot(cwd).pipe(Effect.orElseSucceed(() => undefined)),
@@ -386,7 +401,7 @@ const make = Effect.gen(function* () {
401
git
402
.hasCommit({ cwd, refName: baseRef === "-" ? "@{-1}" : baseRef })
403
.pipe(Effect.orElseSucceed(() => true)),
389
- checksBranch
404
+ branch !== undefined
405
? git
406
.listLocalBranchNames(cwd)
407
.pipe(Effect.orElseSucceed((): ReadonlyArray<string> => []))
@@ -423,8 +438,15 @@ const make = Effect.gen(function* () {
438
workspaceRoot: project.workspaceRoot,
439
baseRef,
440
});
441
+ if (branch === undefined) return;
442
+ if (localBranches.includes(branch))
443
+ return yield* new ThreadLaunchBranchExistsError({
444
+ projectId: project.id,
445
+ projectTitle: project.title,
446
+ branch,
447
+ });
448
// Provisioning flattens temporary names that collide, so only explicit names are refused.
427
- if (!checksBranch) return;
449
+ if (isTemporaryWorktreeBranch(branch)) return;
450
const conflictingBranch = localBranches.find(
451
(existing) => existing.startsWith(`${branch}/`) || branch.startsWith(`${existing}/`),
452
);
apps/server/src/ws.ts
+7
@@ -2259,6 +2259,13 @@ export const layerWsRpc = (
2259
message: cause.message,
2260
cause,
2261
}),
2262
+ ThreadLaunchBranchExistsError: (cause) =>
2263
+ new OrchestrationV2ThreadLaunchError({
2264
+ commandId: input.commandId,
2265
+ projectId: input.projectId,
2266
+ message: cause.message,
2267
+ cause,
2268
+ }),
2269
ThreadLaunchBranchConflictError: (cause) =>
2270
new OrchestrationV2ThreadLaunchError({
2271
commandId: input.commandId,