fix(server): a thread's branch and worktree follow the agent when it moves#15989

@@ -3313,6 +3315,28 @@ export function makeClaudeAdapterV2(
         const emitProviderEvent = (event: ProviderAdapter.ProviderAdapterV2Event) =>
           Queue.offer(events, event).pipe(Effect.asVoid);
 
+        // Live-tracks this session's actual cwd, separately from `session`
+        // (the snapshot ProviderSessionManager first registered this session
+        // with). Claude's EnterWorktree/ExitWorktree tools move the running
+        // session's cwd without going through any T3 command (#11078); the
+        // PostToolUse hook below reports that move here so the server can
+        // follow it at turn end, the same way it already follows a plain
+        // branch change (git checkout) inside an unmoved cwd.
+        const trackedCwd = yield* Ref.make(session.cwd);
+        const followWorktreeCwdChange = Effect.fn("ClaudeAdapterV2.followWorktreeCwdChange")(
+          function* (nextCwd: string) {
+            const previousCwd = yield* Ref.get(trackedCwd);
+            if (nextCwd === previousCwd) return;
+            yield* Ref.set(trackedCwd, nextCwd);
+            const updatedAt = yield* DateTime.now;
+            yield* emitProviderEvent({
+              type: "provider_session.updated",
+              driver: CLAUDE_PROVIDER,
+              providerSession: { ...session, cwd: nextCwd, updatedAt },

@@ -495,6 +495,19 @@ const layerOrchestrationV2Runtime = RuntimeLayer.layerProduction.pipe(
       Layer.provide(ProjectionStoreV2.layer),
       Layer.provide(layerPullRequestService),
       Layer.provide(RuntimeLayer.layerProjectService),
+      // layerThreadManagementProvided is the same orchestrator instance
+      // RuntimeLayer.layerProduction runs; its own remaining requirements
+      // (satisfied for that instance above) must be repeated here too, since a
+      // dependency's open requirements are not inherited from a sibling
+      // `Layer.provide` step. Layer memoization still builds each of these once
+      // and shares it, so this is one orchestrator, not two.
+      Layer.provide(
+        RuntimeLayer.layerThreadManagementProvided.pipe(

@@ -3759,6 +3762,40 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
         const emitProviderEvent = (event: ProviderAdapter.ProviderAdapterV2Event) =>
           Queue.offer(events, event).pipe(Effect.asVoid);
 
+        // A root session can move without a T3 worktree handoff.
+        const trackedCwd = yield* Ref.make(session.cwd);
+        const followWorktreeCwdChange = Effect.fn("ClaudeAdapterV2.followWorktreeCwdChange")(
+          function* (nextCwd: string) {
+            const previousCwd = yield* Ref.get(trackedCwd);
+            if (nextCwd === previousCwd) return;
+            yield* Ref.set(trackedCwd, nextCwd);
+            const updatedAt = yield* DateTime.now;
+            const context = yield* Ref.get(activeTurn);
+            yield* emitProviderEvent({
+              type: "provider_session.updated",
+              driver: CLAUDE_PROVIDER,
+              providerSession: {
+                ...session,
+                cwd: nextCwd,
+                cwdChangeSource: context?.input.runtimePolicy.cwd ?? undefined,
+                updatedAt,
+              },
+            });
+          },
+        );

@@ -94,18 +163,160 @@ export const observerLive = Layer.effect(
     const vcsStatus = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
     const projections = yield* ProjectionStore.ProjectionStoreV2;
     const pullRequests = yield* PullRequestService.PullRequestService;
+    const threads = yield* ThreadManagementService.ThreadManagementService;
+    const projects = yield* ProjectService.ProjectService;
+
+    // A `git checkout`/`git switch` run inside a thread's dedicated worktree
+    // (by the agent or the user) bypasses T3's own commands, so the stamped
+    // branch goes stale (#11078). Follow it here: adopt the checked-out
+    // branch as the thread's branch, but only while the worktree still
+    // belongs to exactly this thread. For a shared worktree, whose branch it
+    // is would be ambiguous, so leave the stamp alone.
+    const followBranchDrift = Effect.fn("RunFinalizationService.followBranchDrift")(function* (
+      thread: OrchestrationV2ThreadShell,
+      refName: string,
+      runId: RunId,
+    ) {
+      // No branch to compare-and-swap against, no dedicated worktree to own
+      // exclusively, or the first-turn auto-rename is still in flight.
+      if (
+        thread.branch === null ||
+        thread.worktreePath === null ||
+        isTemporaryWorktreeBranch(refName)
+      ) {
+        return;
+      }
+      yield* threads
+        .dispatch({
+          type: "thread.metadata.update",
+          // Keyed by the run being finalized, not the branch: a retry of the
+          // same at-least-once effect must reuse this id (see
+          // checkpoint.capture below), but a later run drifting back to an
+          // earlier branch is a fresh occurrence, not a duplicate.
+          commandId: CommandId.make(`command:effect:worktree-branch-drift:${runId}`),
+          threadId: thread.id,
+          branch: refName,
+          expectedBranch: thread.branch,
+          expectedWorktreePath: thread.worktreePath,
+          requireExclusiveWorktree: true,
+        })
+        .pipe(
+          Effect.catch((error) =>
+            Effect.logWarning("failed to follow worktree branch drift after run completion", {
+              threadId: thread.id,
+              previousBranch: thread.branch,
+              branch: refName,
+              category: failureCategory(error),
+            }),
+          ),
+        );
+    });
+
+    // The provider session's own cwd (tracked live by the adapter, e.g. from
+    // Claude's EnterWorktree/ExitWorktree) moving away from the thread's
+    // recorded worktreePath (#11078). Unlike followBranchDrift, the
+    // worktreePath itself is always worth tracking here, so it commits even
+    // into a shared worktree; only the branch adoption is conditional, via
+    // the same exclusivity check (requireExclusiveWorktree).
+    const followWorktreeMove = ({
+      threadId,
+      runId,
+    }: {
+      readonly threadId: ThreadId;
+      readonly runId: RunId;
+    }) =>
+      Effect.gen(function* () {
+        const thread = yield* projections.getThreadShell(threadId);
+        if (!thread) return;
+        if (thread.activeRunId !== null && thread.activeRunId !== runId) return;
+        const providerContext = yield* projections.getThreadProviderContext(threadId);
+        // Most recently updated, not last in array order: ProjectionStoreV2's
+        // SQL path already returns these ordered by updated_at, but
+        // layerMemory does not, so picking explicitly here works under both.
+        const liveCwd = providerContext.providerSessions

@@ -63,6 +90,18 @@ const make = Effect.gen(function* () {
           (cause) => new RunFinalizationError({ ...input, operation: "capture-checkpoint", cause }),
         ),
       );
+    // Best-effort: this follow is independent of (and must not block) the
+    // checkpoint-cwd branch refresh below, so a failure here is logged and
+    // swallowed rather than aborting the rest of finalize.
+    yield* observer.followWorktreeMove({ threadId: input.threadId, runId: input.runId }).pipe(
+      Effect.catchCause((cause) =>
+        Effect.logWarning("worktree-location follow failed", {
+          threadId: input.threadId,
+          runId: input.runId,
+          cause: Cause.pretty(cause),

@@ -436,6 +436,14 @@ const make = Effect.gen(function* () {
               threadId,
               branch: renamed.branch,
               worktreePath: worktreeCwd,
+              // Generation and the actual `git branch -m` both take a beat,
+              // during which the agent can check out a real branch itself
+              // (followBranchDrift then corrects the stamp before this
+              // lands). A compare-and-swap drops the rename instead of
+              // overwriting that correction with a branch nothing has
+              // checked out.
+              expectedBranch: oldBranch,

@@ -94,18 +162,180 @@ export const layerObserver = Layer.effect(
     const vcsStatus = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
     const projections = yield* ProjectionStore.ProjectionStoreV2;
     const pullRequests = yield* PullRequestService.PullRequestService;
+    const threads = yield* ThreadManagementService.ThreadManagementService;
+    const projects = yield* ProjectService.ProjectService;
+
+    // A `git checkout`/`git switch` run inside a thread's dedicated worktree
+    // (by the agent or the user) bypasses T3's own commands, so the stamped
+    // branch goes stale (#11078). Follow it here: adopt the checked-out
+    // branch as the thread's branch, but only while the worktree still
+    // belongs to exactly this thread. For a shared worktree, whose branch it
+    // is would be ambiguous, so leave the stamp alone.
+    // Returns whether it dispatched the follow.
+    const followBranchDrift = Effect.fn("RunFinalizationService.followBranchDrift")(function* (
+      thread: OrchestrationV2ThreadShell,
+      cwd: string,
+      refName: string,
+      runId: RunId,
+    ) {
+      // No branch to compare-and-swap against, no dedicated worktree to own
+      // exclusively, the first-turn auto-rename is still in flight, or `cwd`
+      // is not the thread's worktree. The last one happens when
+      // followWorktreeMove just moved the thread out of the checkpoint cwd:
+      // that cwd's branch belongs to where the thread was, not where it is.
+      if (
+        thread.branch === null ||
+        thread.worktreePath === null ||
+        thread.worktreePath !== cwd ||
+        isTemporaryWorktreeBranch(refName)
+      ) {
+        return false;
+      }
+      yield* threads
+        .dispatch({
+          type: "thread.metadata.update",
+          // Keyed by the run being finalized, not the branch: a retry of the
+          // same at-least-once effect must reuse this id (see
+          // checkpoint.capture below), but a later run drifting back to an
+          // earlier branch is a fresh occurrence, not a duplicate.
+          commandId: CommandId.make(`command:effect:worktree-branch-drift:${runId}`),
+          threadId: thread.id,
+          branch: refName,
+          expectedBranch: thread.branch,
+          expectedWorktreePath: thread.worktreePath,
+          requireExclusiveWorktree: true,
+        })
+        .pipe(
+          Effect.catch((error) =>
+            Effect.logWarning("failed to follow worktree branch drift after run completion", {
+              threadId: thread.id,
+              previousBranch: thread.branch,
+              branch: refName,
+              category: failureCategory(error),
+            }),
+          ),
+        );
+      return true;
+    });
+
+    // The provider session's own cwd (tracked live by the adapter, e.g. from
+    // Claude's EnterWorktree/ExitWorktree) moving away from the thread's
+    // recorded worktreePath (#11078). Unlike followBranchDrift, the
+    // worktreePath itself is always worth tracking here, so it commits even
+    // into a shared worktree; only the branch adoption is conditional, via
+    // the same exclusivity check (requireExclusiveWorktree).
+    const followWorktreeMove = ({
+      threadId,
+      runId,
+    }: {
+      readonly threadId: ThreadId;
+      readonly runId: RunId;
+    }) =>
+      Effect.gen(function* () {
+        const thread = yield* projections.getThreadShell(threadId);
+        if (!thread) return;
+        if (thread.activeRunId !== null && thread.activeRunId !== runId) return;
+        if (thread.activeProviderThreadId === null) return;
+        // The session this thread's own provider thread runs on, not just any
+        // session bound to the thread: a thread can stay bound to sessions
+        // opened elsewhere, whose cwd says nothing about where this agent is.
+        const providerContext = yield* projections.getThreadProviderContext(
+          threadId,
+          thread.providerInstanceId,
+        );
+        const providerSessionId = providerContext.providerThreads.find(
+          (providerThread) => providerThread.id === thread.activeProviderThreadId,
+        )?.providerSessionId;
+        if (providerSessionId == null) return;
+        const liveCwd = providerContext.providerSessions.find(
+          (session) => session.id === providerSessionId,
+        )?.cwd;
+        if (liveCwd === undefined) return;
+        // A shared session has one cwd for every thread on it, so a move may
+        // have been another thread's. Leave the location alone rather than
+        // guess.
+        if (yield* projections.isProviderSessionShared(threadId, providerSessionId)) return;
+        const project = yield* projects.getById(thread.projectId);
+        if (Option.isNone(project)) return;
+        const recordedCwd = thread.worktreePath ?? project.value.workspaceRoot;
+        if (liveCwd === recordedCwd) return;
+
+        const newWorktreePath = liveCwd === project.value.workspaceRoot ? null : liveCwd;
+        const local = yield* vcsStatus.refreshLocalStatus(liveCwd).pipe(
+          Effect.catch((error) =>
+            Effect.logWarning("failed to read git status after a worktree move", {
+              threadId,
+              cwd: liveCwd,
+              category: failureCategory(error),
+            }).pipe(Effect.as(null)),
+          ),
+        );
+        // A detached HEAD or the still-in-flight first-turn placeholder
+        // branch has nothing adoptable; a non-dedicated location (back to
+        // the main checkout) never adopts a branch either.
+        const checkedOutBranch =
+          newWorktreePath !== null &&
+          local !== null &&
+          local.refName !== null &&
+          !isTemporaryWorktreeBranch(local.refName)
+            ? local.refName
+            : null;
+
+        yield* threads
+          .dispatch({
+            type: "thread.metadata.update",
+            // Keyed by the run being finalized: a retry of the same
+            // at-least-once effect must reuse this id, but a later run
+            // moving again is a fresh occurrence, not a duplicate.
+            commandId: CommandId.make(`command:effect:worktree-location-follow:${runId}`),
+            threadId,
+            worktreePath: newWorktreePath,
+            expectedWorktreePath: thread.worktreePath,
+            branch: checkedOutBranch,
+            // The session itself moved and is already working from the new
+            // location; detaching it (the default for an explicit worktree
+            // handoff) would kill useful, in-progress work.
+            preserveProviderSession: true,
+            ...(checkedOutBranch !== null ? { requireExclusiveWorktree: true } : {}),
+          })
+          .pipe(
+            Effect.catch((error) =>
+              Effect.logWarning("failed to follow the provider session into its new worktree", {
+                threadId,
+                worktreePath: newWorktreePath,
+                category: failureCategory(error),
+              }),
+            ),
+          );
+      }).pipe(

@@ -96,18 +198,191 @@ export const layerObserver = Layer.effect(
     const vcsStatus = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
     const projections = yield* ProjectionStore.ProjectionStoreV2;
     const pullRequests = yield* PullRequestService.PullRequestService;
+    const threads = yield* ThreadManagementService.ThreadManagementService;
+    const projects = yield* ProjectService.ProjectService;
+
+    // A `git checkout`/`git switch` run inside a thread's dedicated worktree
+    // (by the agent or the user) bypasses T3's own commands, so the stamped
+    // branch goes stale (#11078). Follow it here: adopt the checked-out
+    // branch as the thread's branch, but only while the worktree still
+    // belongs to exactly this thread. For a shared worktree, whose branch it
+    // is would be ambiguous, so leave the stamp alone.
+    // Returns whether it dispatched the follow.
+    const followBranchDrift = Effect.fn("RunFinalizationService.followBranchDrift")(function* (
+      thread: OrchestrationV2ThreadShell,
+      cwd: string,
+      refName: string,
+      runId: RunId,
+    ) {
+      // No branch to compare-and-swap against, no dedicated worktree to own
+      // exclusively, the first-turn auto-rename is still in flight, or `cwd`
+      // is not the thread's worktree. The last one happens when
+      // followWorktreeMove just moved the thread out of the checkpoint cwd:
+      // that cwd's branch belongs to where the thread was, not where it is.
+      if (
+        thread.branch === null ||
+        thread.worktreePath === null ||
+        thread.worktreePath !== cwd ||
+        isTemporaryWorktreeBranch(refName)
+      ) {
+        return false;

@@ -104,8 +276,12 @@ export const observerLive = Layer.effect(
           );
           if (local.refName === null || local.isDefaultRef) return;
           const thread = yield* projections.getThreadShell(threadId);
-          if (!thread || thread.branch !== local.refName) return;
+          if (!thread) return;
           if (thread.activeRunId !== null && thread.activeRunId !== runId) return;
+          if (thread.branch !== local.refName) {
+            yield* followBranchDrift(thread, local.refName, runId);
+            return;
+          }
           yield* vcsStatus.refreshPullRequestStatus(cwd).pipe(

@@ -2612,6 +2612,30 @@ export const OrchestrationV2Command = Schema.Union([
     branch: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
     worktreePath: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
     expectedWorktreePath: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
+    expectedBranch: Schema.optional(Schema.NullOr(TrimmedNonEmptyString)),
+    /**
+     * Only adopt `branch` while this thread's (new, if `worktreePath` is also
+     * set) worktree is exclusive to it. Set by the server's own
+     * worktree-location follow (#11078): a worktree two threads both point at
+     * makes "whose branch is it" ambiguous. Rechecked against the live
+     * projection when the command is decided, not against a stale read, so a
+     * thread that starts sharing the worktree in between cannot be adopted
+     * into. When `worktreePath` is also present, a shared worktree still
+     * commits with `branch` dropped (the location is always worth tracking;
+     * only adopting its branch is not) rather than rejecting the command;
+     * without a `worktreePath` change, there is nothing else worth keeping,
+     * so the whole command is rejected instead.
+     */
+    requireExclusiveWorktree: Schema.optional(Schema.Boolean),
+    /**

@@ -104,8 +276,12 @@ export const observerLive = Layer.effect(
           );
           if (local.refName === null || local.isDefaultRef) return;
           const thread = yield* projections.getThreadShell(threadId);
-          if (!thread || thread.branch !== local.refName) return;
+          if (!thread) return;
           if (thread.activeRunId !== null && thread.activeRunId !== runId) return;
+          if (thread.branch !== local.refName) {
+            yield* followBranchDrift(thread, local.refName, runId);
+            return;
+          }

@@ -94,8 +133,141 @@ export const observerLive = Layer.effect(
     const vcsStatus = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
     const projections = yield* ProjectionStore.ProjectionStoreV2;
     const pullRequests = yield* PullRequestService.PullRequestService;
+    const threads = yield* ThreadManagementService.ThreadManagementService;
+    const projects = yield* ProjectService.ProjectService;
+
+    // A `git checkout`/`git switch` run inside a thread's dedicated worktree
+    // (by the agent or the user) bypasses T3's own commands, so the stamped
+    // branch goes stale (#11078). Follow it here: adopt the checked-out
+    // branch as the thread's branch, but only while the worktree still
+    // belongs to exactly this thread. For a shared worktree, whose branch it
+    // is would be ambiguous, so leave the stamp alone.
+    const followBranchDrift = Effect.fn("RunFinalizationService.followBranchDrift")(function* (
+      thread: OrchestrationV2ThreadShell,
+      refName: string,
+      runId: RunId,
+    ) {
+      // No branch to compare-and-swap against, no dedicated worktree to own
+      // exclusively, or the first-turn auto-rename is still in flight.
+      if (
+        thread.branch === null ||
+        thread.worktreePath === null ||
+        isTemporaryWorktreeBranch(refName)
+      ) {
+        return;
+      }
+      yield* threads
+        .dispatch({
+          type: "thread.metadata.update",
+          // Keyed by the run being finalized, not the branch: a retry of the
+          // same at-least-once effect must reuse this id (see
+          // checkpoint.capture below), but a later run drifting back to an
+          // earlier branch is a fresh occurrence, not a duplicate.
+          commandId: CommandId.make(`command:effect:worktree-branch-drift:${runId}`),
+          threadId: thread.id,
+          branch: refName,
+          expectedBranch: thread.branch,
+          expectedWorktreePath: thread.worktreePath,
+          requireExclusiveWorktree: true,
+        })
+        .pipe(
+          Effect.catch((error) =>
+            Effect.logWarning("failed to follow worktree branch drift after run completion", {
+              threadId: thread.id,
+              previousBranch: thread.branch,
+              branch: refName,
+              detail: error.message,

@@ -4502,6 +4515,21 @@ export const layer: Layer.Layer<ProjectionStoreV2, never, SqlClient.SqlClient> =
         Effect.map((rows) => rows[0]?.count ?? 0),
         Effect.mapError(controlReadError(threadId)),
       );
+
+    const hasSiblingThreadWithWorktreePath: ProjectionStoreV2Shape["hasSiblingThreadWithWorktreePath"] =
+      (input) =>
+        sql<{ readonly thread_id: string }>`
+          SELECT thread_id FROM orchestration_v2_projection_threads

@@ -6975,6 +6999,27 @@ export function makeClaudeAdapterV2(
             canUseTool,
             onUserDialog,
             supportedDialogKinds: ["resume_return"],
+            hooks: {
+              PostToolUse: [
+                {
+                  matcher: "^(EnterWorktree|ExitWorktree)$",
+                  hooks: [
+                    (hookInput) =>
+                      runPromise(
+                        Effect.gen(function* () {
+                          // agent_id is present only for a subagent's own
+                          // tool call; a subagent's worktree is its own
+                          // isolated concern, not this (root) session's.
+                          if (hookInput.hook_event_name === "PostToolUse" && !hookInput.agent_id) {

@@ -63,6 +120,18 @@ const make = Effect.gen(function* () {
           (cause) => new RunFinalizationError({ ...input, operation: "capture-checkpoint", cause }),
         ),
       );
+    // Best-effort: this follow is independent of (and must not block) the