feat(settings): control completed pull request auto-settlement (#2)

Add a dedicated setting for completed pull request auto-settlement across web, desktop, and mobile while preserving existing defaults and independent inactivity behavior.

Author: Defmon3

apps/desktop/src/settings/DesktopClientSettings.test.ts

@@ -33,6 +33,7 @@ const clientSettings: ClientSettings = {
   planModeEnabled: false,
   providerModelPreferences: {},
   sidebarAutoSettleAfterDays: 3,
+  sidebarAutoSettleCompletedChangeRequests: false,
   sidebarProjectGroupingMode: "repository_path",
   sidebarProjectGroupingOverrides: {
     "environment-1:/tmp/project-a": "separate",
@@ -201,7 +202,9 @@ describe("DesktopClientSettings", () => {
         yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
         yield* fileSystem.writeFileString(environment.clientSettingsPath, "{}\n");
 
-        assert.deepEqual(yield* settings.get, Option.some(yield* decodeClientSettingsJson("{}")));
+        const persisted = yield* settings.get;
+        assert.deepEqual(persisted, Option.some(yield* decodeClientSettingsJson("{}")));
+        assert.isTrue(Option.getOrThrow(persisted).sidebarAutoSettleCompletedChangeRequests);
       }),
     ),
   );

apps/mobile/src/features/home/HomeScreen.tsx

@@ -33,6 +33,7 @@ import { scopedProjectKey } from "../../lib/scopedEntities";
 import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../../native/native-glass";
 import { mobilePreferencesAtom, updateMobilePreferencesAtom } from "../../state/preferences";
 import { useThreadSearch } from "../../state/queries";
+import { useAutoSettleCompletedChangeRequests } from "../threads/use-auto-settle-completed-change-requests";
 import { useThreadListV2Enabled } from "../threads/use-thread-list-v2-enabled";
 import { environmentServerConfigsAtom } from "../../state/server";
 import type { PendingNewTask } from "../../state/use-pending-new-tasks";
@@ -207,6 +208,7 @@ export function HomeScreen(props: HomeScreenProps) {
   >(() => new Map());
   const preferencesResult = useAtomValue(mobilePreferencesAtom);
   const threadListV2Enabled = useThreadListV2Enabled();
+  const autoSettleCompletedChangeRequests = useAutoSettleCompletedChangeRequests();
   const savePreferences = useAtomSet(updateMobilePreferencesAtom);
   const openSwipeableRef = useRef<SwipeableMethods | null>(null);
   const listRef = useRef<LegendListRef | null>(null);
@@ -665,6 +667,7 @@ export function HomeScreen(props: HomeScreenProps) {
       searchQuery: props.searchQuery,
       matchedThreadKeys,
       changeRequestStateByKey,
+      autoSettleCompletedChangeRequests,
       settlementEnvironmentIds,
       snoozeEnvironmentIds,
       settledLimit: settledVisibleCount,
@@ -675,6 +678,7 @@ export function HomeScreen(props: HomeScreenProps) {
       selectedThreadKey: null,
     });
   }, [
+    autoSettleCompletedChangeRequests,
     changeRequestStateByKey,
     nowMinute,
     snoozeWakeTick,

apps/mobile/src/features/settings/SettingsRouteScreen.tsx

@@ -35,6 +35,7 @@ import { WorkspaceSidebarToolbar } from "../layout/workspace-sidebar-toolbar";
 import { runtime } from "../../lib/runtime";
 import { useThemeColor } from "../../lib/useThemeColor";
 import { mobilePreferencesAtom, updateMobilePreferencesAtom } from "../../state/preferences";
+import { useAutoSettleCompletedChangeRequests } from "../threads/use-auto-settle-completed-change-requests";
 import { useThreadListV2Enabled } from "../threads/use-thread-list-v2-enabled";
 import {
   type AppUpdateCheckState,
@@ -46,6 +47,7 @@ import { useSavedRemoteConnections } from "../../state/use-remote-environment-re
 import { SettingsRow } from "./components/SettingsRow";
 import { SettingsSection } from "./components/SettingsSection";
 import { SettingsSwitchRow } from "./components/SettingsSwitchRow";
+import { shouldShowAutoSettleCompletedChangeRequestsSetting } from "./autoSettleCompletedChangeRequests";
 
 type NotificationStatus = "checking" | "enabled" | "disabled" | "unsupported";
 type LiveActivityStatus = "checking" | "enabled" | "disabled" | "signed-out" | "linking";
@@ -522,10 +524,27 @@ function ConfiguredSettingsRouteScreen() {
 }
 
 function GeneralSettingsSection() {
+  const preferencesResult = useAtomValue(mobilePreferencesAtom);
+  const savePreferences = useAtomSet(updateMobilePreferencesAtom);
+  const threadListV2Enabled = useThreadListV2Enabled();
+  const autoSettleCompletedChangeRequests = useAutoSettleCompletedChangeRequests();
+  const preferencesLoaded = AsyncResult.isSuccess(preferencesResult) && !preferencesResult.waiting;
+
   return (
     <SettingsSection title="General">
       <SettingsRow icon="folder" label="Project Grouping" target="SettingsProjectGrouping" />
       <SettingsRow icon="chart.bar.xaxis" label="Usage" target="SettingsUsage" />
+      {shouldShowAutoSettleCompletedChangeRequestsSetting({
+        preferencesLoaded,
+        threadListV2Enabled,
+      }) ? (
+        <SettingsSwitchRow
+          icon="checkmark.circle"
+          label="Auto-settle completed pull requests"
+          value={autoSettleCompletedChangeRequests}
+          onValueChange={(value) => savePreferences({ autoSettleCompletedChangeRequests: value })}
+        />
+      ) : null}
     </SettingsSection>
   );
 }

apps/mobile/src/features/settings/autoSettleCompletedChangeRequests.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { shouldShowAutoSettleCompletedChangeRequestsSetting } from "./autoSettleCompletedChangeRequests";
+
+describe("shouldShowAutoSettleCompletedChangeRequestsSetting", () => {
+  it("shows the control only after preferences load for the list it changes", () => {
+    expect(
+      shouldShowAutoSettleCompletedChangeRequestsSetting({
+        preferencesLoaded: false,
+        threadListV2Enabled: true,
+      }),
+    ).toBe(false);
+    expect(
+      shouldShowAutoSettleCompletedChangeRequestsSetting({
+        preferencesLoaded: true,
+        threadListV2Enabled: false,
+      }),
+    ).toBe(false);
+    expect(
+      shouldShowAutoSettleCompletedChangeRequestsSetting({
+        preferencesLoaded: true,
+        threadListV2Enabled: true,
+      }),
+    ).toBe(true);
+  });
+});

apps/mobile/src/features/settings/autoSettleCompletedChangeRequests.ts

@@ -0,0 +1,6 @@
+export function shouldShowAutoSettleCompletedChangeRequestsSetting(input: {
+  readonly preferencesLoaded: boolean;
+  readonly threadListV2Enabled: boolean;
+}): boolean {
+  return input.preferencesLoaded && input.threadListV2Enabled;
+}

apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx

@@ -30,6 +30,7 @@ import { scopedProjectKey, scopedThreadKey } from "../../lib/scopedEntities";
 import { useThemeColor } from "../../lib/useThemeColor";
 import { useProjects, useThreadShells } from "../../state/entities";
 import { useThreadSearch } from "../../state/queries";
+import { useAutoSettleCompletedChangeRequests } from "./use-auto-settle-completed-change-requests";
 import { useThreadListV2Enabled } from "./use-thread-list-v2-enabled";
 import { environmentServerConfigsAtom } from "../../state/server";
 import { usePendingNewTasks } from "../../state/use-pending-new-tasks";
@@ -214,6 +215,7 @@ function ThreadNavigationSidebarPane(
     regenerateThreadTitle,
   } = useThreadListActions();
   const threadListV2Enabled = useThreadListV2Enabled();
+  const autoSettleCompletedChangeRequests = useAutoSettleCompletedChangeRequests();
   const pendingTasks = usePendingNewTasks();
   const { openPendingTask, confirmDeletePendingTask } = usePendingTaskListActions();
   const environments = useMemo(
@@ -546,6 +548,7 @@ function ThreadNavigationSidebarPane(
       searchQuery: props.searchQuery,
       matchedThreadKeys,
       changeRequestStateByKey,
+      autoSettleCompletedChangeRequests,
       settlementEnvironmentIds,
       snoozeEnvironmentIds,
       settledLimit: settledVisibleCount,
@@ -556,6 +559,7 @@ function ThreadNavigationSidebarPane(
       selectedThreadKey: props.selectedThreadKey ?? null,
     });
   }, [
+    autoSettleCompletedChangeRequests,
     changeRequestStateByKey,
     nowMinute,
     snoozeWakeTick,

apps/mobile/src/features/threads/threadListV2.test.ts

@@ -3,6 +3,7 @@ import { threadSearchMatchKey } from "@t3tools/client-runtime/state/thread-searc
 import { resolveSnoozePresets } from "@t3tools/client-runtime/state/thread-settled";
 import {
   CommandId,
+  DEFAULT_SIDEBAR_AUTO_SETTLE_COMPLETED_CHANGE_REQUESTS,
   EnvironmentId,
   MessageId,
   ProjectId,
@@ -16,6 +17,7 @@ import type { PendingNewTask } from "../../state/use-pending-new-tasks";
 import {
   buildThreadListV2Items,
   buildThreadListV2ListItems,
+  resolveAutoSettleCompletedChangeRequests,
   resolveThreadListV2Enabled,
   resolveThreadListV2SnoozeMenuSelection,
   resolveThreadListV2SnoozeGateExpiryMs,
@@ -125,6 +127,29 @@ describe("resolveThreadListV2Enabled", () => {
   });
 });
 
+describe("resolveAutoSettleCompletedChangeRequests", () => {
+  it("preserves an explicit disabled preference", () => {
+    expect(
+      resolveAutoSettleCompletedChangeRequests({ preference: false, preferencesLoaded: true }),
+    ).toBe(false);
+  });
+
+  it("uses the shared completed-PR auto-settle default when the preference is absent", () => {
+    expect(DEFAULT_SIDEBAR_AUTO_SETTLE_COMPLETED_CHANGE_REQUESTS).toBe(true);
+    expect(
+      resolveAutoSettleCompletedChangeRequests({ preference: undefined, preferencesLoaded: true }),
+    ).toBe(DEFAULT_SIDEBAR_AUTO_SETTLE_COMPLETED_CHANGE_REQUESTS);
+  });
+
+  it("keeps a saved disabled preference disabled through hydration", () => {
+    const resolvedStates = [false, true].map((preferencesLoaded) =>
+      resolveAutoSettleCompletedChangeRequests({ preference: false, preferencesLoaded }),
+    );
+
+    expect(resolvedStates).toEqual([false, false]);
+  });
+});
+
 describe("resolveThreadListV2Status", () => {
   it("prioritizes approval over a running session", () => {
     const thread = makeThread({
@@ -315,6 +340,107 @@ describe("buildThreadListV2Items", () => {
     expect(layout.settledCount).toBe(0);
   });
 
+  it("keeps fresh completed-PR threads active when completed-PR auto-settle is off", () => {
+    const fresh = makeThread({
+      id: ThreadId.make("fresh-completed-pr"),
+      title: "Fresh completed PR",
+      latestUserMessageAt: "2026-06-01T12:00:00.000Z",
+      latestTurn: {
+        turnId: TurnId.make("fresh-completed-pr-turn"),
+        state: "completed",
+        requestedAt: "2026-06-01T12:00:00.000Z",
+        startedAt: "2026-06-01T12:00:00.000Z",
+        completedAt: "2026-06-01T12:10:00.000Z",
+        assistantMessageId: null,
+      },
+    });
+    const layout = buildThreadListV2Items({
+      threads: [fresh],
+      environmentId: null,
+      searchQuery: "",
+      now: NOW,
+      autoSettleAfterDays: 3,
+      autoSettleCompletedChangeRequests: false,
+      changeRequestStateByKey: new Map([[`${environmentId}:${fresh.id}`, "merged"]]),
+    });
+
+    expect(layout.items.map((item) => [item.thread.id, item.variant])).toEqual([
+      ["fresh-completed-pr", "card"],
+    ]);
+    expect(layout.settledCount).toBe(0);
+  });
+
+  it("does not briefly settle a saved-disabled completed pull request while preferences hydrate", () => {
+    const fresh = makeThread({
+      id: ThreadId.make("saved-disabled-completed-pr"),
+      title: "Saved disabled completed PR",
+    });
+    const layouts = [false, true].map((preferencesLoaded) =>
+      buildThreadListV2Items({
+        threads: [fresh],
+        environmentId: null,
+        searchQuery: "",
+        now: NOW,
+        autoSettleCompletedChangeRequests: resolveAutoSettleCompletedChangeRequests({
+          preference: false,
+          preferencesLoaded,
+        }),
+        changeRequestStateByKey: new Map([[`${environmentId}:${fresh.id}`, "closed"]]),
+      }),
+    );
+
+    expect(layouts.map((layout) => layout.items[0]?.variant)).toEqual(["card", "card"]);
+    expect(layouts.map((layout) => layout.settledCount)).toEqual([0, 0]);
+  });
+
+  it("defaults completed-PR auto-settle on for existing mobile installs", () => {
+    const fresh = makeThread({
+      id: ThreadId.make("default-completed-pr"),
+      title: "Default completed PR",
+    });
+    const layout = buildThreadListV2Items({
+      threads: [fresh],
+      environmentId: null,
+      searchQuery: "",
+      now: NOW,
+      changeRequestStateByKey: new Map([[`${environmentId}:${fresh.id}`, "merged"]]),
+    });
+
+    expect(layout.items.map((item) => [item.thread.id, item.variant])).toEqual([
+      ["default-completed-pr", "slim"],
+    ]);
+  });
+
+  it("keeps inactivity settlement independent when completed-PR auto-settle is off", () => {
+    const stale = makeThread({
+      id: ThreadId.make("stale-completed-pr"),
+      title: "Stale completed PR",
+      latestUserMessageAt: "2026-05-28T12:00:00.000Z",
+      latestTurn: {
+        turnId: TurnId.make("stale-completed-pr-turn"),
+        state: "completed",
+        requestedAt: "2026-05-28T12:00:00.000Z",
+        startedAt: "2026-05-28T12:00:00.000Z",
+        completedAt: "2026-05-28T12:10:00.000Z",
+        assistantMessageId: null,
+      },
+    });
+    const layout = buildThreadListV2Items({
+      threads: [stale],
+      environmentId: null,
+      searchQuery: "",
+      now: NOW,
+      autoSettleAfterDays: 3,
+      autoSettleCompletedChangeRequests: false,
+      changeRequestStateByKey: new Map([[`${environmentId}:${stale.id}`, "closed"]]),
+    });
+
+    expect(layout.items.map((item) => [item.thread.id, item.variant])).toEqual([
+      ["stale-completed-pr", "slim"],
+    ]);
+    expect(layout.settledCount).toBe(1);
+  });
+
   it("snooze hides a pinned thread and wake restores it to the pinned block", () => {
     const snoozedInput = {
       threads: [

apps/mobile/src/features/threads/threadListV2.ts

@@ -10,7 +10,11 @@ import type { SnoozePreset } from "@t3tools/client-runtime/state/thread-settled"
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { threadSearchMatchKey } from "@t3tools/client-runtime/state/thread-search";
 import { sortPinnedThreadsByOrderKey } from "@t3tools/client-runtime/state/thread-sort";
-import type { EnvironmentId, ProjectId } from "@t3tools/contracts";
+import {
+  DEFAULT_SIDEBAR_AUTO_SETTLE_COMPLETED_CHANGE_REQUESTS,
+  type EnvironmentId,
+  type ProjectId,
+} from "@t3tools/contracts";
 
 import type { PendingNewTask } from "../../state/use-pending-new-tasks";
 
@@ -122,6 +126,20 @@ export function resolveThreadListV2Enabled(input: {
   return input.legacyPreference !== true;
 }
 
+/**
+ * Existing installs had completed-PR auto-settlement before this preference
+ * existed, so an absent loaded value preserves that behavior. Until mobile
+ * preferences load, keep every thread visible rather than temporarily settling
+ * a thread whose stored device-local preference is false.
+ */
+export function resolveAutoSettleCompletedChangeRequests(input: {
+  readonly preference: boolean | undefined;
+  readonly preferencesLoaded: boolean;
+}): boolean {
+  if (!input.preferencesLoaded) return false;
+  return input.preference ?? DEFAULT_SIDEBAR_AUTO_SETTLE_COMPLETED_CHANGE_REQUESTS;
+}
+
 export function resolveThreadListV2Status(
   thread: Pick<EnvironmentThreadShell, "hasPendingApprovals" | "hasPendingUserInput" | "session">,
 ): ThreadListV2Status {
@@ -307,8 +325,8 @@ export function buildThreadListV2ListItems(input: {
 /**
  * Partitions visible threads into the active card block (creation order) and
  * the settled recency tail, matching the web v2 list. `autoSettleAfterDays`
- * mirrors the web default of 3 — mobile has no client-settings sync yet, so
- * the default is fixed here rather than user-configurable.
+ * mirrors the web default of 3. Completed-change-request auto-settlement is
+ * configurable through a device-local mobile preference.
  */
 export function buildThreadListV2Items(input: {
   readonly threads: ReadonlyArray<EnvironmentThreadShell>;
@@ -329,6 +347,7 @@ export function buildThreadListV2Items(input: {
       contract as settlementEnvironmentIds. */
   readonly snoozeEnvironmentIds?: ReadonlySet<EnvironmentId>;
   readonly autoSettleAfterDays?: number;
+  readonly autoSettleCompletedChangeRequests?: boolean;
   /** Max settled rows to render; the rest are counted, not built. */
   readonly settledLimit?: number;
   /** Injectable for tests; defaults to now. */
@@ -349,6 +368,9 @@ export function buildThreadListV2Items(input: {
   const now = input.now ?? new Date().toISOString();
   const snoozeNow = input.snoozeNow ?? now;
   const autoSettleAfterDays = input.autoSettleAfterDays ?? 3;
+  const autoSettleCompletedChangeRequests =
+    input.autoSettleCompletedChangeRequests ??
+    DEFAULT_SIDEBAR_AUTO_SETTLE_COMPLETED_CHANGE_REQUESTS;
   const query = input.searchQuery.trim().toLocaleLowerCase();
   const projectKeys = input.projectRefs
     ? new Set(input.projectRefs.map((ref) => `${ref.environmentId}:${ref.projectId}`))
@@ -405,7 +427,12 @@ export function buildThreadListV2Items(input: {
     }
     if (
       supportsSettlement &&
-      effectiveSettled(thread, { now, autoSettleAfterDays, changeRequestState })
+      effectiveSettled(thread, {
+        now,
+        autoSettleAfterDays,
+        autoSettleCompletedChangeRequests,
+        changeRequestState,
+      })
     ) {
       settled.push(thread);
     } else {