From a8d794035f117575f0b651e01d15f358931d4087 Mon Sep 17 00:00:00 2001
From: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
Date: Mon, 14 Sep 2026 17:29:26 -0700
Subject: [PATCH 1/4] feat(web): render worktree setup inline and let the agent
 start while the setup script runs

The worktree setup card was a boxed stepper that swapped wholesale for the
turn header once the agent started, and the agent could not start until the
setup script had exited.

The setup now renders as the same shimmering header row the turn uses plus
worklog-style rows underneath, so the handoff only swaps the header text.
Setup scripts default to async: the agent starts right after checkout and the
script's row stays under the turn header until it exits, then leaves (or
stays with its exit code if it failed). A new `async: false` on a t3.json
script, or the "Wait for it to finish" toggle in the action editor, keeps the
old blocking behaviour.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../project/ProjectSetupScriptRunner.test.ts  |   1 +
 .../src/project/ProjectSetupScriptRunner.ts   |   3 +
 apps/server/src/server.test.ts                | 151 ++++++++++
 apps/server/src/ws.ts                         |  65 ++--
 apps/web/src/components/ChatView.tsx          |  39 ++-
 .../src/components/ProjectScriptsControl.tsx  |   1 +
 .../chat/MessagesTimeline.logic.test.ts       |  33 ++-
 .../components/chat/MessagesTimeline.logic.ts |  39 ++-
 .../src/components/chat/MessagesTimeline.tsx  |   7 +-
 .../src/components/chat/WorktreeSetupCard.tsx | 280 +++++++++++-------
 .../src/components/projectScriptEditor.tsx    |  19 ++
 .../settings/ProjectActionsSettings.tsx       |   1 +
 apps/web/src/projectScripts.test.ts           |  21 ++
 apps/web/src/projectScripts.ts                |   2 +
 packages/contracts/src/orchestration.ts       |   6 +
 packages/contracts/src/t3ProjectFile.test.ts  |   4 +-
 packages/contracts/src/t3ProjectFile.ts       |   6 +
 packages/shared/src/t3ProjectFile.test.ts     |   1 +
 18 files changed, 534 insertions(+), 145 deletions(-)

diff --git a/apps/server/src/project/ProjectSetupScriptRunner.test.ts b/apps/server/src/project/ProjectSetupScriptRunner.test.ts
index c0d15f105af7..d9d74d926717 100644
--- a/apps/server/src/project/ProjectSetupScriptRunner.test.ts
+++ b/apps/server/src/project/ProjectSetupScriptRunner.test.ts
@@ -203,6 +203,7 @@ describe("ProjectSetupScriptRunner", () => {
           scriptCommand: "bun install",
           terminalId: "setup-setup",
           cwd: "/repo/worktrees/a",
+          async: true,
         });
         expect(open).toHaveBeenCalledWith({
           threadId: "thread-1",
diff --git a/apps/server/src/project/ProjectSetupScriptRunner.ts b/apps/server/src/project/ProjectSetupScriptRunner.ts
index c80dd535f514..d69198e30917 100644
--- a/apps/server/src/project/ProjectSetupScriptRunner.ts
+++ b/apps/server/src/project/ProjectSetupScriptRunner.ts
@@ -30,6 +30,8 @@ export interface ProjectSetupScriptRunnerResultStarted {
   readonly scriptCommand: string;
   readonly terminalId: string;
   readonly cwd: string;
+  /** False when the script's `async` flag asks the agent to wait for it. */
+  readonly async: boolean;
   /**
    * Resolves when the script's shell prints the completion sentinel. The
    * exit code is null when the terminal exited or was closed before the
@@ -410,6 +412,7 @@ export const make = Effect.gen(function* () {
       scriptCommand: script.command,
       terminalId,
       cwd,
+      async: script.async !== false,
       ...(observed ? { completion: observed.completion } : {}),
     } as const;
   });
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index 7402e908fcf8..540436a69a5e 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -44,6 +44,8 @@ import {
   WS_METHODS,
   WsRpcGroup,
   EditorId,
+  type WorktreeSetupSnapshot,
+  type WorktreeSetupStageId,
 } from "@t3tools/contracts";
 import {
   computeDpopAccessTokenHash,
@@ -10781,6 +10783,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
               scriptCommand: "npm install",
               terminalId: "setup-setup",
               cwd: "/tmp/bootstrap-worktree",
+              async: true,
             }),
         );
 
@@ -11346,6 +11349,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             scriptCommand: "npm install",
             terminalId: "setup-setup",
             cwd: "/tmp/bootstrap-worktree",
+            async: true,
           }),
       );
       let setupActivityAppendAttempt = 0;
@@ -11449,6 +11453,153 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect.each([
+    { caseName: "async setup scripts let the turn start before the script exits", async: true },
+    { caseName: "sync setup scripts hold the turn until the script exits", async: false },
+  ])("$caseName", ({ async }) =>
+    Effect.gen(function* () {
+      const dispatchedCommands: Array<OrchestrationCommand> = [];
+      const scriptExit = yield* Deferred.make<void>();
+      const runForThread = vi.fn(
+        (
+          _: Parameters<
+            ProjectSetupScriptRunner.ProjectSetupScriptRunner["Service"]["runForThread"]
+          >[0],
+        ) =>
+          Effect.succeed({
+            status: "started" as const,
+            scriptId: "setup",
+            scriptName: "Setup",
+            scriptCommand: "npm install",
+            terminalId: "setup-setup",
+            cwd: "/tmp/bootstrap-worktree",
+            async,
+            completion: Deferred.await(scriptExit).pipe(Effect.as({ exitCode: 0, durationMs: 1 })),
+          }),
+      );
+
+      yield* buildAppUnderTest({
+        layers: {
+          vcsDriver: {
+            isInsideWorkTree: () => Effect.succeed(true),
+          },
+          gitVcsDriver: {
+            execute: () => Effect.succeed(SUCCESSFUL_GIT_EXECUTION),
+            createWorktree: () =>
+              Effect.succeed({
+                worktree: {
+                  refName: "t3code/bootstrap-refName",
+                  path: "/tmp/bootstrap-worktree",
+                },
+              }),
+          },
+          orchestrationEngine: {
+            dispatch: (command) =>
+              Effect.sync(() => {
+                dispatchedCommands.push(command);
+                return { sequence: dispatchedCommands.length };
+              }),
+            readEvents: () => Stream.empty,
+          },
+          projectSetupScriptRunner: {
+            runForThread,
+          },
+        },
+      });
+
+      const createdAt = "2026-01-01T00:00:00.000Z";
+      const threadId = ThreadId.make(`thread-bootstrap-${async ? "async" : "sync"}-setup`);
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const dispatchFiber = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.dispatchCommand]({
+            type: "thread.turn.start",
+            commandId: CommandId.make(`cmd-bootstrap-${async ? "async" : "sync"}-setup`),
+            threadId,
+            message: {
+              messageId: MessageId.make("msg-bootstrap-setup"),
+              role: "user",
+              text: "hello",
+              attachments: [],
+            },
+            modelSelection: defaultModelSelection,
+            runtimeMode: "full-access",
+            interactionMode: "default",
+            bootstrap: {
+              createThread: {
+                projectId: defaultProjectId,
+                title: "Bootstrap Thread",
+                modelSelection: defaultModelSelection,
+                runtimeMode: "full-access",
+                interactionMode: "default",
+                branch: "main",
+                worktreePath: null,
+                createdAt,
+              },
+              prepareWorktree: {
+                projectCwd: "/tmp/project",
+                baseBranch: "main",
+                branch: "t3code/bootstrap-refName",
+              },
+              runSetupScript: true,
+            },
+            createdAt,
+          }),
+        ),
+      ).pipe(Effect.forkChild);
+
+      const turnStarted = () =>
+        dispatchedCommands.some((command) => command.type === "thread.turn.start");
+      const snapshotWhere = (predicate: (snapshot: WorktreeSetupSnapshot) => boolean) =>
+        Effect.scoped(
+          withWsRpcClient(wsUrl, (client) =>
+            client[WS_METHODS.subscribeWorktreeSetup]({ threadId }).pipe(
+              Stream.filter(
+                (snapshot): snapshot is WorktreeSetupSnapshot =>
+                  snapshot !== null && predicate(snapshot),
+              ),
+              Stream.runHead,
+              Effect.map(Option.getOrThrow),
+            ),
+          ),
+        );
+      const stageStatus = (snapshot: WorktreeSetupSnapshot, id: WorktreeSetupStageId) =>
+        snapshot.stages.find((stage) => stage.id === id)?.status;
+
+      if (async) {
+        // The turn is dispatched while the script is still running.
+        const started = yield* snapshotWhere(
+          (snapshot) => stageStatus(snapshot, "agent") === "done",
+        );
+        assertTrue(turnStarted());
+        assert.equal(started.phase, "running");
+        assert.equal(stageStatus(started, "setup-script"), "running");
+        yield* Fiber.join(dispatchFiber);
+
+        yield* Deferred.succeed(scriptExit, undefined);
+        const settled = yield* snapshotWhere((snapshot) => snapshot.phase !== "running");
+        assert.equal(settled.phase, "done");
+        assert.equal(stageStatus(settled, "setup-script"), "done");
+        return;
+      }
+
+      // The script is running and the turn has not been dispatched yet.
+      const running = yield* snapshotWhere(
+        (snapshot) => stageStatus(snapshot, "setup-script") === "running",
+      );
+      assert.equal(stageStatus(running, "agent"), "pending");
+      assert.isFalse(turnStarted());
+
+      yield* Deferred.succeed(scriptExit, undefined);
+      yield* Fiber.join(dispatchFiber);
+      assertTrue(turnStarted());
+      const settled = yield* snapshotWhere((snapshot) => snapshot.phase !== "running");
+      assert.equal(settled.phase, "done");
+      assert.equal(stageStatus(settled, "setup-script"), "done");
+      assert.equal(stageStatus(settled, "agent"), "done");
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("cleans up created bootstrap threads when worktree creation defects", () =>
     Effect.gen(function* () {
       const dispatchedCommands: Array<OrchestrationCommand> = [];
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index 6e5d9c02db39..4ae84c3c2f43 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -1112,15 +1112,16 @@ const makeWsRpcLayer = (
           const threadId = command.threadId;
           const track = (effect: Effect.Effect<void>) => (tracked ? effect : Effect.void);
 
-          // Runs the setup script and, for tracked bootstraps, waits for it to
-          // exit so the card can show the exit code and the agent stage never
-          // starts on a half-installed tree. Untracked callers keep the old
-          // fire-and-forget behavior.
+          // Starts the setup script. For tracked bootstraps it returns the
+          // effect that waits for the script to exit and records the outcome
+          // on the card; whether the agent stage waits on it depends on the
+          // script's `async` flag. Returns null when nothing is left to await.
+          // Untracked callers keep the old fire-and-forget behavior.
           const runSetupProgram = () =>
             Effect.gen(function* () {
               if (!bootstrap?.runSetupScript || !targetWorktreePath) {
                 yield* track(worktreeSetupTracker.stageStatus(threadId, "setup-script", "skipped"));
-                return;
+                return null;
               }
               const worktreePath = targetWorktreePath;
               const requestedAt = yield* nowIso;
@@ -1197,21 +1198,33 @@ const makeWsRpcLayer = (
                   }),
                 );
               if (!tracked || !setupResult?.completion) {
-                return;
+                return null;
               }
               // The setup script is best effort, like the untracked path: a
               // failed install must not throw away the worktree the user just
               // waited for. The card keeps the failed stage and its terminal.
-              const completion = yield* setupResult.completion;
-              if (completion.exitCode === 0) {
-                yield* worktreeSetupTracker.stageStatus(threadId, "setup-script", "done");
-                return;
+              const awaitCompletion = setupResult.completion.pipe(
+                Effect.flatMap((completion) => {
+                  if (completion.exitCode === 0) {
+                    return worktreeSetupTracker.stageStatus(threadId, "setup-script", "done");
+                  }
+                  const detail =
+                    completion.exitCode === null
+                      ? "terminal closed before the script finished"
+                      : `exit ${completion.exitCode}`;
+                  return worktreeSetupTracker.stageStatus(
+                    threadId,
+                    "setup-script",
+                    "failed",
+                    detail,
+                  );
+                }),
+              );
+              if (!setupResult.async) {
+                yield* awaitCompletion;
+                return null;
               }
-              const detail =
-                completion.exitCode === null
-                  ? "terminal closed before the script finished"
-                  : `exit ${completion.exitCode}`;
-              yield* worktreeSetupTracker.stageStatus(threadId, "setup-script", "failed", detail);
+              return awaitCompletion;
             });
 
           const bootstrapProgram = Effect.gen(function* () {
@@ -1414,7 +1427,7 @@ const makeWsRpcLayer = (
               yield* refreshGitStatus(targetWorktreePath);
             }
 
-            yield* runSetupProgram();
+            const pendingSetupScript = yield* runSetupProgram();
 
             yield* track(worktreeSetupTracker.stageStatus(threadId, "agent", "running"));
             // Past this point a cancel would roll back a thread whose turn has
@@ -1423,11 +1436,21 @@ const makeWsRpcLayer = (
             const started = yield* Effect.uninterruptible(
               dispatchFromClient(finalTurnStartCommand),
             );
-            yield* track(
-              worktreeSetupTracker
-                .stageStatus(threadId, "agent", "done")
-                .pipe(Effect.andThen(worktreeSetupTracker.finish(threadId, "done"))),
-            );
+            yield* track(worktreeSetupTracker.stageStatus(threadId, "agent", "done"));
+            // An async setup script outlives the handoff: the snapshot stays
+            // running so the client keeps its row next to the agent's work,
+            // and settles when the script exits. The turn already started, so
+            // the wait cannot fail the dispatch.
+            const settle = track(worktreeSetupTracker.finish(threadId, "done"));
+            if (pendingSetupScript) {
+              yield* pendingSetupScript.pipe(
+                Effect.ignoreCause({ log: true }),
+                Effect.andThen(settle),
+                Effect.forkDetach,
+              );
+            } else {
+              yield* settle;
+            }
             return started;
           });
 
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 303427ebd2e7..f2fc5aa069ef 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -1430,6 +1430,16 @@ function releaseChatTimelineAnchor<T extends { readonly messageId: MessageId | n
   return current.messageId === null ? current : { ...current, messageId: null };
 }
 
+/**
+ * Worktree setups whose async setup script may still be running after the
+ * draft route hands off to the created thread. Keyed by scoped thread key;
+ * entries are removed once the setup settles.
+ */
+const pendingWorktreeSetupByThreadKey = new Map<
+  string,
+  { environmentId: EnvironmentId; threadId: ThreadId }
+>();
+
 export default function ChatView(props: ChatViewProps) {
   const {
     environmentId,
@@ -1659,7 +1669,12 @@ export default function ChatView(props: ChatViewProps) {
     environmentId: EnvironmentId;
     threadId: ThreadId;
     ownerKey: string;
-  } | null>(null);
+  } | null>(() => {
+    // The draft route unmounts when it promotes to the created thread, while an
+    // async setup script may still be running. Adopt the ref the draft left.
+    const handed = pendingWorktreeSetupByThreadKey.get(routeThreadKey);
+    return handed ? { ...handed, ownerKey: routeThreadKey } : null;
+  });
   const [heldWorktreeSetup, setHeldWorktreeSetup] = useState<WorktreeSetupSnapshot | null>(null);
   // Set by "Work locally": the draft whose restored message should be resent
   // once the cancelled dispatch has settled and the draft is in local mode.
@@ -3500,14 +3515,24 @@ export default function ChatView(props: ChatViewProps) {
       ? heldWorktreeSetup
       : null;
   // A finished card is dropped once the agent's turn shows in the timeline:
-  // the card belongs to the send, and the agent takes over from there.
+  // the card belongs to the send, and the agent takes over from there. An
+  // async setup script keeps the snapshot running past the handoff and its
+  // row leaves the moment the script exits cleanly; a failed script stays
+  // for the rest of the turn so the exit code and terminal remain reachable.
   const worktreeSetupDoneAndTurnVisible =
-    worktreeSetup?.phase === "done" && activeThread?.latestTurn?.startedAt != null;
+    worktreeSetup?.phase === "done" &&
+    activeThread?.latestTurn?.startedAt != null &&
+    (!isWorking || !worktreeSetup.stages.some((stage) => stage.status === "failed"));
   useEffect(() => {
     if (!worktreeSetupDoneAndTurnVisible) return;
+    if (worktreeSetupRef) {
+      pendingWorktreeSetupByThreadKey.delete(
+        scopedThreadKey(scopeThreadRef(worktreeSetupRef.environmentId, worktreeSetupRef.threadId)),
+      );
+    }
     setWorktreeSetupRef(null);
     setHeldWorktreeSetup(null);
-  }, [worktreeSetupDoneAndTurnVisible]);
+  }, [worktreeSetupDoneAndTurnVisible, worktreeSetupRef]);
   const cancelWorktreeSetup = useAtomCommand(vcsEnvironment.cancelWorktreeSetup, {
     reportFailure: false,
   });
@@ -7515,6 +7540,12 @@ export default function ChatView(props: ChatViewProps) {
         ? { environmentId, threadId: threadIdForSend, ownerKey: worktreeSetupOwnerKey }
         : null,
     );
+    if (baseBranchForWorktree) {
+      pendingWorktreeSetupByThreadKey.set(
+        scopedThreadKey(scopeThreadRef(environmentId, threadIdForSend)),
+        { environmentId, threadId: threadIdForSend },
+      );
+    }
 
     const messageIdForSend = newMessageId();
     const messageCreatedAt = new Date().toISOString();
diff --git a/apps/web/src/components/ProjectScriptsControl.tsx b/apps/web/src/components/ProjectScriptsControl.tsx
index 304922909b0a..15cca412ba43 100644
--- a/apps/web/src/components/ProjectScriptsControl.tsx
+++ b/apps/web/src/components/ProjectScriptsControl.tsx
@@ -113,6 +113,7 @@ export default function ProjectScriptsControl({
       command: fileScript.command,
       icon: fileScript.icon ?? "play",
       runOnWorktreeCreate: fileScript.runOnWorktreeCreate ?? false,
+      waitForSetup: fileScript.runOnWorktreeCreate === true && fileScript.async === false,
       keybinding: null,
       previewUrl: fileScript.previewUrl ?? null,
       autoOpenPreview: fileScript.previewUrl ? (fileScript.autoOpenPreview ?? false) : false,
diff --git a/apps/web/src/components/chat/MessagesTimeline.logic.test.ts b/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
index 59b4a0c9856b..06a2e49d8948 100644
--- a/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
+++ b/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
@@ -1148,17 +1148,18 @@ describe("deriveMessagesTimelineRows", () => {
         id: WORKTREE_SETUP_ROW_ID,
         createdAt: "2026-01-01T00:00:00Z",
         snapshot,
+        embedded: false,
       },
     ]);
 
-    // Once the agent has replied the finished card stays under the send.
+    // A failed setup never handed off, so the card stays under the send.
     const withMessages = deriveMessagesTimelineRows({
       timelineEntries: [userEntry, assistantEntry],
       isWorking: true,
       activeTurnStartedAt: "2026-01-01T00:00:00Z",
       turnDiffSummaries: [],
       supportsConversationRollback: false,
-      worktreeSetup: { ...snapshot, phase: "done" },
+      worktreeSetup: { ...snapshot, phase: "failed" },
     });
     expect(withMessages.map((row) => row.kind)).toEqual([
       "message",
@@ -1166,6 +1167,34 @@ describe("deriveMessagesTimelineRows", () => {
       "working",
       "message",
     ]);
+
+    // Once the agent stage is done the setup script may still be running in
+    // the background: the turn owns the header and the script row follows it.
+    const agentStage = {
+      id: "agent",
+      status: "done",
+      startedAt: "2026-01-01T00:00:10Z",
+      endedAt: "2026-01-01T00:00:11Z",
+      percent: null,
+      detail: null,
+      tail: [],
+    } as const;
+    const asyncSnapshot: WorktreeSetupSnapshot = { ...snapshot, stages: [agentStage] };
+    const asyncRows = deriveMessagesTimelineRows({
+      timelineEntries: [userEntry],
+      isWorking: true,
+      activeTurnStartedAt: "2026-01-01T00:00:00Z",
+      turnDiffSummaries: [],
+      supportsConversationRollback: false,
+      worktreeSetup: asyncSnapshot,
+    });
+    expect(asyncRows.map((row) => row.kind)).toEqual([
+      "message",
+      "working",
+      "worktree-setup",
+      "thinking",
+    ]);
+    expect(asyncRows[2]).toMatchObject({ kind: "worktree-setup", embedded: true });
   });
 
   it("keeps context compaction visible outside folded work", () => {
diff --git a/apps/web/src/components/chat/MessagesTimeline.logic.ts b/apps/web/src/components/chat/MessagesTimeline.logic.ts
index 3d7b1e12284e..6f3be2ab3ead 100644
--- a/apps/web/src/components/chat/MessagesTimeline.logic.ts
+++ b/apps/web/src/components/chat/MessagesTimeline.logic.ts
@@ -400,6 +400,8 @@ export type MessagesTimelineRow =
       id: string;
       createdAt: string | null;
       snapshot: WorktreeSetupSnapshot;
+      /** The agent already started; render only the script row under the turn header. */
+      embedded: boolean;
     };
 
 export interface StableMessagesTimelineRowsState {
@@ -1260,15 +1262,20 @@ export function deriveMessagesTimelineRows(input: {
     });
   }
 
-  // The setup card takes the place of the working and thinking placeholders
-  // while a worktree is being prepared. It stays after the setup settles so a
-  // failure and its actions remain visible until the thread state moves on.
-  if (input.worktreeSetup) {
+  // Until the agent starts, the setup card takes the place of the working and
+  // thinking placeholders. It stays after a failed or cancelled setup so the
+  // outcome and its actions remain visible until the thread state moves on.
+  const setupAgentStarted =
+    input.worktreeSetup !== null &&
+    input.worktreeSetup !== undefined &&
+    worktreeSetupAgentStarted(input.worktreeSetup);
+  if (input.worktreeSetup && !setupAgentStarted) {
     const setupRow = {
       kind: "worktree-setup",
       id: WORKTREE_SETUP_ROW_ID,
       createdAt: input.worktreeSetup.startedAt,
       snapshot: input.worktreeSetup,
+      embedded: false,
     } as const;
     // Sit directly under the first user message: a finished snapshot can
     // outlive the first assistant reply, and it belongs to the send, not the
@@ -1287,6 +1294,25 @@ export function deriveMessagesTimelineRows(input: {
   if (input.isWorking && activeTurnHeaderIndex === input.timelineEntries.length) {
     appendWorkingRow();
   }
+  // An async setup script outlives the handoff. The turn owns the header, so
+  // the script's row sits first under it, ahead of the agent's own work.
+  if (input.worktreeSetup && setupAgentStarted) {
+    const setupRow = {
+      kind: "worktree-setup",
+      id: WORKTREE_SETUP_ROW_ID,
+      createdAt: input.worktreeSetup.startedAt,
+      snapshot: input.worktreeSetup,
+      embedded: true,
+    } as const;
+    const workingRowIndex = nextRows.findIndex((row) => row.kind === "working");
+    if (workingRowIndex >= 0) {
+      nextRows.splice(workingRowIndex + 1, 0, setupRow);
+    } else {
+      // The turn already finished (or has not been dispatched yet): the row
+      // trails the reply so a still-running script stays visible after it.
+      nextRows.push(setupRow);
+    }
+  }
   if (input.isWorking && (!hasActivityRow || latestToolFailed)) {
     nextRows.push({
       kind: "thinking",
@@ -1300,6 +1326,11 @@ export function deriveMessagesTimelineRows(input: {
 
 export const WORKTREE_SETUP_ROW_ID = "worktree-setup-row";
 
+/** True once the bootstrap handed off to the agent (async setup script may still run). */
+export function worktreeSetupAgentStarted(snapshot: WorktreeSetupSnapshot): boolean {
+  return snapshot.stages.some((stage) => stage.id === "agent" && stage.status === "done");
+}
+
 type MessagesTimelineRowsInput = Parameters<typeof deriveMessagesTimelineRows>[0];
 
 export interface MessagesTimelineRowsProjection {
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index bc3a66f4e28c..b6383724e036 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -1464,8 +1464,11 @@ function WorktreeSetupTimelineRow({
   return (
     <WorktreeSetupCard
       snapshot={row.snapshot}
-      onCancel={ctx.onCancelWorktreeSetup}
-      onWorkLocally={row.snapshot.phase === "running" ? ctx.onWorktreeSetupWorkLocally : null}
+      embedded={row.embedded}
+      onCancel={row.embedded ? null : ctx.onCancelWorktreeSetup}
+      onWorkLocally={
+        !row.embedded && row.snapshot.phase === "running" ? ctx.onWorktreeSetupWorkLocally : null
+      }
       onOpenTerminal={onOpenTerminal}
     />
   );
diff --git a/apps/web/src/components/chat/WorktreeSetupCard.tsx b/apps/web/src/components/chat/WorktreeSetupCard.tsx
index 8b838fb81cc9..6fe54269cd10 100644
--- a/apps/web/src/components/chat/WorktreeSetupCard.tsx
+++ b/apps/web/src/components/chat/WorktreeSetupCard.tsx
@@ -10,16 +10,16 @@ import {
   ChevronRightIcon,
   CircleAlertIcon,
   CircleIcon,
-  GitBranchIcon,
   LaptopIcon,
   MinusIcon,
   TerminalIcon,
   XIcon,
 } from "lucide-react";
-import { useEffect, useState } from "react";
+import { useEffect, useState, type ReactNode } from "react";
 
 import { Button } from "~/components/ui/button";
 import { Spinner } from "~/components/ui/spinner";
+import { observeVisibleAnimation } from "~/lib/visibleAnimation";
 import { cn } from "~/lib/utils";
 
 interface WorktreeSetupCardProps {
@@ -74,20 +74,95 @@ function StageIcon({ status }: { status: WorktreeSetupStage["status"] }) {
 
 function stageRowClassName(status: WorktreeSetupStage["status"]): string {
   switch (status) {
-    case "running":
-      return "text-foreground";
     case "failed":
       return "text-destructive-foreground";
     case "warning":
       return "text-warning-foreground";
     case "pending":
+      return "text-secondary-label opacity-40";
+    case "running":
     case "skipped":
-      return "text-secondary-label opacity-50";
     case "done":
       return "text-secondary-label";
   }
 }
 
+/** Same shimmer treatment as the live tool rows in the timeline. */
+function ShimmerOverlay({ children }: { children: ReactNode }) {
+  return (
+    <span
+      aria-hidden
+      className="live-activity-focus pointer-events-none absolute inset-y-0 select-none"
+    >
+      <span className="live-activity-focus-counter block">
+        <span className="live-activity-focus-aligned block text-foreground">{children}</span>
+      </span>
+    </span>
+  );
+}
+
+function headerLabel(snapshot: WorktreeSetupSnapshot): string {
+  switch (snapshot.phase) {
+    case "running":
+      return "Setting up worktree…";
+    case "done":
+      return snapshot.stages.some((stage) => stage.status === "failed")
+        ? "Worktree ready, setup script failed"
+        : "Worktree ready";
+    case "failed":
+      return "Worktree setup failed";
+    case "cancelled":
+      return "Worktree setup cancelled";
+  }
+}
+
+/**
+ * Occupies the same slot, with the same metrics, as the "Working for" header
+ * so the handoff to the agent's turn only swaps the text.
+ */
+function SetupHeaderRow({
+  snapshot,
+  totalElapsed,
+}: {
+  snapshot: WorktreeSetupSnapshot;
+  totalElapsed: number | null;
+}) {
+  const running = snapshot.phase === "running";
+  const failed = snapshot.phase === "failed";
+  const finishedWithFailedStage =
+    snapshot.phase === "done" && snapshot.stages.some((stage) => stage.status === "failed");
+  const text = headerLabel(snapshot);
+  const tone = failed
+    ? "text-destructive-foreground"
+    : finishedWithFailedStage
+      ? "text-warning-foreground"
+      : "text-muted-foreground";
+  return (
+    <div className="border-b border-border/60 pb-2 pt-1">
+      <div
+        className={cn(
+          "flex h-6 min-w-0 items-baseline gap-2 px-1 text-sm leading-relaxed tabular-nums",
+          tone,
+        )}
+      >
+        <span
+          ref={running ? observeVisibleAnimation : undefined}
+          className="relative min-w-0 shrink overflow-hidden whitespace-nowrap"
+        >
+          <span className="block truncate">{text}</span>
+          {running ? <ShimmerOverlay>{text}</ShimmerOverlay> : null}
+        </span>
+        {totalElapsed !== null ? (
+          <span className="ml-auto shrink-0 text-xs text-muted-foreground">
+            {formatDuration(totalElapsed)}
+          </span>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+/** One stage, rendered like a live work entry row. */
 function StageRow({
   stage,
   nowMs,
@@ -100,44 +175,49 @@ function StageRow({
   const elapsed = stageElapsedMs(stage, nowMs);
   const label =
     stage.id === "setup-script" && scriptName ? scriptName : worktreeSetupStageLabel(stage.id);
-  const showBar = stage.id === "checkout" && stage.status === "running" && stage.percent !== null;
+  const running = stage.status === "running";
   const trailing =
     stage.status === "pending"
       ? null
       : stage.status === "skipped"
         ? (stage.detail ?? "skipped")
-        : stage.detail;
-
+        : stage.id === "checkout" && running && stage.percent !== null
+          ? `${stage.percent}%`
+          : stage.detail;
   return (
     <div
+      ref={running ? observeVisibleAnimation : undefined}
       className={cn(
-        "flex min-h-6 items-center gap-1.5 px-0.5 py-0.5 text-sm leading-relaxed",
+        "relative flex min-h-6 min-w-0 items-center gap-1.5 overflow-hidden rounded-md px-0.5 py-0.5 text-sm leading-relaxed",
         stageRowClassName(stage.status),
       )}
       data-worktree-setup-stage={stage.id}
       data-worktree-setup-status={stage.status}
     >
-      <span className="flex size-6 shrink-0 items-center justify-center">
+      <span className="flex size-6 shrink-0 items-center justify-center text-icon-muted">
         <StageIcon status={stage.status} />
       </span>
       <span className="min-w-0 flex-1 truncate">{label}</span>
-      <span className="flex min-w-0 items-center gap-2 text-xs text-muted-foreground tabular-nums">
-        {showBar ? (
-          <>
-            <span className="h-1 w-18 overflow-hidden rounded-full bg-input">
-              <span
-                className="block h-full rounded-full bg-primary"
-                style={{ width: `${stage.percent ?? 0}%` }}
-              />
+      {trailing ? (
+        <span className="min-w-0 truncate text-xs text-muted-foreground tabular-nums">
+          {trailing}
+        </span>
+      ) : null}
+      {elapsed !== null && stage.status !== "skipped" && stage.status !== "pending" ? (
+        <span className="shrink-0 text-xs text-muted-foreground tabular-nums">
+          {formatDuration(elapsed)}
+        </span>
+      ) : null}
+      {running ? (
+        <ShimmerOverlay>
+          <span className="flex min-h-6 items-center gap-1.5 px-0.5 py-0.5">
+            <span className="flex size-6 shrink-0 items-center justify-center">
+              <StageIcon status={stage.status} />
             </span>
-            <span className="text-foreground">{stage.percent}%</span>
-          </>
-        ) : null}
-        {!showBar && trailing ? <span className="truncate">{trailing}</span> : null}
-        {elapsed !== null && stage.status !== "skipped" && stage.status !== "pending" ? (
-          <span>{formatDuration(elapsed)}</span>
-        ) : null}
-      </span>
+            <span className="min-w-0 flex-1 truncate">{label}</span>
+          </span>
+        </ShimmerOverlay>
+      ) : null}
     </div>
   );
 }
@@ -158,19 +238,35 @@ function OutputTail({ lines, failed }: { lines: ReadonlyArray<string>; failed: b
   );
 }
 
-function headerLabel(snapshot: WorktreeSetupSnapshot): string {
-  switch (snapshot.phase) {
-    case "running":
-      return "Creating worktree";
-    case "done":
-      return snapshot.stages.some((stage) => stage.status === "failed")
-        ? "Worktree ready, setup script failed"
-        : "Worktree ready";
-    case "failed":
-      return "Worktree setup failed";
-    case "cancelled":
-      return "Worktree setup cancelled";
-  }
+function SetupDetails({ snapshot }: { snapshot: WorktreeSetupSnapshot }) {
+  return (
+    <dl className="mt-1 mb-1.5 ml-8 grid grid-cols-[auto_1fr] gap-x-3 gap-y-0.5 text-xs text-muted-foreground">
+      {snapshot.branch ? (
+        <>
+          <dt className="text-foreground/80">Branch</dt>
+          <dd className="truncate font-mono">{snapshot.branch}</dd>
+        </>
+      ) : null}
+      {snapshot.baseRef ? (
+        <>
+          <dt className="text-foreground/80">Base</dt>
+          <dd className="truncate font-mono">{snapshot.baseRef}</dd>
+        </>
+      ) : null}
+      {snapshot.worktreePath ? (
+        <>
+          <dt className="text-foreground/80">Path</dt>
+          <dd className="truncate font-mono">{snapshot.worktreePath}</dd>
+        </>
+      ) : null}
+      {snapshot.setupScript ? (
+        <>
+          <dt className="text-foreground/80">Setup</dt>
+          <dd className="truncate font-mono">{snapshot.setupScript.command}</dd>
+        </>
+      ) : null}
+    </dl>
+  );
 }
 
 export function WorktreeSetupCard({
@@ -178,7 +274,14 @@ export function WorktreeSetupCard({
   onCancel,
   onWorkLocally,
   onOpenTerminal,
-}: WorktreeSetupCardProps) {
+  embedded = false,
+}: WorktreeSetupCardProps & {
+  /**
+   * The agent already started (async setup script), so the turn owns the
+   * "Working for" header and only the script's row sits among the worklog.
+   */
+  embedded?: boolean;
+}) {
   const running = snapshot.phase === "running";
   const nowMs = useNowWhile(running);
   const [detailsOpen, setDetailsOpen] = useState(false);
@@ -188,79 +291,35 @@ export function WorktreeSetupCard({
     return Number.isFinite(start) && Number.isFinite(end) ? Math.max(0, end - start) : null;
   })();
   const setupStage = snapshot.stages.find((stage) => stage.id === "setup-script");
-  const failed = snapshot.phase === "failed";
-  const finishedWithFailedStage =
-    snapshot.phase === "done" && snapshot.stages.some((stage) => stage.status === "failed");
-  const headerClassName = failed
-    ? "text-destructive-foreground"
-    : finishedWithFailedStage
-      ? "text-warning-foreground"
-      : snapshot.phase === "cancelled"
-        ? "text-muted-foreground"
-        : "text-secondary-label";
+  const showTerminal = onOpenTerminal && setupStage && setupStage.status !== "pending";
+  const stages = embedded
+    ? snapshot.stages.filter((stage) => stage.id === "setup-script")
+    : snapshot.stages;
 
   return (
-    <section
-      aria-label="Worktree setup"
-      className="mt-3 rounded-lg border border-border bg-card/60 px-2.5 pt-1.5 pb-2"
-      data-worktree-setup-phase={snapshot.phase}
-    >
-      <div className={cn("flex min-h-6 items-center gap-1.5 px-0.5 text-sm", headerClassName)}>
-        <span className="flex size-6 shrink-0 items-center justify-center text-icon-muted">
-          <GitBranchIcon aria-hidden className="size-4 shrink-0 stroke-[1.8]" />
-        </span>
-        <span className="min-w-0 flex-1 truncate">{headerLabel(snapshot)}</span>
-        {totalElapsed !== null ? (
-          <span className="shrink-0 text-xs text-muted-foreground tabular-nums">
-            {formatDuration(totalElapsed)}
-          </span>
-        ) : null}
+    <section aria-label="Worktree setup" data-worktree-setup-phase={snapshot.phase}>
+      {embedded ? null : <SetupHeaderRow snapshot={snapshot} totalElapsed={totalElapsed} />}
+      <div className={embedded ? undefined : "pt-1.5"}>
+        {stages.map((stage) => (
+          <div key={stage.id}>
+            <StageRow stage={stage} nowMs={nowMs} scriptName={snapshot.setupScript?.name ?? null} />
+            {stage.id === "setup-script" &&
+            (stage.status === "running" || stage.status === "failed") ? (
+              <OutputTail lines={stage.tail} failed={stage.status === "failed"} />
+            ) : null}
+          </div>
+        ))}
       </div>
 
-      {snapshot.stages.map((stage) => (
-        <div key={stage.id}>
-          <StageRow stage={stage} nowMs={nowMs} scriptName={snapshot.setupScript?.name ?? null} />
-          {stage.id === "setup-script" &&
-          (stage.status === "running" || stage.status === "failed") ? (
-            <OutputTail lines={stage.tail} failed={stage.status === "failed"} />
-          ) : null}
-        </div>
-      ))}
-
-      {failed && snapshot.error ? (
-        <p className="mt-1 px-0.5 text-xs text-muted-foreground">{snapshot.error}</p>
+      {snapshot.phase === "failed" && snapshot.error ? (
+        <p className="mt-1 ml-8 text-xs text-muted-foreground">{snapshot.error}</p>
       ) : null}
 
-      {detailsOpen ? (
-        <dl className="mt-1 mb-1.5 ml-8 grid grid-cols-[auto_1fr] gap-x-3 gap-y-0.5 text-xs text-muted-foreground">
-          {snapshot.branch ? (
-            <>
-              <dt className="text-foreground/80">Branch</dt>
-              <dd className="truncate font-mono">{snapshot.branch}</dd>
-            </>
-          ) : null}
-          {snapshot.baseRef ? (
-            <>
-              <dt className="text-foreground/80">Base</dt>
-              <dd className="truncate font-mono">{snapshot.baseRef}</dd>
-            </>
-          ) : null}
-          {snapshot.worktreePath ? (
-            <>
-              <dt className="text-foreground/80">Path</dt>
-              <dd className="truncate font-mono">{snapshot.worktreePath}</dd>
-            </>
-          ) : null}
-          {snapshot.setupScript ? (
-            <>
-              <dt className="text-foreground/80">Setup</dt>
-              <dd className="truncate font-mono">{snapshot.setupScript.command}</dd>
-            </>
-          ) : null}
-        </dl>
-      ) : null}
+      {detailsOpen ? <SetupDetails snapshot={snapshot} /> : null}
 
-      <div className="mt-1 flex flex-wrap items-center gap-1.5">
+      {/* Indented so the first label lines up with the stage labels: the icon
+          column, minus the xs button's own horizontal padding. */}
+      <div className="mt-0.5 ml-[calc(--spacing(6)+2px-(--spacing(2)-1px))] flex flex-wrap items-center gap-0.5">
         <Button
           type="button"
           size="xs"
@@ -271,21 +330,20 @@ export function WorktreeSetupCard({
           {detailsOpen ? <ChevronDownIcon aria-hidden /> : <ChevronRightIcon aria-hidden />}
           Details
         </Button>
-        <span className="flex-1" />
-        {onOpenTerminal && setupStage && setupStage.status !== "pending" ? (
-          <Button type="button" size="xs" variant="outline" onClick={onOpenTerminal}>
+        {showTerminal ? (
+          <Button type="button" size="xs" variant="ghost-muted" onClick={onOpenTerminal}>
             <TerminalIcon aria-hidden />
             Open terminal
           </Button>
         ) : null}
         {onWorkLocally ? (
-          <Button type="button" size="xs" variant="outline" onClick={onWorkLocally}>
+          <Button type="button" size="xs" variant="ghost-muted" onClick={onWorkLocally}>
             <LaptopIcon aria-hidden />
             Work locally
           </Button>
         ) : null}
         {onCancel && running ? (
-          <Button type="button" size="xs" variant="outline" onClick={onCancel}>
+          <Button type="button" size="xs" variant="ghost-muted" onClick={onCancel}>
             <XIcon aria-hidden />
             Cancel
           </Button>
diff --git a/apps/web/src/components/projectScriptEditor.tsx b/apps/web/src/components/projectScriptEditor.tsx
index 74b189a02fc5..774398feda06 100644
--- a/apps/web/src/components/projectScriptEditor.tsx
+++ b/apps/web/src/components/projectScriptEditor.tsx
@@ -85,6 +85,8 @@ export interface NewProjectScriptInput {
   command: string;
   icon: ProjectScriptIcon;
   runOnWorktreeCreate: boolean;
+  /** Setup scripts only: hold the agent until the script exits. */
+  waitForSetup: boolean;
   keybinding: string | null;
   /** Optional URL to open in the in-app preview when this script runs. */
   previewUrl: string | null;
@@ -99,6 +101,7 @@ export const EMPTY_PROJECT_SCRIPT_INPUT: NewProjectScriptInput = {
   command: "",
   icon: "play",
   runOnWorktreeCreate: false,
+  waitForSetup: false,
   keybinding: null,
   previewUrl: null,
   autoOpenPreview: false,
@@ -123,6 +126,7 @@ export function editorRequestForScript(
       command: script.command,
       icon: script.icon,
       runOnWorktreeCreate: script.runOnWorktreeCreate,
+      waitForSetup: script.runOnWorktreeCreate && script.async === false,
       keybinding: keybindingValueForCommand(keybindings, commandForProjectScript(script.id)),
       previewUrl: script.previewUrl ?? null,
       autoOpenPreview: script.autoOpenPreview ?? false,
@@ -158,6 +162,7 @@ export function ProjectScriptEditorDialog({
   const [icon, setIcon] = useState<ProjectScriptIcon>("play");
   const [iconPickerOpen, setIconPickerOpen] = useState(false);
   const [runOnWorktreeCreate, setRunOnWorktreeCreate] = useState(false);
+  const [waitForSetup, setWaitForSetup] = useState(false);
   const [keybinding, setKeybinding] = useState("");
   const [previewUrl, setPreviewUrl] = useState("");
   const [autoOpenPreview, setAutoOpenPreview] = useState(false);
@@ -188,6 +193,7 @@ export function ProjectScriptEditorDialog({
     setIcon(request.initial.icon);
     setIconPickerOpen(false);
     setRunOnWorktreeCreate(request.initial.runOnWorktreeCreate);
+    setWaitForSetup(request.initial.waitForSetup);
     setKeybinding(request.initial.keybinding ?? "");
     setPreviewUrl(request.initial.previewUrl ?? "");
     setAutoOpenPreview(request.initial.autoOpenPreview);
@@ -247,6 +253,7 @@ export function ProjectScriptEditorDialog({
         command: trimmedCommand,
         icon,
         runOnWorktreeCreate,
+        waitForSetup: runOnWorktreeCreate && waitForSetup,
         keybinding: keybindingRule?.key ?? null,
         previewUrl: trimmedPreviewUrl.length > 0 ? trimmedPreviewUrl : null,
         autoOpenPreview: trimmedPreviewUrl.length > 0 ? autoOpenPreview : false,
@@ -396,6 +403,18 @@ export function ProjectScriptEditorDialog({
                     onCheckedChange={(checked) => setRunOnWorktreeCreate(Boolean(checked))}
                   />
                 </label>
+                <label
+                  className={`flex items-center justify-between gap-3 rounded-md border border-border/70 px-3 py-2 text-sm dark:border-transparent dark:bg-white/[0.035] ${
+                    runOnWorktreeCreate ? "" : "opacity-60"
+                  }`}
+                >
+                  <span>Wait for it to finish before the agent starts</span>
+                  <Switch
+                    checked={waitForSetup}
+                    disabled={!runOnWorktreeCreate}
+                    onCheckedChange={(checked) => setWaitForSetup(Boolean(checked))}
+                  />
+                </label>
                 <label
                   className={`flex items-center justify-between gap-3 rounded-md border border-border/70 px-3 py-2 text-sm dark:border-transparent dark:bg-white/[0.035] ${
                     previewUrl.trim().length === 0 ? "opacity-60" : ""
diff --git a/apps/web/src/components/settings/ProjectActionsSettings.tsx b/apps/web/src/components/settings/ProjectActionsSettings.tsx
index aa4d7077ff6e..edbde5e7439a 100644
--- a/apps/web/src/components/settings/ProjectActionsSettings.tsx
+++ b/apps/web/src/components/settings/ProjectActionsSettings.tsx
@@ -111,6 +111,7 @@ export function ProjectActionsSettings() {
         command: fileScript.command,
         icon: fileScript.icon ?? "play",
         runOnWorktreeCreate: fileScript.runOnWorktreeCreate ?? false,
+        waitForSetup: fileScript.runOnWorktreeCreate === true && fileScript.async === false,
         keybinding: null,
         previewUrl: fileScript.previewUrl ?? null,
         autoOpenPreview: fileScript.previewUrl ? (fileScript.autoOpenPreview ?? false) : false,
diff --git a/apps/web/src/projectScripts.test.ts b/apps/web/src/projectScripts.test.ts
index a09a18d03b35..a1ed2afb989d 100644
--- a/apps/web/src/projectScripts.test.ts
+++ b/apps/web/src/projectScripts.test.ts
@@ -23,6 +23,7 @@ describe("projectScripts helpers", () => {
         command: "pnpm dev",
         icon: "debug",
         runOnWorktreeCreate: false,
+        waitForSetup: false,
         previewUrl: "http://localhost:5733",
         autoOpenPreview: true,
       }),
@@ -44,6 +45,7 @@ describe("projectScripts helpers", () => {
         command: "pnpm test",
         icon: "test",
         runOnWorktreeCreate: false,
+        waitForSetup: false,
         previewUrl: null,
         autoOpenPreview: false,
       }),
@@ -56,6 +58,25 @@ describe("projectScripts helpers", () => {
     });
   });
 
+  it("only records async: false for setup scripts that should block the agent", () => {
+    const input = {
+      name: "Setup",
+      command: "pnpm i",
+      icon: "configure",
+      previewUrl: null,
+      autoOpenPreview: false,
+    } as const;
+    expect(
+      buildProjectScript("setup", { ...input, runOnWorktreeCreate: true, waitForSetup: true }),
+    ).toMatchObject({ runOnWorktreeCreate: true, async: false });
+    expect(
+      buildProjectScript("setup", { ...input, runOnWorktreeCreate: true, waitForSetup: false }),
+    ).not.toHaveProperty("async");
+    expect(
+      buildProjectScript("setup", { ...input, runOnWorktreeCreate: false, waitForSetup: true }),
+    ).not.toHaveProperty("async");
+  });
+
   it("builds and parses script run commands", () => {
     const command = commandForProjectScript("lint");
     expect(command).toBe("script.lint.run");
diff --git a/apps/web/src/projectScripts.ts b/apps/web/src/projectScripts.ts
index 20d06c9c572a..f0bcb5301419 100644
--- a/apps/web/src/projectScripts.ts
+++ b/apps/web/src/projectScripts.ts
@@ -12,6 +12,7 @@ export interface ProjectScriptInput {
   readonly command: ProjectScript["command"];
   readonly icon: ProjectScript["icon"];
   readonly runOnWorktreeCreate: ProjectScript["runOnWorktreeCreate"];
+  readonly waitForSetup: boolean;
   readonly previewUrl: Exclude<ProjectScript["previewUrl"], undefined> | null;
   readonly autoOpenPreview: boolean;
 }
@@ -23,6 +24,7 @@ export function buildProjectScript(id: string, input: ProjectScriptInput): Proje
     command: input.command,
     icon: input.icon,
     runOnWorktreeCreate: input.runOnWorktreeCreate,
+    ...(input.runOnWorktreeCreate && input.waitForSetup ? { async: false } : {}),
     ...(input.previewUrl === null
       ? {}
       : {
diff --git a/packages/contracts/src/orchestration.ts b/packages/contracts/src/orchestration.ts
index 7b1fd2f96597..1bb11ba0a673 100644
--- a/packages/contracts/src/orchestration.ts
+++ b/packages/contracts/src/orchestration.ts
@@ -404,6 +404,12 @@ export const ProjectScript = Schema.Struct({
   command: TrimmedNonEmptyString,
   icon: ProjectScriptIcon,
   runOnWorktreeCreate: Schema.Boolean,
+  /**
+   * For `runOnWorktreeCreate` scripts: when false, the agent's first turn waits
+   * for the script to exit. Absent or true starts the agent right away and
+   * lets the script finish in the background.
+   */
+  async: Schema.optional(Schema.Boolean),
   /**
    * URL to open in the in-app browser preview when this script runs (or
    * when the user explicitly requests a preview). Optional; only honored on
diff --git a/packages/contracts/src/t3ProjectFile.test.ts b/packages/contracts/src/t3ProjectFile.test.ts
index ed19c6d69887..4352449c7ade 100644
--- a/packages/contracts/src/t3ProjectFile.test.ts
+++ b/packages/contracts/src/t3ProjectFile.test.ts
@@ -20,12 +20,14 @@ describe("T3ProjectFile", () => {
           autoOpenPreview: true,
         },
         { name: "Test", command: "pnpm test" },
+        { name: "Setup", command: "pnpm i", runOnWorktreeCreate: true, async: false },
       ],
     });
 
     expect(decoded.iconPath).toBe("assets/logo.svg");
-    expect(decoded.scripts).toHaveLength(2);
+    expect(decoded.scripts).toHaveLength(3);
     expect(decoded.scripts?.[1]).toEqual({ name: "Test", command: "pnpm test" });
+    expect(decoded.scripts?.[2]?.async).toBe(false);
   });
 
   it("decodes an empty object and ignores unknown fields", () => {
diff --git a/packages/contracts/src/t3ProjectFile.ts b/packages/contracts/src/t3ProjectFile.ts
index 5062a1a370b5..6bd4168054d5 100644
--- a/packages/contracts/src/t3ProjectFile.ts
+++ b/packages/contracts/src/t3ProjectFile.ts
@@ -42,6 +42,12 @@ export const T3ProjectFileScript = Schema.Struct({
         "When true, the script runs automatically after a worktree is created for a new thread.",
     }),
   ),
+  async: Schema.optionalKey(
+    Schema.Boolean.annotate({
+      description:
+        "Only for runOnWorktreeCreate scripts. When true (the default), the agent starts while the script is still running. Set false to hold the agent until the script exits.",
+    }),
+  ),
   previewUrl: Schema.optionalKey(
     trimmedNonEmpty({
       description:
diff --git a/packages/shared/src/t3ProjectFile.test.ts b/packages/shared/src/t3ProjectFile.test.ts
index a1986ff35f9b..924a01c4414b 100644
--- a/packages/shared/src/t3ProjectFile.test.ts
+++ b/packages/shared/src/t3ProjectFile.test.ts
@@ -44,6 +44,7 @@ describe("buildT3ProjectFileJsonSchema", () => {
     const script = schema.properties.scripts?.items;
     expect(script?.required).toEqual(["name", "command"]);
     expect(Object.keys(script?.properties ?? {}).sort()).toEqual([
+      "async",
       "autoOpenPreview",
       "command",
       "icon",

From 073f3d712cf6b3275fb3f623136984af694265ef Mon Sep 17 00:00:00 2001
From: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
Date: Mon, 14 Sep 2026 17:33:03 -0700
Subject: [PATCH 2/4] chore(web): keep worktreeSetupAgentStarted module-private

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/web/src/components/chat/MessagesTimeline.logic.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/web/src/components/chat/MessagesTimeline.logic.ts b/apps/web/src/components/chat/MessagesTimeline.logic.ts
index 6f3be2ab3ead..b83f0d75d49a 100644
--- a/apps/web/src/components/chat/MessagesTimeline.logic.ts
+++ b/apps/web/src/components/chat/MessagesTimeline.logic.ts
@@ -1327,7 +1327,7 @@ export function deriveMessagesTimelineRows(input: {
 export const WORKTREE_SETUP_ROW_ID = "worktree-setup-row";
 
 /** True once the bootstrap handed off to the agent (async setup script may still run). */
-export function worktreeSetupAgentStarted(snapshot: WorktreeSetupSnapshot): boolean {
+function worktreeSetupAgentStarted(snapshot: WorktreeSetupSnapshot): boolean {
   return snapshot.stages.some((stage) => stage.id === "agent" && stage.status === "done");
 }
 

From 625e6a099b00fd500df6fae14cfe85d4ffe363e4 Mon Sep 17 00:00:00 2001
From: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
Date: Mon, 14 Sep 2026 17:36:11 -0700
Subject: [PATCH 3/4] fix: consume the setup script listener even if the turn
 dispatch fails; clear the handoff entry on any settled setup

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 apps/server/src/ws.ts                | 13 +++++++++----
 apps/web/src/components/ChatView.tsx | 16 ++++++++++------
 2 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index 4ae84c3c2f43..a3d8bbba577e 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -1203,7 +1203,11 @@ const makeWsRpcLayer = (
               // The setup script is best effort, like the untracked path: a
               // failed install must not throw away the worktree the user just
               // waited for. The card keeps the failed stage and its terminal.
-              const awaitCompletion = setupResult.completion.pipe(
+              // Forked right away so the terminal listener behind `completion`
+              // is always consumed, even when the turn dispatch fails before
+              // anyone would otherwise wait on it. The tracker update is a
+              // no-op once the snapshot has been dropped.
+              const completionFiber = yield* setupResult.completion.pipe(
                 Effect.flatMap((completion) => {
                   if (completion.exitCode === 0) {
                     return worktreeSetupTracker.stageStatus(threadId, "setup-script", "done");
@@ -1219,12 +1223,13 @@ const makeWsRpcLayer = (
                     detail,
                   );
                 }),
+                Effect.forkDetach,
               );
               if (!setupResult.async) {
-                yield* awaitCompletion;
+                yield* Fiber.join(completionFiber);
                 return null;
               }
-              return awaitCompletion;
+              return completionFiber;
             });
 
           const bootstrapProgram = Effect.gen(function* () {
@@ -1443,7 +1448,7 @@ const makeWsRpcLayer = (
             // the wait cannot fail the dispatch.
             const settle = track(worktreeSetupTracker.finish(threadId, "done"));
             if (pendingSetupScript) {
-              yield* pendingSetupScript.pipe(
+              yield* Fiber.join(pendingSetupScript).pipe(
                 Effect.ignoreCause({ log: true }),
                 Effect.andThen(settle),
                 Effect.forkDetach,
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index f2fc5aa069ef..6b8c65410edb 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -3525,14 +3525,18 @@ export default function ChatView(props: ChatViewProps) {
     (!isWorking || !worktreeSetup.stages.some((stage) => stage.status === "failed"));
   useEffect(() => {
     if (!worktreeSetupDoneAndTurnVisible) return;
-    if (worktreeSetupRef) {
-      pendingWorktreeSetupByThreadKey.delete(
-        scopedThreadKey(scopeThreadRef(worktreeSetupRef.environmentId, worktreeSetupRef.threadId)),
-      );
-    }
     setWorktreeSetupRef(null);
     setHeldWorktreeSetup(null);
-  }, [worktreeSetupDoneAndTurnVisible, worktreeSetupRef]);
+  }, [worktreeSetupDoneAndTurnVisible]);
+  // The handoff entry only matters while the setup is still running: once it
+  // settles in any phase, a later mount of the thread must not adopt it.
+  const worktreeSetupSettledKey =
+    worktreeSetup && worktreeSetup.phase !== "running" && worktreeSetupRef
+      ? scopedThreadKey(scopeThreadRef(worktreeSetupRef.environmentId, worktreeSetupRef.threadId))
+      : null;
+  useEffect(() => {
+    if (worktreeSetupSettledKey) pendingWorktreeSetupByThreadKey.delete(worktreeSetupSettledKey);
+  }, [worktreeSetupSettledKey]);
   const cancelWorktreeSetup = useAtomCommand(vcsEnvironment.cancelWorktreeSetup, {
     reportFailure: false,
   });

From e303805defdaa89798dd2e3f7b444604768b8fa7 Mon Sep 17 00:00:00 2001
From: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com>
Date: Mon, 14 Sep 2026 17:43:40 -0700
Subject: [PATCH 4/4] fix(web): keep the setup card intact until the turn is
 live

The card switched to the embedded script row as soon as the server marked
the agent stage done, a moment before the turn existed in the timeline, so
the header and stage rows collapsed for a frame and a finished or absent
script rendered an orphan row. Hand off only once the turn has started, and
embed the script row only while it is running or failed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../chat/MessagesTimeline.logic.test.ts       | 57 ++++++++++++++++---
 .../components/chat/MessagesTimeline.logic.ts | 25 +++++---
 2 files changed, 65 insertions(+), 17 deletions(-)

diff --git a/apps/web/src/components/chat/MessagesTimeline.logic.test.ts b/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
index 06a2e49d8948..39cd8f8318a8 100644
--- a/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
+++ b/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
@@ -1170,18 +1170,29 @@ describe("deriveMessagesTimelineRows", () => {
 
     // Once the agent stage is done the setup script may still be running in
     // the background: the turn owns the header and the script row follows it.
-    const agentStage = {
-      id: "agent",
-      status: "done",
-      startedAt: "2026-01-01T00:00:10Z",
-      endedAt: "2026-01-01T00:00:11Z",
-      percent: null,
-      detail: null,
-      tail: [],
+    const stage = (id: "agent" | "setup-script", status: "done" | "running") =>
+      ({
+        id,
+        status,
+        startedAt: "2026-01-01T00:00:10Z",
+        endedAt: status === "done" ? "2026-01-01T00:00:11Z" : null,
+        percent: null,
+        detail: null,
+        tail: [],
+      }) as const;
+    const asyncSnapshot: WorktreeSetupSnapshot = {
+      ...snapshot,
+      stages: [stage("setup-script", "running"), stage("agent", "done")],
+    };
+    const liveTurn = {
+      turnId: "turn-1" as never,
+      state: "running",
+      startedAt: "2026-01-01T00:00:11Z",
+      completedAt: null,
     } as const;
-    const asyncSnapshot: WorktreeSetupSnapshot = { ...snapshot, stages: [agentStage] };
     const asyncRows = deriveMessagesTimelineRows({
       timelineEntries: [userEntry],
+      latestTurn: liveTurn,
       isWorking: true,
       activeTurnStartedAt: "2026-01-01T00:00:00Z",
       turnDiffSummaries: [],
@@ -1195,6 +1206,34 @@ describe("deriveMessagesTimelineRows", () => {
       "thinking",
     ]);
     expect(asyncRows[2]).toMatchObject({ kind: "worktree-setup", embedded: true });
+
+    // Dispatched but not yet visible as a turn: the full card stays put so
+    // nothing collapses during the handoff.
+    const handoffRows = deriveMessagesTimelineRows({
+      timelineEntries: [userEntry],
+      isWorking: true,
+      activeTurnStartedAt: "2026-01-01T00:00:00Z",
+      turnDiffSummaries: [],
+      supportsConversationRollback: false,
+      worktreeSetup: asyncSnapshot,
+    });
+    expect(handoffRows.map((row) => row.kind)).toEqual(["message", "worktree-setup"]);
+    expect(handoffRows[1]).toMatchObject({ kind: "worktree-setup", embedded: false });
+
+    // A script that already finished has nothing left to show once the turn is live.
+    const finishedRows = deriveMessagesTimelineRows({
+      timelineEntries: [userEntry],
+      latestTurn: liveTurn,
+      isWorking: true,
+      activeTurnStartedAt: "2026-01-01T00:00:00Z",
+      turnDiffSummaries: [],
+      supportsConversationRollback: false,
+      worktreeSetup: {
+        ...asyncSnapshot,
+        stages: [stage("setup-script", "done"), stage("agent", "done")],
+      },
+    });
+    expect(finishedRows.map((row) => row.kind)).toEqual(["message", "working", "thinking"]);
   });
 
   it("keeps context compaction visible outside folded work", () => {
diff --git a/apps/web/src/components/chat/MessagesTimeline.logic.ts b/apps/web/src/components/chat/MessagesTimeline.logic.ts
index b83f0d75d49a..89bcf214783f 100644
--- a/apps/web/src/components/chat/MessagesTimeline.logic.ts
+++ b/apps/web/src/components/chat/MessagesTimeline.logic.ts
@@ -1262,14 +1262,17 @@ export function deriveMessagesTimelineRows(input: {
     });
   }
 
-  // Until the agent starts, the setup card takes the place of the working and
-  // thinking placeholders. It stays after a failed or cancelled setup so the
-  // outcome and its actions remain visible until the thread state moves on.
-  const setupAgentStarted =
+  // Until the agent's turn is live, the setup card takes the place of the
+  // working and thinking placeholders. It stays after a failed or cancelled
+  // setup so the outcome and its actions remain visible until the thread
+  // state moves on. "Live" means the turn is in the timeline, not just that
+  // the server dispatched it: the card must not collapse in the gap between.
+  const setupHandedOff =
     input.worktreeSetup !== null &&
     input.worktreeSetup !== undefined &&
-    worktreeSetupAgentStarted(input.worktreeSetup);
-  if (input.worktreeSetup && !setupAgentStarted) {
+    worktreeSetupAgentStarted(input.worktreeSetup) &&
+    input.latestTurn?.startedAt != null;
+  if (input.worktreeSetup && !setupHandedOff) {
     const setupRow = {
       kind: "worktree-setup",
       id: WORKTREE_SETUP_ROW_ID,
@@ -1295,8 +1298,14 @@ export function deriveMessagesTimelineRows(input: {
     appendWorkingRow();
   }
   // An async setup script outlives the handoff. The turn owns the header, so
-  // the script's row sits first under it, ahead of the agent's own work.
-  if (input.worktreeSetup && setupAgentStarted) {
+  // the script's row sits first under it, ahead of the agent's own work. A
+  // script that already finished (or never ran) has nothing left to show.
+  const setupScriptStage = input.worktreeSetup?.stages.find((stage) => stage.id === "setup-script");
+  if (
+    input.worktreeSetup &&
+    setupHandedOff &&
+    (setupScriptStage?.status === "running" || setupScriptStage?.status === "failed")
+  ) {
     const setupRow = {
       kind: "worktree-setup",
       id: WORKTREE_SETUP_ROW_ID,