Clean up worktrees when archiving threads

apps/mobile/src/features/home/threadActionMessages.ts

@@ -0,0 +1,30 @@
+import * as Cause from "effect/Cause";
+
+export type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
+
+const ACTION_VERBS: Record<ThreadListAction, string> = {
+ archive: "archived",
+ unarchive: "unarchived",
+ delete: "deleted",
+ settle: "settled",
+ unsettle: "un-settled",
+};
+
+export function actionFailureMessage(
+ action: ThreadListAction,
+ cause: Cause.Cause<unknown>,
+): string {
+ const error = Cause.squash(cause);
+ if (error instanceof Error && error.message.trim().length > 0) {
+ return error.message;
+ }
+ return `The thread could not be ${ACTION_VERBS[action]}.`;
+}
+
+export function actionFailureTitle(action: ThreadListAction): string {
+ if (action === "archive") return "Could not archive thread";
+ if (action === "unarchive") return "Could not unarchive thread";
+ if (action === "settle") return "Could not settle thread";
+ if (action === "unsettle") return "Could not un-settle thread";
+ return "Could not delete thread";
+}

apps/mobile/src/features/home/useThreadListActions.ts

@@ -1,5 +1,6 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { canSettle } from "@t3tools/client-runtime/state/thread-settled";
+import { runArchiveWithWorktreeCleanup } from "@t3tools/client-runtime/state/worktreeCleanup";
 import * as Cause from "effect/Cause";
 import * as Haptics from "expo-haptics";
 import { useCallback, useRef } from "react";
@@ -11,7 +12,14 @@ import { refreshArchivedThreadsForEnvironment } from "../archive/useArchivedThre
 import { appAtomRegistry } from "../../state/atom-registry";
 import { environmentServerConfigsAtom } from "../../state/server";
 import { threadEnvironment } from "../../state/threads";
+import { vcsEnvironment } from "../../state/vcs";
 import { useAtomCommand } from "../../state/use-atom-command";
+import {
+ actionFailureMessage,
+ actionFailureTitle,
+ type ThreadListAction,
+} from "./threadActionMessages";
+import { presentWorktreeCleanupConfirmation } from "./worktreeCleanupPrompt";
 
 /** Version skew: never send settle/unsettle to a server that predates them
  (capability defaults false on decode for older servers). */
@@ -22,36 +30,10 @@ function environmentSupportsSettlement(environmentId: EnvironmentThreadShell["en
  );
 }
 
-type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
-
-const ACTION_VERBS: Record<ThreadListAction, string> = {
- archive: "archived",
- unarchive: "unarchived",
- delete: "deleted",
- settle: "settled",
- unsettle: "un-settled",
-};
-
-function actionFailureMessage(action: ThreadListAction, cause: Cause.Cause<unknown>): string {
- const error = Cause.squash(cause);
- if (error instanceof Error && error.message.trim().length > 0) {
- return error.message;
- }
- return `The thread could not be ${ACTION_VERBS[action]}.`;
-}
-
 function selectionHaptic(): void {
  void Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
 }
 
-function actionFailureTitle(action: ThreadListAction): string {
- if (action === "archive") return "Could not archive thread";
- if (action === "unarchive") return "Could not unarchive thread";
- if (action === "settle") return "Could not settle thread";
- if (action === "unsettle") return "Could not un-settle thread";
- return "Could not delete thread";
-}
-
 /** Resolves to true iff the action was dispatched and succeeded. */
 function useThreadActionExecutor(
  onCompleted?: (action: ThreadListAction, thread: EnvironmentThreadShell) => void,
@@ -195,12 +177,88 @@ export function useThreadListActions(): {
  readonly unsettleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
 } {
  const executeAction = useThreadActionExecutor();
+ const previewWorktreeCleanup = useAtomCommand(vcsEnvironment.previewWorktreeCleanup, {
+ reportFailure: false,
+ });
+ const cleanupThreadWorktree = useAtomCommand(vcsEnvironment.cleanupThreadWorktree, {
+ reportFailure: false,
+ });
 
  const archiveThread = useCallback(
  (thread: EnvironmentThreadShell) => {
- void executeAction("archive", thread);
+ void runArchiveWithWorktreeCleanup({
+ // Server-authoritative preview; a failure (old server, transient
+ // error) degrades to a plain archive without a prompt. A thread
+ // mid-turn keeps the original archive guard: executeAction re-checks
+ // and surfaces the alert, so it must not be prompted for cleanup.
+ previewCandidate: async () => {
+ if (thread.session?.status === "running" && thread.session.activeTurnId != null) {
+ return null;
+ }
+ const preview = await previewWorktreeCleanup({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ return preview._tag === "Success" ? preview.value.candidate : null;
+ },
+ confirmRemoval: ({ displayWorktreePath }) =>
+ presentWorktreeCleanupConfirmation({
+ isIos: process.env.EXPO_OS === "ios",
+ displayWorktreePath,
+ presentAlert: (buttons) => {
+ Alert.alert(buttons.title, buttons.message, [
+ { text: "Keep", style: "cancel", onPress: buttons.onKeep },
+ { text: "Remove", style: "destructive", onPress: buttons.onRemove },
+ ]);
+ },
+ presentConfirmDialog: (buttons) => {
+ showConfirmDialog({
+ title: buttons.title,
+ message: buttons.message,
+ cancelText: "Keep",
+ confirmText: "Remove",
+ destructive: true,
+ onConfirm: buttons.onRemove,
+ onCancel: buttons.onKeep,
+ });
+ },
+ }),
+ archive: () => executeAction("archive", thread),
+ isArchiveSuccess: (archived) => archived,
+ cleanup: async () => {
+ const result = await cleanupThreadWorktree({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ if (result._tag === "Failure") {
+ const error = Cause.squash(result.cause);
+ return {
+ kind: "failed",
+ message:
+ error instanceof Error && error.message.trim().length > 0
+ ? error.message
+ : "The worktree could not be removed.",
+ } as const;
+ }
+ return { kind: "done", status: result.value.status } as const;
+ },
+ // Cleanup problems are nonfatal: the archive itself already
+ // succeeded.
+ onCleanupFailed: (displayWorktreePath, message) => {
+ Alert.alert(
+ "Thread archived, but worktree removal failed",
+ `Could not remove ${displayWorktreePath}. ${message}`,
+ );
+ },
+ onCleanupRetained: (displayWorktreePath) => {
+ Alert.alert(
+ "Worktree kept",
+ `${displayWorktreePath} is still used by another active thread.`,
+ );
+ },
+ });
  },
- [executeAction],
+ [cleanupThreadWorktree, executeAction, previewWorktreeCleanup],
  );
  const settleThread = useCallback(
  async (thread: EnvironmentThreadShell) => (await executeAction("settle", thread)) === true,

apps/mobile/src/features/home/worktreeCleanupPrompt.test.ts

@@ -0,0 +1,102 @@
+import { WorktreeLifecycleError } from "@t3tools/contracts";
+import { ThreadId } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { actionFailureMessage, actionFailureTitle } from "./threadActionMessages";
+import {
+ buildWorktreeCleanupPrompt,
+ presentWorktreeCleanupConfirmation,
+} from "./worktreeCleanupPrompt";
+
+describe("presentWorktreeCleanupConfirmation", () => {
+ it("uses the native alert on iOS and never the confirm dialog", async () => {
+ const presentAlert = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onRemove();
+ },
+ );
+ const presentConfirmDialog = vi.fn();
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "confirmed" });
+ expect(presentAlert).toHaveBeenCalledTimes(1);
+ expect(presentConfirmDialog).not.toHaveBeenCalled();
+ });
+
+ it("uses the confirm dialog host elsewhere", async () => {
+ const presentAlert = vi.fn();
+ const presentConfirmDialog = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onKeep();
+ },
+ );
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "declined" });
+ expect(presentAlert).not.toHaveBeenCalled();
+ expect(presentConfirmDialog).toHaveBeenCalledTimes(1);
+ });
+
+ it("resolves declined for Keep and confirmed for Remove", async () => {
+ const keep = presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert: (buttons) => {
+ buttons.onKeep();
+ },
+ presentConfirmDialog: () => {},
+ });
+ await expect(keep).resolves.toEqual({ kind: "declined" });
+
+ const remove = presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert: () => {},
+ presentConfirmDialog: (buttons) => {
+ buttons.onRemove();
+ },
+ });
+ await expect(remove).resolves.toEqual({ kind: "confirmed" });
+ });
+
+ it("names the worktree in the prompt copy", () => {
+ const prompt = buildWorktreeCleanupPrompt("feature-1");
+ expect(prompt.title).toBe("Remove worktree?");
+ expect(prompt.message).toContain("feature-1");
+ expect(prompt.message).toContain("branch is kept");
+ });
+});
+
+describe("thread action failure messages", () => {
+ it("surfaces unarchive restoration errors with the server-provided detail", () => {
+ const restorationError = new WorktreeLifecycleError({
+ operation: "restore",
+ threadId: ThreadId.make("thread-1"),
+ detail:
+ "Failed to recreate the worktree at /wt/feature-1 from branch 'feature-1': branch missing. The thread stays archived.",
+ });
+ expect(actionFailureTitle("unarchive")).toBe("Could not unarchive thread");
+ expect(actionFailureMessage("unarchive", Cause.fail(restorationError))).toContain(
+ "Failed to recreate the worktree",
+ );
+ });
+
+ it("falls back to a generic message when the cause has no message", () => {
+ expect(actionFailureMessage("unarchive", Cause.fail(new Error("")))).toBe(
+ "The thread could not be unarchived.",
+ );
+ });
+});

apps/mobile/src/features/home/worktreeCleanupPrompt.ts

@@ -0,0 +1,49 @@
+import type { WorktreeCleanupConfirmation } from "@t3tools/client-runtime/state/worktreeCleanup";
+
+export interface WorktreeCleanupPromptButtons {
+ readonly title: string;
+ readonly message: string;
+ readonly onKeep: () => void;
+ readonly onRemove: () => void;
+}
+
+export function buildWorktreeCleanupPrompt(displayWorktreePath: string): {
+ readonly title: string;
+ readonly message: string;
+} {
+ return {
+ title: "Remove worktree?",
+ message: `This thread is the last active one linked to the worktree “${displayWorktreePath}”. Remove it when archiving? The branch is kept.`,
+ };
+}
+
+/**
+ * Presents the archive-time cleanup confirmation through the platform's
+ * surface: the native alert on iOS, the in-app confirm dialog elsewhere.
+ * Keep archives without cleanup; Remove archives and cleans up.
+ */
+export function presentWorktreeCleanupConfirmation(input: {
+ readonly isIos: boolean;
+ readonly displayWorktreePath: string;
+ readonly presentAlert: (buttons: WorktreeCleanupPromptButtons) => void;
+ readonly presentConfirmDialog: (buttons: WorktreeCleanupPromptButtons) => void;
+}): Promise<WorktreeCleanupConfirmation<never>> {
+ const { title, message } = buildWorktreeCleanupPrompt(input.displayWorktreePath);
+ return new Promise((resolve) => {
+ const buttons: WorktreeCleanupPromptButtons = {
+ title,
+ message,
+ onKeep: () => {
+ resolve({ kind: "declined" });
+ },
+ onRemove: () => {
+ resolve({ kind: "confirmed" });
+ },
+ };
+ if (input.isIos) {
+ input.presentAlert(buttons);
+ return;
+ }
+ input.presentConfirmDialog(buttons);
+ });
+}

apps/server/src/auth/RpcAuthorization.ts

@@ -71,6 +71,8 @@ export const RPC_REQUIRED_SCOPES = {
  [WS_METHODS.vcsListRefs]: AuthOrchestrationReadScope,
  [WS_METHODS.vcsCreateWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsRemoveWorktree]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsPreviewWorktreeCleanup]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsCleanupThreadWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsCreateRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsSwitchRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsInit]: AuthOrchestrationOperateScope,

apps/server/src/checkpointing/CheckpointDiffQuery.test.ts

@@ -106,6 +106,7 @@ describe("CheckpointDiffQuery.layer", () => {
  });
  }),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -200,6 +201,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -284,6 +286,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -353,6 +356,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -407,6 +411,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts

@@ -201,6 +201,7 @@ describe("OrchestrationEngine", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/mobile/src/features/home/threadActionMessages.ts

@@ -0,0 +1,30 @@
+import * as Cause from "effect/Cause";
+
+export type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
+
+const ACTION_VERBS: Record<ThreadListAction, string> = {
+ archive: "archived",
+ unarchive: "unarchived",
+ delete: "deleted",
+ settle: "settled",
+ unsettle: "un-settled",
+};
+
+export function actionFailureMessage(
+ action: ThreadListAction,
+ cause: Cause.Cause<unknown>,
+): string {
+ const error = Cause.squash(cause);
+ if (error instanceof Error && error.message.trim().length > 0) {
+ return error.message;
+ }
+ return `The thread could not be ${ACTION_VERBS[action]}.`;
+}
+
+export function actionFailureTitle(action: ThreadListAction): string {
+ if (action === "archive") return "Could not archive thread";
+ if (action === "unarchive") return "Could not unarchive thread";
+ if (action === "settle") return "Could not settle thread";
+ if (action === "unsettle") return "Could not un-settle thread";
+ return "Could not delete thread";
+}

apps/mobile/src/features/home/useThreadListActions.ts

@@ -1,5 +1,6 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { canSettle } from "@t3tools/client-runtime/state/thread-settled";
+import { runArchiveWithWorktreeCleanup } from "@t3tools/client-runtime/state/worktreeCleanup";
 import * as Cause from "effect/Cause";
 import * as Haptics from "expo-haptics";
 import { useCallback, useRef } from "react";
@@ -11,7 +12,14 @@ import { refreshArchivedThreadsForEnvironment } from "../archive/useArchivedThre
 import { appAtomRegistry } from "../../state/atom-registry";
 import { environmentServerConfigsAtom } from "../../state/server";
 import { threadEnvironment } from "../../state/threads";
+import { vcsEnvironment } from "../../state/vcs";
 import { useAtomCommand } from "../../state/use-atom-command";
+import {
+ actionFailureMessage,
+ actionFailureTitle,
+ type ThreadListAction,
+} from "./threadActionMessages";
+import { presentWorktreeCleanupConfirmation } from "./worktreeCleanupPrompt";
 
 /** Version skew: never send settle/unsettle to a server that predates them
  (capability defaults false on decode for older servers). */
@@ -22,36 +30,10 @@ function environmentSupportsSettlement(environmentId: EnvironmentThreadShell["en
  );
 }
 
-type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
-
-const ACTION_VERBS: Record<ThreadListAction, string> = {
- archive: "archived",
- unarchive: "unarchived",
- delete: "deleted",
- settle: "settled",
- unsettle: "un-settled",
-};
-
-function actionFailureMessage(action: ThreadListAction, cause: Cause.Cause<unknown>): string {
- const error = Cause.squash(cause);
- if (error instanceof Error && error.message.trim().length > 0) {
- return error.message;
- }
- return `The thread could not be ${ACTION_VERBS[action]}.`;
-}
-
 function selectionHaptic(): void {
  void Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
 }
 
-function actionFailureTitle(action: ThreadListAction): string {
- if (action === "archive") return "Could not archive thread";
- if (action === "unarchive") return "Could not unarchive thread";
- if (action === "settle") return "Could not settle thread";
- if (action === "unsettle") return "Could not un-settle thread";
- return "Could not delete thread";
-}
-
 /** Resolves to true iff the action was dispatched and succeeded. */
 function useThreadActionExecutor(
  onCompleted?: (action: ThreadListAction, thread: EnvironmentThreadShell) => void,
@@ -195,12 +177,88 @@ export function useThreadListActions(): {
  readonly unsettleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
 } {
  const executeAction = useThreadActionExecutor();
+ const previewWorktreeCleanup = useAtomCommand(vcsEnvironment.previewWorktreeCleanup, {
+ reportFailure: false,
+ });
+ const cleanupThreadWorktree = useAtomCommand(vcsEnvironment.cleanupThreadWorktree, {
+ reportFailure: false,
+ });
 
  const archiveThread = useCallback(
  (thread: EnvironmentThreadShell) => {
- void executeAction("archive", thread);
+ void runArchiveWithWorktreeCleanup({
+ // Server-authoritative preview; a failure (old server, transient
+ // error) degrades to a plain archive without a prompt. A thread
+ // mid-turn keeps the original archive guard: executeAction re-checks
+ // and surfaces the alert, so it must not be prompted for cleanup.
+ previewCandidate: async () => {
+ if (thread.session?.status === "running" && thread.session.activeTurnId != null) {
+ return null;
+ }
+ const preview = await previewWorktreeCleanup({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ return preview._tag === "Success" ? preview.value.candidate : null;
+ },
+ confirmRemoval: ({ displayWorktreePath }) =>
+ presentWorktreeCleanupConfirmation({
+ isIos: process.env.EXPO_OS === "ios",
+ displayWorktreePath,
+ presentAlert: (buttons) => {
+ Alert.alert(buttons.title, buttons.message, [
+ { text: "Keep", style: "cancel", onPress: buttons.onKeep },
+ { text: "Remove", style: "destructive", onPress: buttons.onRemove },
+ ]);
+ },
+ presentConfirmDialog: (buttons) => {
+ showConfirmDialog({
+ title: buttons.title,
+ message: buttons.message,
+ cancelText: "Keep",
+ confirmText: "Remove",
+ destructive: true,
+ onConfirm: buttons.onRemove,
+ onCancel: buttons.onKeep,
+ });
+ },
+ }),
+ archive: () => executeAction("archive", thread),
+ isArchiveSuccess: (archived) => archived,
+ cleanup: async () => {
+ const result = await cleanupThreadWorktree({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ if (result._tag === "Failure") {
+ const error = Cause.squash(result.cause);
+ return {
+ kind: "failed",
+ message:
+ error instanceof Error && error.message.trim().length > 0
+ ? error.message
+ : "The worktree could not be removed.",
+ } as const;
+ }
+ return { kind: "done", status: result.value.status } as const;
+ },
+ // Cleanup problems are nonfatal: the archive itself already
+ // succeeded.
+ onCleanupFailed: (displayWorktreePath, message) => {
+ Alert.alert(
+ "Thread archived, but worktree removal failed",
+ `Could not remove ${displayWorktreePath}. ${message}`,
+ );
+ },
+ onCleanupRetained: (displayWorktreePath) => {
+ Alert.alert(
+ "Worktree kept",
+ `${displayWorktreePath} is still used by another active thread.`,
+ );
+ },
+ });
  },
- [executeAction],
+ [cleanupThreadWorktree, executeAction, previewWorktreeCleanup],
  );
  const settleThread = useCallback(
  async (thread: EnvironmentThreadShell) => (await executeAction("settle", thread)) === true,

apps/mobile/src/features/home/worktreeCleanupPrompt.test.ts

@@ -0,0 +1,102 @@
+import { WorktreeLifecycleError } from "@t3tools/contracts";
+import { ThreadId } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { actionFailureMessage, actionFailureTitle } from "./threadActionMessages";
+import {
+ buildWorktreeCleanupPrompt,
+ presentWorktreeCleanupConfirmation,
+} from "./worktreeCleanupPrompt";
+
+describe("presentWorktreeCleanupConfirmation", () => {
+ it("uses the native alert on iOS and never the confirm dialog", async () => {
+ const presentAlert = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onRemove();
+ },
+ );
+ const presentConfirmDialog = vi.fn();
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "confirmed" });
+ expect(presentAlert).toHaveBeenCalledTimes(1);
+ expect(presentConfirmDialog).not.toHaveBeenCalled();
+ });
+
+ it("uses the confirm dialog host elsewhere", async () => {
+ const presentAlert = vi.fn();
+ const presentConfirmDialog = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onKeep();
+ },
+ );
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "declined" });
+ expect(presentAlert).not.toHaveBeenCalled();
+ expect(presentConfirmDialog).toHaveBeenCalledTimes(1);
+ });
+
+ it("resolves declined for Keep and confirmed for Remove", async () => {
+ const keep = presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert: (buttons) => {
+ buttons.onKeep();
+ },
+ presentConfirmDialog: () => {},
+ });
+ await expect(keep).resolves.toEqual({ kind: "declined" });
+
+ const remove = presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert: () => {},
+ presentConfirmDialog: (buttons) => {
+ buttons.onRemove();
+ },
+ });
+ await expect(remove).resolves.toEqual({ kind: "confirmed" });
+ });
+
+ it("names the worktree in the prompt copy", () => {
+ const prompt = buildWorktreeCleanupPrompt("feature-1");
+ expect(prompt.title).toBe("Remove worktree?");
+ expect(prompt.message).toContain("feature-1");
+ expect(prompt.message).toContain("branch is kept");
+ });
+});
+
+describe("thread action failure messages", () => {
+ it("surfaces unarchive restoration errors with the server-provided detail", () => {
+ const restorationError = new WorktreeLifecycleError({
+ operation: "restore",
+ threadId: ThreadId.make("thread-1"),
+ detail:
+ "Failed to recreate the worktree at /wt/feature-1 from branch 'feature-1': branch missing. The thread stays archived.",
+ });
+ expect(actionFailureTitle("unarchive")).toBe("Could not unarchive thread");
+ expect(actionFailureMessage("unarchive", Cause.fail(restorationError))).toContain(
+ "Failed to recreate the worktree",
+ );
+ });
+
+ it("falls back to a generic message when the cause has no message", () => {
+ expect(actionFailureMessage("unarchive", Cause.fail(new Error("")))).toBe(
+ "The thread could not be unarchived.",
+ );
+ });
+});

apps/mobile/src/features/home/worktreeCleanupPrompt.ts

@@ -0,0 +1,49 @@
+import type { WorktreeCleanupConfirmation } from "@t3tools/client-runtime/state/worktreeCleanup";
+
+export interface WorktreeCleanupPromptButtons {
+ readonly title: string;
+ readonly message: string;
+ readonly onKeep: () => void;
+ readonly onRemove: () => void;
+}
+
+export function buildWorktreeCleanupPrompt(displayWorktreePath: string): {
+ readonly title: string;
+ readonly message: string;
+} {
+ return {
+ title: "Remove worktree?",
+ message: `This thread is the last active one linked to the worktree “${displayWorktreePath}”. Remove it when archiving? The branch is kept.`,
+ };
+}
+
+/**
+ * Presents the archive-time cleanup confirmation through the platform's
+ * surface: the native alert on iOS, the in-app confirm dialog elsewhere.
+ * Keep archives without cleanup; Remove archives and cleans up.
+ */
+export function presentWorktreeCleanupConfirmation(input: {
+ readonly isIos: boolean;
+ readonly displayWorktreePath: string;
+ readonly presentAlert: (buttons: WorktreeCleanupPromptButtons) => void;
+ readonly presentConfirmDialog: (buttons: WorktreeCleanupPromptButtons) => void;
+}): Promise<WorktreeCleanupConfirmation<never>> {
+ const { title, message } = buildWorktreeCleanupPrompt(input.displayWorktreePath);
+ return new Promise((resolve) => {
+ const buttons: WorktreeCleanupPromptButtons = {
+ title,
+ message,
+ onKeep: () => {
+ resolve({ kind: "declined" });
+ },
+ onRemove: () => {
+ resolve({ kind: "confirmed" });
+ },
+ };
+ if (input.isIos) {
+ input.presentAlert(buttons);
+ return;
+ }
+ input.presentConfirmDialog(buttons);
+ });
+}

apps/server/src/auth/RpcAuthorization.ts

@@ -71,6 +71,8 @@ export const RPC_REQUIRED_SCOPES = {
  [WS_METHODS.vcsListRefs]: AuthOrchestrationReadScope,
  [WS_METHODS.vcsCreateWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsRemoveWorktree]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsPreviewWorktreeCleanup]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsCleanupThreadWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsCreateRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsSwitchRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsInit]: AuthOrchestrationOperateScope,

apps/server/src/checkpointing/CheckpointDiffQuery.test.ts

@@ -106,6 +106,7 @@ describe("CheckpointDiffQuery.layer", () => {
  });
  }),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -200,6 +201,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -284,6 +286,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -353,6 +356,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -407,6 +411,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts

@@ -201,6 +201,7 @@ describe("OrchestrationEngine", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/mobile/src/features/home/threadActionMessages.ts

@@ -0,0 +1,30 @@
+import * as Cause from "effect/Cause";
+
+export type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
+
+const ACTION_VERBS: Record<ThreadListAction, string> = {
+ archive: "archived",
+ unarchive: "unarchived",
+ delete: "deleted",
+ settle: "settled",
+ unsettle: "un-settled",
+};
+
+export function actionFailureMessage(
+ action: ThreadListAction,
+ cause: Cause.Cause<unknown>,
+): string {
+ const error = Cause.squash(cause);
+ if (error instanceof Error && error.message.trim().length > 0) {
+ return error.message;
+ }
+ return `The thread could not be ${ACTION_VERBS[action]}.`;
+}
+
+export function actionFailureTitle(action: ThreadListAction): string {
+ if (action === "archive") return "Could not archive thread";
+ if (action === "unarchive") return "Could not unarchive thread";
+ if (action === "settle") return "Could not settle thread";
+ if (action === "unsettle") return "Could not un-settle thread";
+ return "Could not delete thread";
+}

apps/mobile/src/features/home/useThreadListActions.ts

@@ -1,5 +1,6 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { canSettle } from "@t3tools/client-runtime/state/thread-settled";
+import { runArchiveWithWorktreeCleanup } from "@t3tools/client-runtime/state/worktreeCleanup";
 import * as Cause from "effect/Cause";
 import * as Haptics from "expo-haptics";
 import { useCallback, useRef } from "react";
@@ -11,7 +12,14 @@ import { refreshArchivedThreadsForEnvironment } from "../archive/useArchivedThre
 import { appAtomRegistry } from "../../state/atom-registry";
 import { environmentServerConfigsAtom } from "../../state/server";
 import { threadEnvironment } from "../../state/threads";
+import { vcsEnvironment } from "../../state/vcs";
 import { useAtomCommand } from "../../state/use-atom-command";
+import {
+ actionFailureMessage,
+ actionFailureTitle,
+ type ThreadListAction,
+} from "./threadActionMessages";
+import { presentWorktreeCleanupConfirmation } from "./worktreeCleanupPrompt";
 
 /** Version skew: never send settle/unsettle to a server that predates them
  (capability defaults false on decode for older servers). */
@@ -22,36 +30,10 @@ function environmentSupportsSettlement(environmentId: EnvironmentThreadShell["en
  );
 }
 
-type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
-
-const ACTION_VERBS: Record<ThreadListAction, string> = {
- archive: "archived",
- unarchive: "unarchived",
- delete: "deleted",
- settle: "settled",
- unsettle: "un-settled",
-};
-
-function actionFailureMessage(action: ThreadListAction, cause: Cause.Cause<unknown>): string {
- const error = Cause.squash(cause);
- if (error instanceof Error && error.message.trim().length > 0) {
- return error.message;
- }
- return `The thread could not be ${ACTION_VERBS[action]}.`;
-}
-
 function selectionHaptic(): void {
  void Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
 }
 
-function actionFailureTitle(action: ThreadListAction): string {
- if (action === "archive") return "Could not archive thread";
- if (action === "unarchive") return "Could not unarchive thread";
- if (action === "settle") return "Could not settle thread";
- if (action === "unsettle") return "Could not un-settle thread";
- return "Could not delete thread";
-}
-
 /** Resolves to true iff the action was dispatched and succeeded. */
 function useThreadActionExecutor(
  onCompleted?: (action: ThreadListAction, thread: EnvironmentThreadShell) => void,
@@ -195,12 +177,88 @@ export function useThreadListActions(): {
  readonly unsettleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
 } {
  const executeAction = useThreadActionExecutor();
+ const previewWorktreeCleanup = useAtomCommand(vcsEnvironment.previewWorktreeCleanup, {
+ reportFailure: false,
+ });
+ const cleanupThreadWorktree = useAtomCommand(vcsEnvironment.cleanupThreadWorktree, {
+ reportFailure: false,
+ });
 
  const archiveThread = useCallback(
  (thread: EnvironmentThreadShell) => {
- void executeAction("archive", thread);
+ void runArchiveWithWorktreeCleanup({
+ // Server-authoritative preview; a failure (old server, transient
+ // error) degrades to a plain archive without a prompt. A thread
+ // mid-turn keeps the original archive guard: executeAction re-checks
+ // and surfaces the alert, so it must not be prompted for cleanup.
+ previewCandidate: async () => {
+ if (thread.session?.status === "running" && thread.session.activeTurnId != null) {
+ return null;
+ }
+ const preview = await previewWorktreeCleanup({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ return preview._tag === "Success" ? preview.value.candidate : null;
+ },
+ confirmRemoval: ({ displayWorktreePath }) =>
+ presentWorktreeCleanupConfirmation({
+ isIos: process.env.EXPO_OS === "ios",
+ displayWorktreePath,
+ presentAlert: (buttons) => {
+ Alert.alert(buttons.title, buttons.message, [
+ { text: "Keep", style: "cancel", onPress: buttons.onKeep },
+ { text: "Remove", style: "destructive", onPress: buttons.onRemove },
+ ]);
+ },
+ presentConfirmDialog: (buttons) => {
+ showConfirmDialog({
+ title: buttons.title,
+ message: buttons.message,
+ cancelText: "Keep",
+ confirmText: "Remove",
+ destructive: true,
+ onConfirm: buttons.onRemove,
+ onCancel: buttons.onKeep,
+ });
+ },
+ }),
+ archive: () => executeAction("archive", thread),
+ isArchiveSuccess: (archived) => archived,
+ cleanup: async () => {
+ const result = await cleanupThreadWorktree({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ if (result._tag === "Failure") {
+ const error = Cause.squash(result.cause);
+ return {
+ kind: "failed",
+ message:
+ error instanceof Error && error.message.trim().length > 0
+ ? error.message
+ : "The worktree could not be removed.",
+ } as const;
+ }
+ return { kind: "done", status: result.value.status } as const;
+ },
+ // Cleanup problems are nonfatal: the archive itself already
+ // succeeded.
+ onCleanupFailed: (displayWorktreePath, message) => {
+ Alert.alert(
+ "Thread archived, but worktree removal failed",
+ `Could not remove ${displayWorktreePath}. ${message}`,
+ );
+ },
+ onCleanupRetained: (displayWorktreePath) => {
+ Alert.alert(
+ "Worktree kept",
+ `${displayWorktreePath} is still used by another active thread.`,
+ );
+ },
+ });
  },
- [executeAction],
+ [cleanupThreadWorktree, executeAction, previewWorktreeCleanup],
  );
  const settleThread = useCallback(
  async (thread: EnvironmentThreadShell) => (await executeAction("settle", thread)) === true,

apps/mobile/src/features/home/worktreeCleanupPrompt.test.ts

@@ -0,0 +1,102 @@
+import { WorktreeLifecycleError } from "@t3tools/contracts";
+import { ThreadId } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { actionFailureMessage, actionFailureTitle } from "./threadActionMessages";
+import {
+ buildWorktreeCleanupPrompt,
+ presentWorktreeCleanupConfirmation,
+} from "./worktreeCleanupPrompt";
+
+describe("presentWorktreeCleanupConfirmation", () => {
+ it("uses the native alert on iOS and never the confirm dialog", async () => {
+ const presentAlert = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onRemove();
+ },
+ );
+ const presentConfirmDialog = vi.fn();
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "confirmed" });
+ expect(presentAlert).toHaveBeenCalledTimes(1);
+ expect(presentConfirmDialog).not.toHaveBeenCalled();
+ });
+
+ it("uses the confirm dialog host elsewhere", async () => {
+ const presentAlert = vi.fn();
+ const presentConfirmDialog = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onKeep();
+ },
+ );
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "declined" });
+ expect(presentAlert).not.toHaveBeenCalled();
+ expect(presentConfirmDialog).toHaveBeenCalledTimes(1);
+ });
+
+ it("resolves declined for Keep and confirmed for Remove", async () => {
+ const keep = presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert: (buttons) => {
+ buttons.onKeep();
+ },
+ presentConfirmDialog: () => {},
+ });
+ await expect(keep).resolves.toEqual({ kind: "declined" });
+
+ const remove = presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert: () => {},
+ presentConfirmDialog: (buttons) => {
+ buttons.onRemove();
+ },
+ });
+ await expect(remove).resolves.toEqual({ kind: "confirmed" });
+ });
+
+ it("names the worktree in the prompt copy", () => {
+ const prompt = buildWorktreeCleanupPrompt("feature-1");
+ expect(prompt.title).toBe("Remove worktree?");
+ expect(prompt.message).toContain("feature-1");
+ expect(prompt.message).toContain("branch is kept");
+ });
+});
+
+describe("thread action failure messages", () => {
+ it("surfaces unarchive restoration errors with the server-provided detail", () => {
+ const restorationError = new WorktreeLifecycleError({
+ operation: "restore",
+ threadId: ThreadId.make("thread-1"),
+ detail:
+ "Failed to recreate the worktree at /wt/feature-1 from branch 'feature-1': branch missing. The thread stays archived.",
+ });
+ expect(actionFailureTitle("unarchive")).toBe("Could not unarchive thread");
+ expect(actionFailureMessage("unarchive", Cause.fail(restorationError))).toContain(
+ "Failed to recreate the worktree",
+ );
+ });
+
+ it("falls back to a generic message when the cause has no message", () => {
+ expect(actionFailureMessage("unarchive", Cause.fail(new Error("")))).toBe(
+ "The thread could not be unarchived.",
+ );
+ });
+});

apps/mobile/src/features/home/worktreeCleanupPrompt.ts

@@ -0,0 +1,49 @@
+import type { WorktreeCleanupConfirmation } from "@t3tools/client-runtime/state/worktreeCleanup";
+
+export interface WorktreeCleanupPromptButtons {
+ readonly title: string;
+ readonly message: string;
+ readonly onKeep: () => void;
+ readonly onRemove: () => void;
+}
+
+export function buildWorktreeCleanupPrompt(displayWorktreePath: string): {
+ readonly title: string;
+ readonly message: string;
+} {
+ return {
+ title: "Remove worktree?",
+ message: `This thread is the last active one linked to the worktree “${displayWorktreePath}”. Remove it when archiving? The branch is kept.`,
+ };
+}
+
+/**
+ * Presents the archive-time cleanup confirmation through the platform's
+ * surface: the native alert on iOS, the in-app confirm dialog elsewhere.
+ * Keep archives without cleanup; Remove archives and cleans up.
+ */
+export function presentWorktreeCleanupConfirmation(input: {
+ readonly isIos: boolean;
+ readonly displayWorktreePath: string;
+ readonly presentAlert: (buttons: WorktreeCleanupPromptButtons) => void;
+ readonly presentConfirmDialog: (buttons: WorktreeCleanupPromptButtons) => void;
+}): Promise<WorktreeCleanupConfirmation<never>> {
+ const { title, message } = buildWorktreeCleanupPrompt(input.displayWorktreePath);
+ return new Promise((resolve) => {
+ const buttons: WorktreeCleanupPromptButtons = {
+ title,
+ message,
+ onKeep: () => {
+ resolve({ kind: "declined" });
+ },
+ onRemove: () => {
+ resolve({ kind: "confirmed" });
+ },
+ };
+ if (input.isIos) {
+ input.presentAlert(buttons);
+ return;
+ }
+ input.presentConfirmDialog(buttons);
+ });
+}

apps/server/src/auth/RpcAuthorization.ts

@@ -71,6 +71,8 @@ export const RPC_REQUIRED_SCOPES = {
  [WS_METHODS.vcsListRefs]: AuthOrchestrationReadScope,
  [WS_METHODS.vcsCreateWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsRemoveWorktree]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsPreviewWorktreeCleanup]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsCleanupThreadWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsCreateRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsSwitchRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsInit]: AuthOrchestrationOperateScope,

apps/server/src/checkpointing/CheckpointDiffQuery.test.ts

@@ -106,6 +106,7 @@ describe("CheckpointDiffQuery.layer", () => {
  });
  }),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -200,6 +201,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -284,6 +286,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -353,6 +356,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -407,6 +411,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts

@@ -201,6 +201,7 @@ describe("OrchestrationEngine", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/mobile/src/features/home/threadActionMessages.ts

@@ -0,0 +1,30 @@
+import * as Cause from "effect/Cause";
+
+export type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
+
+const ACTION_VERBS: Record<ThreadListAction, string> = {
+ archive: "archived",
+ unarchive: "unarchived",
+ delete: "deleted",
+ settle: "settled",
+ unsettle: "un-settled",
+};
+
+export function actionFailureMessage(
+ action: ThreadListAction,
+ cause: Cause.Cause<unknown>,
+): string {
+ const error = Cause.squash(cause);
+ if (error instanceof Error && error.message.trim().length > 0) {
+ return error.message;
+ }
+ return `The thread could not be ${ACTION_VERBS[action]}.`;
+}
+
+export function actionFailureTitle(action: ThreadListAction): string {
+ if (action === "archive") return "Could not archive thread";
+ if (action === "unarchive") return "Could not unarchive thread";
+ if (action === "settle") return "Could not settle thread";
+ if (action === "unsettle") return "Could not un-settle thread";
+ return "Could not delete thread";
+}

apps/mobile/src/features/home/useThreadListActions.ts

@@ -1,5 +1,6 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { canSettle } from "@t3tools/client-runtime/state/thread-settled";
+import { runArchiveWithWorktreeCleanup } from "@t3tools/client-runtime/state/worktreeCleanup";
 import * as Cause from "effect/Cause";
 import * as Haptics from "expo-haptics";
 import { useCallback, useRef } from "react";
@@ -11,7 +12,14 @@ import { refreshArchivedThreadsForEnvironment } from "../archive/useArchivedThre
 import { appAtomRegistry } from "../../state/atom-registry";
 import { environmentServerConfigsAtom } from "../../state/server";
 import { threadEnvironment } from "../../state/threads";
+import { vcsEnvironment } from "../../state/vcs";
 import { useAtomCommand } from "../../state/use-atom-command";
+import {
+ actionFailureMessage,
+ actionFailureTitle,
+ type ThreadListAction,
+} from "./threadActionMessages";
+import { presentWorktreeCleanupConfirmation } from "./worktreeCleanupPrompt";
 
 /** Version skew: never send settle/unsettle to a server that predates them
  (capability defaults false on decode for older servers). */
@@ -22,36 +30,10 @@ function environmentSupportsSettlement(environmentId: EnvironmentThreadShell["en
  );
 }
 
-type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
-
-const ACTION_VERBS: Record<ThreadListAction, string> = {
- archive: "archived",
- unarchive: "unarchived",
- delete: "deleted",
- settle: "settled",
- unsettle: "un-settled",
-};
-
-function actionFailureMessage(action: ThreadListAction, cause: Cause.Cause<unknown>): string {
- const error = Cause.squash(cause);
- if (error instanceof Error && error.message.trim().length > 0) {
- return error.message;
- }
- return `The thread could not be ${ACTION_VERBS[action]}.`;
-}
-
 function selectionHaptic(): void {
  void Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
 }
 
-function actionFailureTitle(action: ThreadListAction): string {
- if (action === "archive") return "Could not archive thread";
- if (action === "unarchive") return "Could not unarchive thread";
- if (action === "settle") return "Could not settle thread";
- if (action === "unsettle") return "Could not un-settle thread";
- return "Could not delete thread";
-}
-
 /** Resolves to true iff the action was dispatched and succeeded. */
 function useThreadActionExecutor(
  onCompleted?: (action: ThreadListAction, thread: EnvironmentThreadShell) => void,
@@ -195,12 +177,88 @@ export function useThreadListActions(): {
  readonly unsettleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
 } {
  const executeAction = useThreadActionExecutor();
+ const previewWorktreeCleanup = useAtomCommand(vcsEnvironment.previewWorktreeCleanup, {
+ reportFailure: false,
+ });
+ const cleanupThreadWorktree = useAtomCommand(vcsEnvironment.cleanupThreadWorktree, {
+ reportFailure: false,
+ });
 
  const archiveThread = useCallback(
  (thread: EnvironmentThreadShell) => {
- void executeAction("archive", thread);
+ void runArchiveWithWorktreeCleanup({
+ // Server-authoritative preview; a failure (old server, transient
+ // error) degrades to a plain archive without a prompt. A thread
+ // mid-turn keeps the original archive guard: executeAction re-checks
+ // and surfaces the alert, so it must not be prompted for cleanup.
+ previewCandidate: async () => {
+ if (thread.session?.status === "running" && thread.session.activeTurnId != null) {
+ return null;
+ }
+ const preview = await previewWorktreeCleanup({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ return preview._tag === "Success" ? preview.value.candidate : null;
+ },
+ confirmRemoval: ({ displayWorktreePath }) =>
+ presentWorktreeCleanupConfirmation({
+ isIos: process.env.EXPO_OS === "ios",
+ displayWorktreePath,
+ presentAlert: (buttons) => {
+ Alert.alert(buttons.title, buttons.message, [
+ { text: "Keep", style: "cancel", onPress: buttons.onKeep },
+ { text: "Remove", style: "destructive", onPress: buttons.onRemove },
+ ]);
+ },
+ presentConfirmDialog: (buttons) => {
+ showConfirmDialog({
+ title: buttons.title,
+ message: buttons.message,
+ cancelText: "Keep",
+ confirmText: "Remove",
+ destructive: true,
+ onConfirm: buttons.onRemove,
+ onCancel: buttons.onKeep,
+ });
+ },
+ }),
+ archive: () => executeAction("archive", thread),
+ isArchiveSuccess: (archived) => archived,
+ cleanup: async () => {
+ const result = await cleanupThreadWorktree({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ if (result._tag === "Failure") {
+ const error = Cause.squash(result.cause);
+ return {
+ kind: "failed",
+ message:
+ error instanceof Error && error.message.trim().length > 0
+ ? error.message
+ : "The worktree could not be removed.",
+ } as const;
+ }
+ return { kind: "done", status: result.value.status } as const;
+ },
+ // Cleanup problems are nonfatal: the archive itself already
+ // succeeded.
+ onCleanupFailed: (displayWorktreePath, message) => {
+ Alert.alert(
+ "Thread archived, but worktree removal failed",
+ `Could not remove ${displayWorktreePath}. ${message}`,
+ );
+ },
+ onCleanupRetained: (displayWorktreePath) => {
+ Alert.alert(
+ "Worktree kept",
+ `${displayWorktreePath} is still used by another active thread.`,
+ );
+ },
+ });
  },
- [executeAction],
+ [cleanupThreadWorktree, executeAction, previewWorktreeCleanup],
  );
  const settleThread = useCallback(
  async (thread: EnvironmentThreadShell) => (await executeAction("settle", thread)) === true,

apps/mobile/src/features/home/worktreeCleanupPrompt.test.ts

@@ -0,0 +1,102 @@
+import { WorktreeLifecycleError } from "@t3tools/contracts";
+import { ThreadId } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { actionFailureMessage, actionFailureTitle } from "./threadActionMessages";
+import {
+ buildWorktreeCleanupPrompt,
+ presentWorktreeCleanupConfirmation,
+} from "./worktreeCleanupPrompt";
+
+describe("presentWorktreeCleanupConfirmation", () => {
+ it("uses the native alert on iOS and never the confirm dialog", async () => {
+ const presentAlert = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onRemove();
+ },
+ );
+ const presentConfirmDialog = vi.fn();
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "confirmed" });
+ expect(presentAlert).toHaveBeenCalledTimes(1);
+ expect(presentConfirmDialog).not.toHaveBeenCalled();
+ });
+
+ it("uses the confirm dialog host elsewhere", async () => {
+ const presentAlert = vi.fn();
+ const presentConfirmDialog = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onKeep();
+ },
+ );
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "declined" });
+ expect(presentAlert).not.toHaveBeenCalled();
+ expect(presentConfirmDialog).toHaveBeenCalledTimes(1);
+ });
+
+ it("resolves declined for Keep and confirmed for Remove", async () => {
+ const keep = presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert: (buttons) => {
+ buttons.onKeep();
+ },
+ presentConfirmDialog: () => {},
+ });
+ await expect(keep).resolves.toEqual({ kind: "declined" });
+
+ const remove = presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert: () => {},
+ presentConfirmDialog: (buttons) => {
+ buttons.onRemove();
+ },
+ });
+ await expect(remove).resolves.toEqual({ kind: "confirmed" });
+ });
+
+ it("names the worktree in the prompt copy", () => {
+ const prompt = buildWorktreeCleanupPrompt("feature-1");
+ expect(prompt.title).toBe("Remove worktree?");
+ expect(prompt.message).toContain("feature-1");
+ expect(prompt.message).toContain("branch is kept");
+ });
+});
+
+describe("thread action failure messages", () => {
+ it("surfaces unarchive restoration errors with the server-provided detail", () => {
+ const restorationError = new WorktreeLifecycleError({
+ operation: "restore",
+ threadId: ThreadId.make("thread-1"),
+ detail:
+ "Failed to recreate the worktree at /wt/feature-1 from branch 'feature-1': branch missing. The thread stays archived.",
+ });
+ expect(actionFailureTitle("unarchive")).toBe("Could not unarchive thread");
+ expect(actionFailureMessage("unarchive", Cause.fail(restorationError))).toContain(
+ "Failed to recreate the worktree",
+ );
+ });
+
+ it("falls back to a generic message when the cause has no message", () => {
+ expect(actionFailureMessage("unarchive", Cause.fail(new Error("")))).toBe(
+ "The thread could not be unarchived.",
+ );
+ });
+});

apps/mobile/src/features/home/worktreeCleanupPrompt.ts

@@ -0,0 +1,49 @@
+import type { WorktreeCleanupConfirmation } from "@t3tools/client-runtime/state/worktreeCleanup";
+
+export interface WorktreeCleanupPromptButtons {
+ readonly title: string;
+ readonly message: string;
+ readonly onKeep: () => void;
+ readonly onRemove: () => void;
+}
+
+export function buildWorktreeCleanupPrompt(displayWorktreePath: string): {
+ readonly title: string;
+ readonly message: string;
+} {
+ return {
+ title: "Remove worktree?",
+ message: `This thread is the last active one linked to the worktree “${displayWorktreePath}”. Remove it when archiving? The branch is kept.`,
+ };
+}
+
+/**
+ * Presents the archive-time cleanup confirmation through the platform's
+ * surface: the native alert on iOS, the in-app confirm dialog elsewhere.
+ * Keep archives without cleanup; Remove archives and cleans up.
+ */
+export function presentWorktreeCleanupConfirmation(input: {
+ readonly isIos: boolean;
+ readonly displayWorktreePath: string;
+ readonly presentAlert: (buttons: WorktreeCleanupPromptButtons) => void;
+ readonly presentConfirmDialog: (buttons: WorktreeCleanupPromptButtons) => void;
+}): Promise<WorktreeCleanupConfirmation<never>> {
+ const { title, message } = buildWorktreeCleanupPrompt(input.displayWorktreePath);
+ return new Promise((resolve) => {
+ const buttons: WorktreeCleanupPromptButtons = {
+ title,
+ message,
+ onKeep: () => {
+ resolve({ kind: "declined" });
+ },
+ onRemove: () => {
+ resolve({ kind: "confirmed" });
+ },
+ };
+ if (input.isIos) {
+ input.presentAlert(buttons);
+ return;
+ }
+ input.presentConfirmDialog(buttons);
+ });
+}

apps/server/src/auth/RpcAuthorization.ts

@@ -71,6 +71,8 @@ export const RPC_REQUIRED_SCOPES = {
  [WS_METHODS.vcsListRefs]: AuthOrchestrationReadScope,
  [WS_METHODS.vcsCreateWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsRemoveWorktree]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsPreviewWorktreeCleanup]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsCleanupThreadWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsCreateRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsSwitchRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsInit]: AuthOrchestrationOperateScope,

apps/server/src/checkpointing/CheckpointDiffQuery.test.ts

@@ -106,6 +106,7 @@ describe("CheckpointDiffQuery.layer", () => {
  });
  }),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -200,6 +201,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -284,6 +286,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -353,6 +356,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -407,6 +411,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts

@@ -201,6 +201,7 @@ describe("OrchestrationEngine", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/mobile/src/features/home/threadActionMessages.ts

@@ -0,0 +1,30 @@
+import * as Cause from "effect/Cause";
+
+export type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
+
+const ACTION_VERBS: Record<ThreadListAction, string> = {
+ archive: "archived",
+ unarchive: "unarchived",
+ delete: "deleted",
+ settle: "settled",
+ unsettle: "un-settled",
+};
+
+export function actionFailureMessage(
+ action: ThreadListAction,
+ cause: Cause.Cause<unknown>,
+): string {
+ const error = Cause.squash(cause);
+ if (error instanceof Error && error.message.trim().length > 0) {
+ return error.message;
+ }
+ return `The thread could not be ${ACTION_VERBS[action]}.`;
+}
+
+export function actionFailureTitle(action: ThreadListAction): string {
+ if (action === "archive") return "Could not archive thread";
+ if (action === "unarchive") return "Could not unarchive thread";
+ if (action === "settle") return "Could not settle thread";
+ if (action === "unsettle") return "Could not un-settle thread";
+ return "Could not delete thread";
+}

apps/mobile/src/features/home/useThreadListActions.ts

@@ -1,5 +1,6 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { canSettle } from "@t3tools/client-runtime/state/thread-settled";
+import { runArchiveWithWorktreeCleanup } from "@t3tools/client-runtime/state/worktreeCleanup";
 import * as Cause from "effect/Cause";
 import * as Haptics from "expo-haptics";
 import { useCallback, useRef } from "react";
@@ -11,7 +12,14 @@ import { refreshArchivedThreadsForEnvironment } from "../archive/useArchivedThre
 import { appAtomRegistry } from "../../state/atom-registry";
 import { environmentServerConfigsAtom } from "../../state/server";
 import { threadEnvironment } from "../../state/threads";
+import { vcsEnvironment } from "../../state/vcs";
 import { useAtomCommand } from "../../state/use-atom-command";
+import {
+ actionFailureMessage,
+ actionFailureTitle,
+ type ThreadListAction,
+} from "./threadActionMessages";
+import { presentWorktreeCleanupConfirmation } from "./worktreeCleanupPrompt";
 
 /** Version skew: never send settle/unsettle to a server that predates them
  (capability defaults false on decode for older servers). */
@@ -22,36 +30,10 @@ function environmentSupportsSettlement(environmentId: EnvironmentThreadShell["en
  );
 }
 
-type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
-
-const ACTION_VERBS: Record<ThreadListAction, string> = {
- archive: "archived",
- unarchive: "unarchived",
- delete: "deleted",
- settle: "settled",
- unsettle: "un-settled",
-};
-
-function actionFailureMessage(action: ThreadListAction, cause: Cause.Cause<unknown>): string {
- const error = Cause.squash(cause);
- if (error instanceof Error && error.message.trim().length > 0) {
- return error.message;
- }
- return `The thread could not be ${ACTION_VERBS[action]}.`;
-}
-
 function selectionHaptic(): void {
  void Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
 }
 
-function actionFailureTitle(action: ThreadListAction): string {
- if (action === "archive") return "Could not archive thread";
- if (action === "unarchive") return "Could not unarchive thread";
- if (action === "settle") return "Could not settle thread";
- if (action === "unsettle") return "Could not un-settle thread";
- return "Could not delete thread";
-}
-
 /** Resolves to true iff the action was dispatched and succeeded. */
 function useThreadActionExecutor(
  onCompleted?: (action: ThreadListAction, thread: EnvironmentThreadShell) => void,
@@ -195,12 +177,88 @@ export function useThreadListActions(): {
  readonly unsettleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
 } {
  const executeAction = useThreadActionExecutor();
+ const previewWorktreeCleanup = useAtomCommand(vcsEnvironment.previewWorktreeCleanup, {
+ reportFailure: false,
+ });
+ const cleanupThreadWorktree = useAtomCommand(vcsEnvironment.cleanupThreadWorktree, {
+ reportFailure: false,
+ });
 
  const archiveThread = useCallback(
  (thread: EnvironmentThreadShell) => {
- void executeAction("archive", thread);
+ void runArchiveWithWorktreeCleanup({
+ // Server-authoritative preview; a failure (old server, transient
+ // error) degrades to a plain archive without a prompt. A thread
+ // mid-turn keeps the original archive guard: executeAction re-checks
+ // and surfaces the alert, so it must not be prompted for cleanup.
+ previewCandidate: async () => {
+ if (thread.session?.status === "running" && thread.session.activeTurnId != null) {
+ return null;
+ }
+ const preview = await previewWorktreeCleanup({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ return preview._tag === "Success" ? preview.value.candidate : null;
+ },
+ confirmRemoval: ({ displayWorktreePath }) =>
+ presentWorktreeCleanupConfirmation({
+ isIos: process.env.EXPO_OS === "ios",
+ displayWorktreePath,
+ presentAlert: (buttons) => {
+ Alert.alert(buttons.title, buttons.message, [
+ { text: "Keep", style: "cancel", onPress: buttons.onKeep },
+ { text: "Remove", style: "destructive", onPress: buttons.onRemove },
+ ]);
+ },
+ presentConfirmDialog: (buttons) => {
+ showConfirmDialog({
+ title: buttons.title,
+ message: buttons.message,
+ cancelText: "Keep",
+ confirmText: "Remove",
+ destructive: true,
+ onConfirm: buttons.onRemove,
+ onCancel: buttons.onKeep,
+ });
+ },
+ }),
+ archive: () => executeAction("archive", thread),
+ isArchiveSuccess: (archived) => archived,
+ cleanup: async () => {
+ const result = await cleanupThreadWorktree({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ if (result._tag === "Failure") {
+ const error = Cause.squash(result.cause);
+ return {
+ kind: "failed",
+ message:
+ error instanceof Error && error.message.trim().length > 0
+ ? error.message
+ : "The worktree could not be removed.",
+ } as const;
+ }
+ return { kind: "done", status: result.value.status } as const;
+ },
+ // Cleanup problems are nonfatal: the archive itself already
+ // succeeded.
+ onCleanupFailed: (displayWorktreePath, message) => {
+ Alert.alert(
+ "Thread archived, but worktree removal failed",
+ `Could not remove ${displayWorktreePath}. ${message}`,
+ );
+ },
+ onCleanupRetained: (displayWorktreePath) => {
+ Alert.alert(
+ "Worktree kept",
+ `${displayWorktreePath} is still used by another active thread.`,
+ );
+ },
+ });
  },
- [executeAction],
+ [cleanupThreadWorktree, executeAction, previewWorktreeCleanup],
  );
  const settleThread = useCallback(
  async (thread: EnvironmentThreadShell) => (await executeAction("settle", thread)) === true,

apps/mobile/src/features/home/worktreeCleanupPrompt.test.ts

@@ -0,0 +1,102 @@
+import { WorktreeLifecycleError } from "@t3tools/contracts";
+import { ThreadId } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { actionFailureMessage, actionFailureTitle } from "./threadActionMessages";
+import {
+ buildWorktreeCleanupPrompt,
+ presentWorktreeCleanupConfirmation,
+} from "./worktreeCleanupPrompt";
+
+describe("presentWorktreeCleanupConfirmation", () => {
+ it("uses the native alert on iOS and never the confirm dialog", async () => {
+ const presentAlert = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onRemove();
+ },
+ );
+ const presentConfirmDialog = vi.fn();
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "confirmed" });
+ expect(presentAlert).toHaveBeenCalledTimes(1);
+ expect(presentConfirmDialog).not.toHaveBeenCalled();
+ });
+
+ it("uses the confirm dialog host elsewhere", async () => {
+ const presentAlert = vi.fn();
+ const presentConfirmDialog = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onKeep();
+ },
+ );
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "declined" });
+ expect(presentAlert).not.toHaveBeenCalled();
+ expect(presentConfirmDialog).toHaveBeenCalledTimes(1);
+ });
+
+ it("resolves declined for Keep and confirmed for Remove", async () => {
+ const keep = presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert: (buttons) => {
+ buttons.onKeep();
+ },
+ presentConfirmDialog: () => {},
+ });
+ await expect(keep).resolves.toEqual({ kind: "declined" });
+
+ const remove = presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert: () => {},
+ presentConfirmDialog: (buttons) => {
+ buttons.onRemove();
+ },
+ });
+ await expect(remove).resolves.toEqual({ kind: "confirmed" });
+ });
+
+ it("names the worktree in the prompt copy", () => {
+ const prompt = buildWorktreeCleanupPrompt("feature-1");
+ expect(prompt.title).toBe("Remove worktree?");
+ expect(prompt.message).toContain("feature-1");
+ expect(prompt.message).toContain("branch is kept");
+ });
+});
+
+describe("thread action failure messages", () => {
+ it("surfaces unarchive restoration errors with the server-provided detail", () => {
+ const restorationError = new WorktreeLifecycleError({
+ operation: "restore",
+ threadId: ThreadId.make("thread-1"),
+ detail:
+ "Failed to recreate the worktree at /wt/feature-1 from branch 'feature-1': branch missing. The thread stays archived.",
+ });
+ expect(actionFailureTitle("unarchive")).toBe("Could not unarchive thread");
+ expect(actionFailureMessage("unarchive", Cause.fail(restorationError))).toContain(
+ "Failed to recreate the worktree",
+ );
+ });
+
+ it("falls back to a generic message when the cause has no message", () => {
+ expect(actionFailureMessage("unarchive", Cause.fail(new Error("")))).toBe(
+ "The thread could not be unarchived.",
+ );
+ });
+});

apps/mobile/src/features/home/worktreeCleanupPrompt.ts

@@ -0,0 +1,49 @@
+import type { WorktreeCleanupConfirmation } from "@t3tools/client-runtime/state/worktreeCleanup";
+
+export interface WorktreeCleanupPromptButtons {
+ readonly title: string;
+ readonly message: string;
+ readonly onKeep: () => void;
+ readonly onRemove: () => void;
+}
+
+export function buildWorktreeCleanupPrompt(displayWorktreePath: string): {
+ readonly title: string;
+ readonly message: string;
+} {
+ return {
+ title: "Remove worktree?",
+ message: `This thread is the last active one linked to the worktree “${displayWorktreePath}”. Remove it when archiving? The branch is kept.`,
+ };
+}
+
+/**
+ * Presents the archive-time cleanup confirmation through the platform's
+ * surface: the native alert on iOS, the in-app confirm dialog elsewhere.
+ * Keep archives without cleanup; Remove archives and cleans up.
+ */
+export function presentWorktreeCleanupConfirmation(input: {
+ readonly isIos: boolean;
+ readonly displayWorktreePath: string;
+ readonly presentAlert: (buttons: WorktreeCleanupPromptButtons) => void;
+ readonly presentConfirmDialog: (buttons: WorktreeCleanupPromptButtons) => void;
+}): Promise<WorktreeCleanupConfirmation<never>> {
+ const { title, message } = buildWorktreeCleanupPrompt(input.displayWorktreePath);
+ return new Promise((resolve) => {
+ const buttons: WorktreeCleanupPromptButtons = {
+ title,
+ message,
+ onKeep: () => {
+ resolve({ kind: "declined" });
+ },
+ onRemove: () => {
+ resolve({ kind: "confirmed" });
+ },
+ };
+ if (input.isIos) {
+ input.presentAlert(buttons);
+ return;
+ }
+ input.presentConfirmDialog(buttons);
+ });
+}

apps/server/src/auth/RpcAuthorization.ts

@@ -71,6 +71,8 @@ export const RPC_REQUIRED_SCOPES = {
  [WS_METHODS.vcsListRefs]: AuthOrchestrationReadScope,
  [WS_METHODS.vcsCreateWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsRemoveWorktree]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsPreviewWorktreeCleanup]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsCleanupThreadWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsCreateRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsSwitchRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsInit]: AuthOrchestrationOperateScope,

apps/server/src/checkpointing/CheckpointDiffQuery.test.ts

@@ -106,6 +106,7 @@ describe("CheckpointDiffQuery.layer", () => {
  });
  }),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -200,6 +201,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -284,6 +286,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -353,6 +356,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -407,6 +411,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts

@@ -201,6 +201,7 @@ describe("OrchestrationEngine", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/mobile/src/features/home/threadActionMessages.ts

@@ -0,0 +1,30 @@
+import * as Cause from "effect/Cause";
+
+export type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
+
+const ACTION_VERBS: Record<ThreadListAction, string> = {
+ archive: "archived",
+ unarchive: "unarchived",
+ delete: "deleted",
+ settle: "settled",
+ unsettle: "un-settled",
+};
+
+export function actionFailureMessage(
+ action: ThreadListAction,
+ cause: Cause.Cause<unknown>,
+): string {
+ const error = Cause.squash(cause);
+ if (error instanceof Error && error.message.trim().length > 0) {
+ return error.message;
+ }
+ return `The thread could not be ${ACTION_VERBS[action]}.`;
+}
+
+export function actionFailureTitle(action: ThreadListAction): string {
+ if (action === "archive") return "Could not archive thread";
+ if (action === "unarchive") return "Could not unarchive thread";
+ if (action === "settle") return "Could not settle thread";
+ if (action === "unsettle") return "Could not un-settle thread";
+ return "Could not delete thread";
+}

apps/mobile/src/features/home/useThreadListActions.ts

@@ -1,5 +1,6 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { canSettle } from "@t3tools/client-runtime/state/thread-settled";
+import { runArchiveWithWorktreeCleanup } from "@t3tools/client-runtime/state/worktreeCleanup";
 import * as Cause from "effect/Cause";
 import * as Haptics from "expo-haptics";
 import { useCallback, useRef } from "react";
@@ -11,7 +12,14 @@ import { refreshArchivedThreadsForEnvironment } from "../archive/useArchivedThre
 import { appAtomRegistry } from "../../state/atom-registry";
 import { environmentServerConfigsAtom } from "../../state/server";
 import { threadEnvironment } from "../../state/threads";
+import { vcsEnvironment } from "../../state/vcs";
 import { useAtomCommand } from "../../state/use-atom-command";
+import {
+ actionFailureMessage,
+ actionFailureTitle,
+ type ThreadListAction,
+} from "./threadActionMessages";
+import { presentWorktreeCleanupConfirmation } from "./worktreeCleanupPrompt";
 
 /** Version skew: never send settle/unsettle to a server that predates them
  (capability defaults false on decode for older servers). */
@@ -22,36 +30,10 @@ function environmentSupportsSettlement(environmentId: EnvironmentThreadShell["en
  );
 }
 
-type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
-
-const ACTION_VERBS: Record<ThreadListAction, string> = {
- archive: "archived",
- unarchive: "unarchived",
- delete: "deleted",
- settle: "settled",
- unsettle: "un-settled",
-};
-
-function actionFailureMessage(action: ThreadListAction, cause: Cause.Cause<unknown>): string {
- const error = Cause.squash(cause);
- if (error instanceof Error && error.message.trim().length > 0) {
- return error.message;
- }
- return `The thread could not be ${ACTION_VERBS[action]}.`;
-}
-
 function selectionHaptic(): void {
  void Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
 }
 
-function actionFailureTitle(action: ThreadListAction): string {
- if (action === "archive") return "Could not archive thread";
- if (action === "unarchive") return "Could not unarchive thread";
- if (action === "settle") return "Could not settle thread";
- if (action === "unsettle") return "Could not un-settle thread";
- return "Could not delete thread";
-}
-
 /** Resolves to true iff the action was dispatched and succeeded. */
 function useThreadActionExecutor(
  onCompleted?: (action: ThreadListAction, thread: EnvironmentThreadShell) => void,
@@ -195,12 +177,88 @@ export function useThreadListActions(): {
  readonly unsettleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
 } {
  const executeAction = useThreadActionExecutor();
+ const previewWorktreeCleanup = useAtomCommand(vcsEnvironment.previewWorktreeCleanup, {
+ reportFailure: false,
+ });
+ const cleanupThreadWorktree = useAtomCommand(vcsEnvironment.cleanupThreadWorktree, {
+ reportFailure: false,
+ });
 
  const archiveThread = useCallback(
  (thread: EnvironmentThreadShell) => {
- void executeAction("archive", thread);
+ void runArchiveWithWorktreeCleanup({
+ // Server-authoritative preview; a failure (old server, transient
+ // error) degrades to a plain archive without a prompt. A thread
+ // mid-turn keeps the original archive guard: executeAction re-checks
+ // and surfaces the alert, so it must not be prompted for cleanup.
+ previewCandidate: async () => {
+ if (thread.session?.status === "running" && thread.session.activeTurnId != null) {
+ return null;
+ }
+ const preview = await previewWorktreeCleanup({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ return preview._tag === "Success" ? preview.value.candidate : null;
+ },
+ confirmRemoval: ({ displayWorktreePath }) =>
+ presentWorktreeCleanupConfirmation({
+ isIos: process.env.EXPO_OS === "ios",
+ displayWorktreePath,
+ presentAlert: (buttons) => {
+ Alert.alert(buttons.title, buttons.message, [
+ { text: "Keep", style: "cancel", onPress: buttons.onKeep },
+ { text: "Remove", style: "destructive", onPress: buttons.onRemove },
+ ]);
+ },
+ presentConfirmDialog: (buttons) => {
+ showConfirmDialog({
+ title: buttons.title,
+ message: buttons.message,
+ cancelText: "Keep",
+ confirmText: "Remove",
+ destructive: true,
+ onConfirm: buttons.onRemove,
+ onCancel: buttons.onKeep,
+ });
+ },
+ }),
+ archive: () => executeAction("archive", thread),
+ isArchiveSuccess: (archived) => archived,
+ cleanup: async () => {
+ const result = await cleanupThreadWorktree({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ if (result._tag === "Failure") {
+ const error = Cause.squash(result.cause);
+ return {
+ kind: "failed",
+ message:
+ error instanceof Error && error.message.trim().length > 0
+ ? error.message
+ : "The worktree could not be removed.",
+ } as const;
+ }
+ return { kind: "done", status: result.value.status } as const;
+ },
+ // Cleanup problems are nonfatal: the archive itself already
+ // succeeded.
+ onCleanupFailed: (displayWorktreePath, message) => {
+ Alert.alert(
+ "Thread archived, but worktree removal failed",
+ `Could not remove ${displayWorktreePath}. ${message}`,
+ );
+ },
+ onCleanupRetained: (displayWorktreePath) => {
+ Alert.alert(
+ "Worktree kept",
+ `${displayWorktreePath} is still used by another active thread.`,
+ );
+ },
+ });
  },
- [executeAction],
+ [cleanupThreadWorktree, executeAction, previewWorktreeCleanup],
  );
  const settleThread = useCallback(
  async (thread: EnvironmentThreadShell) => (await executeAction("settle", thread)) === true,

apps/mobile/src/features/home/worktreeCleanupPrompt.test.ts

@@ -0,0 +1,102 @@
+import { WorktreeLifecycleError } from "@t3tools/contracts";
+import { ThreadId } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { actionFailureMessage, actionFailureTitle } from "./threadActionMessages";
+import {
+ buildWorktreeCleanupPrompt,
+ presentWorktreeCleanupConfirmation,
+} from "./worktreeCleanupPrompt";
+
+describe("presentWorktreeCleanupConfirmation", () => {
+ it("uses the native alert on iOS and never the confirm dialog", async () => {
+ const presentAlert = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onRemove();
+ },
+ );
+ const presentConfirmDialog = vi.fn();
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "confirmed" });
+ expect(presentAlert).toHaveBeenCalledTimes(1);
+ expect(presentConfirmDialog).not.toHaveBeenCalled();
+ });
+
+ it("uses the confirm dialog host elsewhere", async () => {
+ const presentAlert = vi.fn();
+ const presentConfirmDialog = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onKeep();
+ },
+ );
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "declined" });
+ expect(presentAlert).not.toHaveBeenCalled();
+ expect(presentConfirmDialog).toHaveBeenCalledTimes(1);
+ });
+
+ it("resolves declined for Keep and confirmed for Remove", async () => {
+ const keep = presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert: (buttons) => {
+ buttons.onKeep();
+ },
+ presentConfirmDialog: () => {},
+ });
+ await expect(keep).resolves.toEqual({ kind: "declined" });
+
+ const remove = presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert: () => {},
+ presentConfirmDialog: (buttons) => {
+ buttons.onRemove();
+ },
+ });
+ await expect(remove).resolves.toEqual({ kind: "confirmed" });
+ });
+
+ it("names the worktree in the prompt copy", () => {
+ const prompt = buildWorktreeCleanupPrompt("feature-1");
+ expect(prompt.title).toBe("Remove worktree?");
+ expect(prompt.message).toContain("feature-1");
+ expect(prompt.message).toContain("branch is kept");
+ });
+});
+
+describe("thread action failure messages", () => {
+ it("surfaces unarchive restoration errors with the server-provided detail", () => {
+ const restorationError = new WorktreeLifecycleError({
+ operation: "restore",
+ threadId: ThreadId.make("thread-1"),
+ detail:
+ "Failed to recreate the worktree at /wt/feature-1 from branch 'feature-1': branch missing. The thread stays archived.",
+ });
+ expect(actionFailureTitle("unarchive")).toBe("Could not unarchive thread");
+ expect(actionFailureMessage("unarchive", Cause.fail(restorationError))).toContain(
+ "Failed to recreate the worktree",
+ );
+ });
+
+ it("falls back to a generic message when the cause has no message", () => {
+ expect(actionFailureMessage("unarchive", Cause.fail(new Error("")))).toBe(
+ "The thread could not be unarchived.",
+ );
+ });
+});

apps/mobile/src/features/home/worktreeCleanupPrompt.ts

@@ -0,0 +1,49 @@
+import type { WorktreeCleanupConfirmation } from "@t3tools/client-runtime/state/worktreeCleanup";
+
+export interface WorktreeCleanupPromptButtons {
+ readonly title: string;
+ readonly message: string;
+ readonly onKeep: () => void;
+ readonly onRemove: () => void;
+}
+
+export function buildWorktreeCleanupPrompt(displayWorktreePath: string): {
+ readonly title: string;
+ readonly message: string;
+} {
+ return {
+ title: "Remove worktree?",
+ message: `This thread is the last active one linked to the worktree “${displayWorktreePath}”. Remove it when archiving? The branch is kept.`,
+ };
+}
+
+/**
+ * Presents the archive-time cleanup confirmation through the platform's
+ * surface: the native alert on iOS, the in-app confirm dialog elsewhere.
+ * Keep archives without cleanup; Remove archives and cleans up.
+ */
+export function presentWorktreeCleanupConfirmation(input: {
+ readonly isIos: boolean;
+ readonly displayWorktreePath: string;
+ readonly presentAlert: (buttons: WorktreeCleanupPromptButtons) => void;
+ readonly presentConfirmDialog: (buttons: WorktreeCleanupPromptButtons) => void;
+}): Promise<WorktreeCleanupConfirmation<never>> {
+ const { title, message } = buildWorktreeCleanupPrompt(input.displayWorktreePath);
+ return new Promise((resolve) => {
+ const buttons: WorktreeCleanupPromptButtons = {
+ title,
+ message,
+ onKeep: () => {
+ resolve({ kind: "declined" });
+ },
+ onRemove: () => {
+ resolve({ kind: "confirmed" });
+ },
+ };
+ if (input.isIos) {
+ input.presentAlert(buttons);
+ return;
+ }
+ input.presentConfirmDialog(buttons);
+ });
+}

apps/server/src/auth/RpcAuthorization.ts

@@ -71,6 +71,8 @@ export const RPC_REQUIRED_SCOPES = {
  [WS_METHODS.vcsListRefs]: AuthOrchestrationReadScope,
  [WS_METHODS.vcsCreateWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsRemoveWorktree]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsPreviewWorktreeCleanup]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsCleanupThreadWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsCreateRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsSwitchRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsInit]: AuthOrchestrationOperateScope,

apps/server/src/checkpointing/CheckpointDiffQuery.test.ts

@@ -106,6 +106,7 @@ describe("CheckpointDiffQuery.layer", () => {
  });
  }),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -200,6 +201,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -284,6 +286,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -353,6 +356,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -407,6 +411,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts

@@ -201,6 +201,7 @@ describe("OrchestrationEngine", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/mobile/src/features/home/threadActionMessages.ts

@@ -0,0 +1,30 @@
+import * as Cause from "effect/Cause";
+
+export type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
+
+const ACTION_VERBS: Record<ThreadListAction, string> = {
+ archive: "archived",
+ unarchive: "unarchived",
+ delete: "deleted",
+ settle: "settled",
+ unsettle: "un-settled",
+};
+
+export function actionFailureMessage(
+ action: ThreadListAction,
+ cause: Cause.Cause<unknown>,
+): string {
+ const error = Cause.squash(cause);
+ if (error instanceof Error && error.message.trim().length > 0) {
+ return error.message;
+ }
+ return `The thread could not be ${ACTION_VERBS[action]}.`;
+}
+
+export function actionFailureTitle(action: ThreadListAction): string {
+ if (action === "archive") return "Could not archive thread";
+ if (action === "unarchive") return "Could not unarchive thread";
+ if (action === "settle") return "Could not settle thread";
+ if (action === "unsettle") return "Could not un-settle thread";
+ return "Could not delete thread";
+}

apps/mobile/src/features/home/useThreadListActions.ts

@@ -1,5 +1,6 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { canSettle } from "@t3tools/client-runtime/state/thread-settled";
+import { runArchiveWithWorktreeCleanup } from "@t3tools/client-runtime/state/worktreeCleanup";
 import * as Cause from "effect/Cause";
 import * as Haptics from "expo-haptics";
 import { useCallback, useRef } from "react";
@@ -11,7 +12,14 @@ import { refreshArchivedThreadsForEnvironment } from "../archive/useArchivedThre
 import { appAtomRegistry } from "../../state/atom-registry";
 import { environmentServerConfigsAtom } from "../../state/server";
 import { threadEnvironment } from "../../state/threads";
+import { vcsEnvironment } from "../../state/vcs";
 import { useAtomCommand } from "../../state/use-atom-command";
+import {
+ actionFailureMessage,
+ actionFailureTitle,
+ type ThreadListAction,
+} from "./threadActionMessages";
+import { presentWorktreeCleanupConfirmation } from "./worktreeCleanupPrompt";
 
 /** Version skew: never send settle/unsettle to a server that predates them
  (capability defaults false on decode for older servers). */
@@ -22,36 +30,10 @@ function environmentSupportsSettlement(environmentId: EnvironmentThreadShell["en
  );
 }
 
-type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
-
-const ACTION_VERBS: Record<ThreadListAction, string> = {
- archive: "archived",
- unarchive: "unarchived",
- delete: "deleted",
- settle: "settled",
- unsettle: "un-settled",
-};
-
-function actionFailureMessage(action: ThreadListAction, cause: Cause.Cause<unknown>): string {
- const error = Cause.squash(cause);
- if (error instanceof Error && error.message.trim().length > 0) {
- return error.message;
- }
- return `The thread could not be ${ACTION_VERBS[action]}.`;
-}
-
 function selectionHaptic(): void {
  void Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
 }
 
-function actionFailureTitle(action: ThreadListAction): string {
- if (action === "archive") return "Could not archive thread";
- if (action === "unarchive") return "Could not unarchive thread";
- if (action === "settle") return "Could not settle thread";
- if (action === "unsettle") return "Could not un-settle thread";
- return "Could not delete thread";
-}
-
 /** Resolves to true iff the action was dispatched and succeeded. */
 function useThreadActionExecutor(
  onCompleted?: (action: ThreadListAction, thread: EnvironmentThreadShell) => void,
@@ -195,12 +177,88 @@ export function useThreadListActions(): {
  readonly unsettleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
 } {
  const executeAction = useThreadActionExecutor();
+ const previewWorktreeCleanup = useAtomCommand(vcsEnvironment.previewWorktreeCleanup, {
+ reportFailure: false,
+ });
+ const cleanupThreadWorktree = useAtomCommand(vcsEnvironment.cleanupThreadWorktree, {
+ reportFailure: false,
+ });
 
  const archiveThread = useCallback(
  (thread: EnvironmentThreadShell) => {
- void executeAction("archive", thread);
+ void runArchiveWithWorktreeCleanup({
+ // Server-authoritative preview; a failure (old server, transient
+ // error) degrades to a plain archive without a prompt. A thread
+ // mid-turn keeps the original archive guard: executeAction re-checks
+ // and surfaces the alert, so it must not be prompted for cleanup.
+ previewCandidate: async () => {
+ if (thread.session?.status === "running" && thread.session.activeTurnId != null) {
+ return null;
+ }
+ const preview = await previewWorktreeCleanup({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ return preview._tag === "Success" ? preview.value.candidate : null;
+ },
+ confirmRemoval: ({ displayWorktreePath }) =>
+ presentWorktreeCleanupConfirmation({
+ isIos: process.env.EXPO_OS === "ios",
+ displayWorktreePath,
+ presentAlert: (buttons) => {
+ Alert.alert(buttons.title, buttons.message, [
+ { text: "Keep", style: "cancel", onPress: buttons.onKeep },
+ { text: "Remove", style: "destructive", onPress: buttons.onRemove },
+ ]);
+ },
+ presentConfirmDialog: (buttons) => {
+ showConfirmDialog({
+ title: buttons.title,
+ message: buttons.message,
+ cancelText: "Keep",
+ confirmText: "Remove",
+ destructive: true,
+ onConfirm: buttons.onRemove,
+ onCancel: buttons.onKeep,
+ });
+ },
+ }),
+ archive: () => executeAction("archive", thread),
+ isArchiveSuccess: (archived) => archived,
+ cleanup: async () => {
+ const result = await cleanupThreadWorktree({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ if (result._tag === "Failure") {
+ const error = Cause.squash(result.cause);
+ return {
+ kind: "failed",
+ message:
+ error instanceof Error && error.message.trim().length > 0
+ ? error.message
+ : "The worktree could not be removed.",
+ } as const;
+ }
+ return { kind: "done", status: result.value.status } as const;
+ },
+ // Cleanup problems are nonfatal: the archive itself already
+ // succeeded.
+ onCleanupFailed: (displayWorktreePath, message) => {
+ Alert.alert(
+ "Thread archived, but worktree removal failed",
+ `Could not remove ${displayWorktreePath}. ${message}`,
+ );
+ },
+ onCleanupRetained: (displayWorktreePath) => {
+ Alert.alert(
+ "Worktree kept",
+ `${displayWorktreePath} is still used by another active thread.`,
+ );
+ },
+ });
  },
- [executeAction],
+ [cleanupThreadWorktree, executeAction, previewWorktreeCleanup],
  );
  const settleThread = useCallback(
  async (thread: EnvironmentThreadShell) => (await executeAction("settle", thread)) === true,

apps/mobile/src/features/home/worktreeCleanupPrompt.test.ts

@@ -0,0 +1,102 @@
+import { WorktreeLifecycleError } from "@t3tools/contracts";
+import { ThreadId } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { actionFailureMessage, actionFailureTitle } from "./threadActionMessages";
+import {
+ buildWorktreeCleanupPrompt,
+ presentWorktreeCleanupConfirmation,
+} from "./worktreeCleanupPrompt";
+
+describe("presentWorktreeCleanupConfirmation", () => {
+ it("uses the native alert on iOS and never the confirm dialog", async () => {
+ const presentAlert = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onRemove();
+ },
+ );
+ const presentConfirmDialog = vi.fn();
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "confirmed" });
+ expect(presentAlert).toHaveBeenCalledTimes(1);
+ expect(presentConfirmDialog).not.toHaveBeenCalled();
+ });
+
+ it("uses the confirm dialog host elsewhere", async () => {
+ const presentAlert = vi.fn();
+ const presentConfirmDialog = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onKeep();
+ },
+ );
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "declined" });
+ expect(presentAlert).not.toHaveBeenCalled();
+ expect(presentConfirmDialog).toHaveBeenCalledTimes(1);
+ });
+
+ it("resolves declined for Keep and confirmed for Remove", async () => {
+ const keep = presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert: (buttons) => {
+ buttons.onKeep();
+ },
+ presentConfirmDialog: () => {},
+ });
+ await expect(keep).resolves.toEqual({ kind: "declined" });
+
+ const remove = presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert: () => {},
+ presentConfirmDialog: (buttons) => {
+ buttons.onRemove();
+ },
+ });
+ await expect(remove).resolves.toEqual({ kind: "confirmed" });
+ });
+
+ it("names the worktree in the prompt copy", () => {
+ const prompt = buildWorktreeCleanupPrompt("feature-1");
+ expect(prompt.title).toBe("Remove worktree?");
+ expect(prompt.message).toContain("feature-1");
+ expect(prompt.message).toContain("branch is kept");
+ });
+});
+
+describe("thread action failure messages", () => {
+ it("surfaces unarchive restoration errors with the server-provided detail", () => {
+ const restorationError = new WorktreeLifecycleError({
+ operation: "restore",
+ threadId: ThreadId.make("thread-1"),
+ detail:
+ "Failed to recreate the worktree at /wt/feature-1 from branch 'feature-1': branch missing. The thread stays archived.",
+ });
+ expect(actionFailureTitle("unarchive")).toBe("Could not unarchive thread");
+ expect(actionFailureMessage("unarchive", Cause.fail(restorationError))).toContain(
+ "Failed to recreate the worktree",
+ );
+ });
+
+ it("falls back to a generic message when the cause has no message", () => {
+ expect(actionFailureMessage("unarchive", Cause.fail(new Error("")))).toBe(
+ "The thread could not be unarchived.",
+ );
+ });
+});

apps/mobile/src/features/home/worktreeCleanupPrompt.ts

@@ -0,0 +1,49 @@
+import type { WorktreeCleanupConfirmation } from "@t3tools/client-runtime/state/worktreeCleanup";
+
+export interface WorktreeCleanupPromptButtons {
+ readonly title: string;
+ readonly message: string;
+ readonly onKeep: () => void;
+ readonly onRemove: () => void;
+}
+
+export function buildWorktreeCleanupPrompt(displayWorktreePath: string): {
+ readonly title: string;
+ readonly message: string;
+} {
+ return {
+ title: "Remove worktree?",
+ message: `This thread is the last active one linked to the worktree “${displayWorktreePath}”. Remove it when archiving? The branch is kept.`,
+ };
+}
+
+/**
+ * Presents the archive-time cleanup confirmation through the platform's
+ * surface: the native alert on iOS, the in-app confirm dialog elsewhere.
+ * Keep archives without cleanup; Remove archives and cleans up.
+ */
+export function presentWorktreeCleanupConfirmation(input: {
+ readonly isIos: boolean;
+ readonly displayWorktreePath: string;
+ readonly presentAlert: (buttons: WorktreeCleanupPromptButtons) => void;
+ readonly presentConfirmDialog: (buttons: WorktreeCleanupPromptButtons) => void;
+}): Promise<WorktreeCleanupConfirmation<never>> {
+ const { title, message } = buildWorktreeCleanupPrompt(input.displayWorktreePath);
+ return new Promise((resolve) => {
+ const buttons: WorktreeCleanupPromptButtons = {
+ title,
+ message,
+ onKeep: () => {
+ resolve({ kind: "declined" });
+ },
+ onRemove: () => {
+ resolve({ kind: "confirmed" });
+ },
+ };
+ if (input.isIos) {
+ input.presentAlert(buttons);
+ return;
+ }
+ input.presentConfirmDialog(buttons);
+ });
+}

apps/server/src/auth/RpcAuthorization.ts

@@ -71,6 +71,8 @@ export const RPC_REQUIRED_SCOPES = {
  [WS_METHODS.vcsListRefs]: AuthOrchestrationReadScope,
  [WS_METHODS.vcsCreateWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsRemoveWorktree]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsPreviewWorktreeCleanup]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsCleanupThreadWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsCreateRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsSwitchRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsInit]: AuthOrchestrationOperateScope,

apps/server/src/checkpointing/CheckpointDiffQuery.test.ts

@@ -106,6 +106,7 @@ describe("CheckpointDiffQuery.layer", () => {
  });
  }),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -200,6 +201,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -284,6 +286,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -353,6 +356,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -407,6 +411,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts

@@ -201,6 +201,7 @@ describe("OrchestrationEngine", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/mobile/src/features/home/threadActionMessages.ts

@@ -0,0 +1,30 @@
+import * as Cause from "effect/Cause";
+
+export type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
+
+const ACTION_VERBS: Record<ThreadListAction, string> = {
+ archive: "archived",
+ unarchive: "unarchived",
+ delete: "deleted",
+ settle: "settled",
+ unsettle: "un-settled",
+};
+
+export function actionFailureMessage(
+ action: ThreadListAction,
+ cause: Cause.Cause<unknown>,
+): string {
+ const error = Cause.squash(cause);
+ if (error instanceof Error && error.message.trim().length > 0) {
+ return error.message;
+ }
+ return `The thread could not be ${ACTION_VERBS[action]}.`;
+}
+
+export function actionFailureTitle(action: ThreadListAction): string {
+ if (action === "archive") return "Could not archive thread";
+ if (action === "unarchive") return "Could not unarchive thread";
+ if (action === "settle") return "Could not settle thread";
+ if (action === "unsettle") return "Could not un-settle thread";
+ return "Could not delete thread";
+}

apps/mobile/src/features/home/useThreadListActions.ts

@@ -1,5 +1,6 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { canSettle } from "@t3tools/client-runtime/state/thread-settled";
+import { runArchiveWithWorktreeCleanup } from "@t3tools/client-runtime/state/worktreeCleanup";
 import * as Cause from "effect/Cause";
 import * as Haptics from "expo-haptics";
 import { useCallback, useRef } from "react";
@@ -11,7 +12,14 @@ import { refreshArchivedThreadsForEnvironment } from "../archive/useArchivedThre
 import { appAtomRegistry } from "../../state/atom-registry";
 import { environmentServerConfigsAtom } from "../../state/server";
 import { threadEnvironment } from "../../state/threads";
+import { vcsEnvironment } from "../../state/vcs";
 import { useAtomCommand } from "../../state/use-atom-command";
+import {
+ actionFailureMessage,
+ actionFailureTitle,
+ type ThreadListAction,
+} from "./threadActionMessages";
+import { presentWorktreeCleanupConfirmation } from "./worktreeCleanupPrompt";
 
 /** Version skew: never send settle/unsettle to a server that predates them
  (capability defaults false on decode for older servers). */
@@ -22,36 +30,10 @@ function environmentSupportsSettlement(environmentId: EnvironmentThreadShell["en
  );
 }
 
-type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
-
-const ACTION_VERBS: Record<ThreadListAction, string> = {
- archive: "archived",
- unarchive: "unarchived",
- delete: "deleted",
- settle: "settled",
- unsettle: "un-settled",
-};
-
-function actionFailureMessage(action: ThreadListAction, cause: Cause.Cause<unknown>): string {
- const error = Cause.squash(cause);
- if (error instanceof Error && error.message.trim().length > 0) {
- return error.message;
- }
- return `The thread could not be ${ACTION_VERBS[action]}.`;
-}
-
 function selectionHaptic(): void {
  void Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);
 }
 
-function actionFailureTitle(action: ThreadListAction): string {
- if (action === "archive") return "Could not archive thread";
- if (action === "unarchive") return "Could not unarchive thread";
- if (action === "settle") return "Could not settle thread";
- if (action === "unsettle") return "Could not un-settle thread";
- return "Could not delete thread";
-}
-
 /** Resolves to true iff the action was dispatched and succeeded. */
 function useThreadActionExecutor(
  onCompleted?: (action: ThreadListAction, thread: EnvironmentThreadShell) => void,
@@ -195,12 +177,88 @@ export function useThreadListActions(): {
  readonly unsettleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
 } {
  const executeAction = useThreadActionExecutor();
+ const previewWorktreeCleanup = useAtomCommand(vcsEnvironment.previewWorktreeCleanup, {
+ reportFailure: false,
+ });
+ const cleanupThreadWorktree = useAtomCommand(vcsEnvironment.cleanupThreadWorktree, {
+ reportFailure: false,
+ });
 
  const archiveThread = useCallback(
  (thread: EnvironmentThreadShell) => {
- void executeAction("archive", thread);
+ void runArchiveWithWorktreeCleanup({
+ // Server-authoritative preview; a failure (old server, transient
+ // error) degrades to a plain archive without a prompt. A thread
+ // mid-turn keeps the original archive guard: executeAction re-checks
+ // and surfaces the alert, so it must not be prompted for cleanup.
+ previewCandidate: async () => {
+ if (thread.session?.status === "running" && thread.session.activeTurnId != null) {
+ return null;
+ }
+ const preview = await previewWorktreeCleanup({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ return preview._tag === "Success" ? preview.value.candidate : null;
+ },
+ confirmRemoval: ({ displayWorktreePath }) =>
+ presentWorktreeCleanupConfirmation({
+ isIos: process.env.EXPO_OS === "ios",
+ displayWorktreePath,
+ presentAlert: (buttons) => {
+ Alert.alert(buttons.title, buttons.message, [
+ { text: "Keep", style: "cancel", onPress: buttons.onKeep },
+ { text: "Remove", style: "destructive", onPress: buttons.onRemove },
+ ]);
+ },
+ presentConfirmDialog: (buttons) => {
+ showConfirmDialog({
+ title: buttons.title,
+ message: buttons.message,
+ cancelText: "Keep",
+ confirmText: "Remove",
+ destructive: true,
+ onConfirm: buttons.onRemove,
+ onCancel: buttons.onKeep,
+ });
+ },
+ }),
+ archive: () => executeAction("archive", thread),
+ isArchiveSuccess: (archived) => archived,
+ cleanup: async () => {
+ const result = await cleanupThreadWorktree({
+ environmentId: thread.environmentId,
+ input: { threadId: thread.id },
+ });
+ if (result._tag === "Failure") {
+ const error = Cause.squash(result.cause);
+ return {
+ kind: "failed",
+ message:
+ error instanceof Error && error.message.trim().length > 0
+ ? error.message
+ : "The worktree could not be removed.",
+ } as const;
+ }
+ return { kind: "done", status: result.value.status } as const;
+ },
+ // Cleanup problems are nonfatal: the archive itself already
+ // succeeded.
+ onCleanupFailed: (displayWorktreePath, message) => {
+ Alert.alert(
+ "Thread archived, but worktree removal failed",
+ `Could not remove ${displayWorktreePath}. ${message}`,
+ );
+ },
+ onCleanupRetained: (displayWorktreePath) => {
+ Alert.alert(
+ "Worktree kept",
+ `${displayWorktreePath} is still used by another active thread.`,
+ );
+ },
+ });
  },
- [executeAction],
+ [cleanupThreadWorktree, executeAction, previewWorktreeCleanup],
  );
  const settleThread = useCallback(
  async (thread: EnvironmentThreadShell) => (await executeAction("settle", thread)) === true,

apps/mobile/src/features/home/worktreeCleanupPrompt.test.ts

@@ -0,0 +1,102 @@
+import { WorktreeLifecycleError } from "@t3tools/contracts";
+import { ThreadId } from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import { actionFailureMessage, actionFailureTitle } from "./threadActionMessages";
+import {
+ buildWorktreeCleanupPrompt,
+ presentWorktreeCleanupConfirmation,
+} from "./worktreeCleanupPrompt";
+
+describe("presentWorktreeCleanupConfirmation", () => {
+ it("uses the native alert on iOS and never the confirm dialog", async () => {
+ const presentAlert = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onRemove();
+ },
+ );
+ const presentConfirmDialog = vi.fn();
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "confirmed" });
+ expect(presentAlert).toHaveBeenCalledTimes(1);
+ expect(presentConfirmDialog).not.toHaveBeenCalled();
+ });
+
+ it("uses the confirm dialog host elsewhere", async () => {
+ const presentAlert = vi.fn();
+ const presentConfirmDialog = vi.fn(
+ (buttons: { readonly onKeep: () => void; readonly onRemove: () => void }) => {
+ buttons.onKeep();
+ },
+ );
+
+ const confirmation = await presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert,
+ presentConfirmDialog,
+ });
+
+ expect(confirmation).toEqual({ kind: "declined" });
+ expect(presentAlert).not.toHaveBeenCalled();
+ expect(presentConfirmDialog).toHaveBeenCalledTimes(1);
+ });
+
+ it("resolves declined for Keep and confirmed for Remove", async () => {
+ const keep = presentWorktreeCleanupConfirmation({
+ isIos: true,
+ displayWorktreePath: "feature-1",
+ presentAlert: (buttons) => {
+ buttons.onKeep();
+ },
+ presentConfirmDialog: () => {},
+ });
+ await expect(keep).resolves.toEqual({ kind: "declined" });
+
+ const remove = presentWorktreeCleanupConfirmation({
+ isIos: false,
+ displayWorktreePath: "feature-1",
+ presentAlert: () => {},
+ presentConfirmDialog: (buttons) => {
+ buttons.onRemove();
+ },
+ });
+ await expect(remove).resolves.toEqual({ kind: "confirmed" });
+ });
+
+ it("names the worktree in the prompt copy", () => {
+ const prompt = buildWorktreeCleanupPrompt("feature-1");
+ expect(prompt.title).toBe("Remove worktree?");
+ expect(prompt.message).toContain("feature-1");
+ expect(prompt.message).toContain("branch is kept");
+ });
+});
+
+describe("thread action failure messages", () => {
+ it("surfaces unarchive restoration errors with the server-provided detail", () => {
+ const restorationError = new WorktreeLifecycleError({
+ operation: "restore",
+ threadId: ThreadId.make("thread-1"),
+ detail:
+ "Failed to recreate the worktree at /wt/feature-1 from branch 'feature-1': branch missing. The thread stays archived.",
+ });
+ expect(actionFailureTitle("unarchive")).toBe("Could not unarchive thread");
+ expect(actionFailureMessage("unarchive", Cause.fail(restorationError))).toContain(
+ "Failed to recreate the worktree",
+ );
+ });
+
+ it("falls back to a generic message when the cause has no message", () => {
+ expect(actionFailureMessage("unarchive", Cause.fail(new Error("")))).toBe(
+ "The thread could not be unarchived.",
+ );
+ });
+});

apps/mobile/src/features/home/worktreeCleanupPrompt.ts

@@ -0,0 +1,49 @@
+import type { WorktreeCleanupConfirmation } from "@t3tools/client-runtime/state/worktreeCleanup";
+
+export interface WorktreeCleanupPromptButtons {
+ readonly title: string;
+ readonly message: string;
+ readonly onKeep: () => void;
+ readonly onRemove: () => void;
+}
+
+export function buildWorktreeCleanupPrompt(displayWorktreePath: string): {
+ readonly title: string;
+ readonly message: string;
+} {
+ return {
+ title: "Remove worktree?",
+ message: `This thread is the last active one linked to the worktree “${displayWorktreePath}”. Remove it when archiving? The branch is kept.`,
+ };
+}
+
+/**
+ * Presents the archive-time cleanup confirmation through the platform's
+ * surface: the native alert on iOS, the in-app confirm dialog elsewhere.
+ * Keep archives without cleanup; Remove archives and cleans up.
+ */
+export function presentWorktreeCleanupConfirmation(input: {
+ readonly isIos: boolean;
+ readonly displayWorktreePath: string;
+ readonly presentAlert: (buttons: WorktreeCleanupPromptButtons) => void;
+ readonly presentConfirmDialog: (buttons: WorktreeCleanupPromptButtons) => void;
+}): Promise<WorktreeCleanupConfirmation<never>> {
+ const { title, message } = buildWorktreeCleanupPrompt(input.displayWorktreePath);
+ return new Promise((resolve) => {
+ const buttons: WorktreeCleanupPromptButtons = {
+ title,
+ message,
+ onKeep: () => {
+ resolve({ kind: "declined" });
+ },
+ onRemove: () => {
+ resolve({ kind: "confirmed" });
+ },
+ };
+ if (input.isIos) {
+ input.presentAlert(buttons);
+ return;
+ }
+ input.presentConfirmDialog(buttons);
+ });
+}

apps/server/src/auth/RpcAuthorization.ts

@@ -71,6 +71,8 @@ export const RPC_REQUIRED_SCOPES = {
  [WS_METHODS.vcsListRefs]: AuthOrchestrationReadScope,
  [WS_METHODS.vcsCreateWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsRemoveWorktree]: AuthOrchestrationOperateScope,
+ [WS_METHODS.vcsPreviewWorktreeCleanup]: AuthOrchestrationReadScope,
+ [WS_METHODS.vcsCleanupThreadWorktree]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsCreateRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsSwitchRef]: AuthOrchestrationOperateScope,
  [WS_METHODS.vcsInit]: AuthOrchestrationOperateScope,

apps/server/src/checkpointing/CheckpointDiffQuery.test.ts

@@ -106,6 +106,7 @@ describe("CheckpointDiffQuery.layer", () => {
  });
  }),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -200,6 +201,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -284,6 +286,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -353,6 +356,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
  getFullThreadDiffContext: () => Effect.die("unused"),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),
@@ -407,6 +411,7 @@ describe("CheckpointDiffQuery.layer", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),

apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts

@@ -201,6 +201,7 @@ describe("OrchestrationEngine", () => {
  getThreadCheckpointContext: () => Effect.succeed(Option.none()),
  getFullThreadDiffContext: () => Effect.succeed(Option.none()),
  getThreadShellById: () => Effect.succeed(Option.none()),
+ getSessionStopContextById: () => Effect.succeed(Option.none()),
  getThreadDetailById: () => Effect.succeed(Option.none()),
  getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
  searchThreads: () => Effect.succeed({ matches: [] }),