feat(web): add toggleable confirmation before unpinning a thread

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

@@ -21,6 +21,7 @@ const clientSettings: ClientSettings = {
  confirmQuit: true,
  confirmThreadArchive: true,
  confirmThreadDelete: false,
+ confirmThreadUnpin: false,
  dismissedProviderUpdateNotificationKeys: [],
  diffIgnoreWhitespace: true,
  environmentIdentificationMode: "artwork",

apps/web/src/components/ChatView.tsx

@@ -1273,7 +1273,7 @@ function ChatViewContent(props: ChatViewProps) {
  const threadSyncPhase = routeKind === "server" ? (props.threadSyncPhase ?? null) : null;
  const threadDetailLoading = threadSyncPhase === "loading";
  const handleNewThread = useNewThreadHandler();
- const { settleThread, pinThread, unpinThread } = useThreadActions();
+ const { settleThread, pinThread, confirmAndUnpinThread } = useThreadActions();
  const routeThreadRef = useMemo(
  () => scopeThreadRef(environmentId, threadId),
  [environmentId, threadId],
@@ -5146,17 +5146,19 @@ function ChatViewContent(props: ChatViewProps) {
  event.stopPropagation();
  if (!isServerThread || !activeThreadRef || !supportsPinning) return;
  const pinned = activeThreadPinned;
- void (pinned ? unpinThread(activeThreadRef) : pinThread(activeThreadRef)).then((result) => {
- if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
- const error = squashAtomCommandFailure(result);
- toastManager.add(
- stackedThreadToast({
- type: "error",
- title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
- description: error instanceof Error ? error.message : "An error occurred.",
- }),
- );
- });
+ void (pinned ? confirmAndUnpinThread(activeThreadRef) : pinThread(activeThreadRef)).then(
+ (result) => {
+ if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+ const error = squashAtomCommandFailure(result);
+ toastManager.add(
+ stackedThreadToast({
+ type: "error",
+ title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ }),
+ );
+ },
+ );
  return;
  }
 
@@ -5284,7 +5286,7 @@ function ChatViewContent(props: ChatViewProps) {
  settleThread,
  supportsPinning,
  supportsSettlement,
-unpinThread,
+confirmAndUnpinThread,
  toggleRightPanel,
  toggleRightPanelMaximized,
  toggleTerminalVisibility,

apps/web/src/components/Sidebar.tsx

@@ -1749,7 +1749,7 @@ export default function Sidebar() {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  reorderPinnedThread,
  archiveThread,
  deleteThread,
@@ -2709,7 +2709,7 @@ export default function Sidebar() {
  const attemptUnpin = useCallback(
  (threadRef: ScopedThreadRef) => {
  void (async () => {
- const result = await unpinThread(threadRef);
+ const result = await confirmAndUnpinThread(threadRef);
  if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
  const error = squashAtomCommandFailure(result);
  toastManager.add(
@@ -2722,7 +2722,7 @@ export default function Sidebar() {
  }
  })();
  },
- [unpinThread],
+ [confirmAndUnpinThread],
  );
 
  const handlePinnedDragEnd = useCallback(

apps/web/src/components/settings/SettingsPanels.tsx

@@ -526,6 +526,9 @@ export function useSettingsRestore(onRestored?: () => void) {
  ...(settings.addProjectBaseDirectory !== DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory
  ? ["Add project base directory"]
  : []),
+ ...(settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin
+ ? ["Unpin confirmation"]
+ : []),
  ...(settings.confirmThreadArchive !== DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive
  ? ["Archive confirmation"]
  : []),
@@ -554,6 +557,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  settings.confirmQuit,
  settings.confirmThreadArchive,
  settings.confirmThreadDelete,
+ settings.confirmThreadUnpin,
  settings.addProjectBaseDirectory,
  settings.defaultThreadEnvMode,
  settings.newWorktreesStartFromOrigin,
@@ -666,6 +670,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
  confirmThreadArchive: DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive,
  confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
  confirmQuit: DEFAULT_UNIFIED_SETTINGS.confirmQuit,
  textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
  fontFamilySans: DEFAULT_UNIFIED_SETTINGS.fontFamilySans,
@@ -2313,6 +2318,32 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ {...searchableSetting("unpin-confirmation")}
+ description="Ask before unpinning a thread from the pinned section."
+ resetAction={
+ settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin ? (
+ <SettingResetButton
+ label="unpin confirmation"
+ onClick={() =>
+ updateSettings({
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Switch
+ checked={settings.confirmThreadUnpin}
+ onCheckedChange={(checked) =>
+ updateSettings({ confirmThreadUnpin: Boolean(checked) })
+ }
+ aria-label="Confirm thread unpinning"
+ />
+ }
+ />
+
  <SettingsRow
  {...searchableSetting("archive-confirmation")}
  description="Require a second click on the inline archive action before a thread is archived."

apps/web/src/components/settings/settingsSearch.test.ts

@@ -56,6 +56,14 @@ describe("searchSettings", () => {
  ]);
  });
 
+ it("lists thread confirmations in panel order", () => {
+ expect(searchSettings("confirmation").map((item) => item.id)).toEqual([
+ "unpin-confirmation",
+ "archive-confirmation",
+ "delete-confirmation",
+ ]);
+ });
+
  it("returns no results for an empty query", () => {
  expect(searchSettings(" ", ITEMS)).toEqual([]);
  });

apps/web/src/components/settings/settingsSearch.ts

@@ -152,6 +152,11 @@ export const SETTINGS_SEARCH_ITEMS = [
  title: "Add project starts in",
  to: "/settings/general",
  },
+ {
+ id: "unpin-confirmation",
+ title: "Unpin confirmation",
+ to: "/settings/general",
+ },
  {
  id: "archive-confirmation",
  title: "Archive confirmation",

apps/web/src/hooks/useThreadActionMenu.ts

@@ -71,7 +71,7 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  archiveThread,
  deleteThread,
  } = useThreadActions();
@@ -215,9 +215,10 @@ export function useThreadActionMenu(input: {
  case "pin":
  await reportFailure("Failed to pin thread", () => pinThread(threadRef));
  return;
- case "unpin":
- await reportFailure("Failed to unpin thread", () => unpinThread(threadRef));
+ case "unpin": {
+ await reportFailure("Failed to unpin thread", () => confirmAndUnpinThread(threadRef));
  return;
+ }
  case "rename":
  onStartRename();
  return;
@@ -315,6 +316,7 @@ export function useThreadActionMenu(input: {
  changeRequest,
  confirmThreadArchive,
  confirmThreadDelete,
+ confirmAndUnpinThread,
  copyBranchToClipboard,
  copyPathToClipboard,
  copyThreadIdToClipboard,
@@ -328,7 +330,6 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  threadRef,
  timestampFormat,
- unpinThread,
  unsettleThread,
  unsnoozeThread,
  updateThreadMetadata,

apps/web/src/hooks/useThreadActions.test.ts

@@ -1,7 +1,7 @@
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
-import { ThreadArchiveBlockedError } from "./useThreadActions";
+import { requestThreadUnpinConfirmation, ThreadArchiveBlockedError } from "./useThreadActions";
 
 describe("ThreadArchiveBlockedError", () => {
  it("keeps the blocked thread context with the fixed message", () => {
@@ -17,3 +17,57 @@ describe("ThreadArchiveBlockedError", () => {
  expect(error.message).toBe("Cannot archive a running thread.");
  });
 });
+
+describe("requestThreadUnpinConfirmation", () => {
+ it("skips the dialog when confirmation is disabled", async () => {
+ let callCount = 0;
+ const result = await requestThreadUnpinConfirmation({
+ enabled: false,
+ title: "Pinned thread",
+ confirm: async () => {
+ callCount += 1;
+ return false;
+ },
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ expect(callCount).toBe(0);
+ });
+
+ it("degrades gracefully when dialogs are unavailable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: null,
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ });
+
+ it("uses the thread title and returns the user's decision", async () => {
+ let message = "";
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Release prep",
+ confirm: async (nextMessage) => {
+ message = nextMessage;
+ return false;
+ },
+ });
+
+ expect(message).toBe(
+ 'Unpin thread "Release prep"?\nThis will move the thread out of your pinned section.',
+ );
+ expect(result).toMatchObject({ _tag: "Success", value: false });
+ });
+
+ it("keeps dialog failures observable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: () => Promise.reject(new Error("dialog unavailable")),
+ });
+
+ expect(result._tag).toBe("Failure");
+ });
+});

apps/web/src/hooks/useThreadActions.ts

@@ -136,6 +136,26 @@ export class ThreadPinReorderUnsupportedError extends Schema.TaggedErrorClass<Th
  }
 }
 
+export async function requestThreadUnpinConfirmation(input: {
+ enabled: boolean;
+ title: string;
+ confirm: ((message: string) => Promise<boolean>) | null;
+}) {
+ const { confirm } = input;
+ if (!input.enabled || confirm === null) {
+ return AsyncResult.success(true);
+ }
+
+ return settlePromise(() =>
+ confirm(
+ [
+ `Unpin thread "${input.title}"?`,
+ "This will move the thread out of your pinned section.",
+ ].join("\n"),
+ ),
+ );
+}
+
 export function useThreadActions() {
  const closeTerminal = useAtomCommand(terminalEnvironment.close);
  const archiveThreadMutation = useAtomCommand(threadEnvironment.archive, {
@@ -177,6 +197,7 @@ export function useThreadActions() {
  });
  const sidebarThreadSortOrder = useClientSettings((settings) => settings.sidebarThreadSortOrder);
  const confirmThreadDelete = useClientSettings((settings) => settings.confirmThreadDelete);
+ const confirmThreadUnpin = useClientSettings((settings) => settings.confirmThreadUnpin);
  const clearComposerDraftForThread = useComposerDraftStore((store) => store.clearDraftThread);
  const clearProjectDraftThreadById = useComposerDraftStore(
  (store) => store.clearProjectDraftThreadById,
@@ -590,6 +611,26 @@ export function useThreadActions() {
  [unpinThreadMutation],
  );
 
+ const confirmAndUnpinThread = useCallback(
+ async (target: ScopedThreadRef) => {
+ const localApi = readLocalApi();
+ const resolved = resolveThreadTarget(target);
+ const confirmationResult = await requestThreadUnpinConfirmation({
+ enabled: confirmThreadUnpin,
+ title: resolved?.thread.title ?? "this thread",
+ confirm: localApi ? (message) => localApi.dialogs.confirm(message) : null,
+ });
+ if (confirmationResult._tag === "Failure") {
+ return confirmationResult;
+ }
+ if (!confirmationResult.value) {
+ return AsyncResult.success(undefined);
+ }
+ return unpinThread(target);
+ },
+ [confirmThreadUnpin, resolveThreadTarget, unpinThread],
+ );
+
  const reorderPinnedThread = useCallback(
  async (target: ScopedThreadRef, orderKey: string) => {
  // Callers (the sidebar drag handler) only enable dragging on
@@ -709,11 +750,13 @@ export function useThreadActions() {
  unsnoozeThread,
  pinThread,
  unpinThread,
+ confirmAndUnpinThread,
  reorderPinnedThread,
  }),
  [
  archiveThread,
  confirmAndDeleteThread,
+ confirmAndUnpinThread,
  deleteThread,
  pinThread,
  reorderPinnedThread,

docs/user/thread-sidebar.md

@@ -4,6 +4,9 @@ Pin a thread from its context menu to keep it in the pinned section above your a
 `mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of
 their project, including when you connect to more than one environment.
 
+To require confirmation before unpinning, enable **Settings → General → Unpin confirmation**. The
+confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.
+
 Pinned threads follow the auto-settle policy in **Settings → General**. Choose exactly one policy:
 settle when a pull request merges or closes, settle after a configurable period of inactivity, or
 never auto-settle. **Never** leaves every automatic path off, so threads settle only when you choose

packages/contracts/src/settings.test.ts

@@ -141,6 +141,12 @@ describe("ClientSettings sidebar", () => {
  );
  });
 
+ it("keeps unpin confirmation opt-in and patchable", () => {
+ expect(decodeClientSettings({}).confirmThreadUnpin).toBe(false);
+ expect(decodeClientSettingsPatch({ confirmThreadUnpin: true }).confirmThreadUnpin).toBe(true);
+ expect(() => decodeClientSettingsPatch({ confirmThreadUnpin: "yes" })).toThrow();
+ });
+
  it("allows auto-settle by inactivity to be disabled", () => {
  expect(
  decodeClientSettings({ sidebarAutoSettleAfterDays: null }).sidebarAutoSettleAfterDays,

packages/contracts/src/settings.ts

@@ -170,6 +170,7 @@ export const ClientSettingsSchema = Schema.Struct({
  confirmQuit: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
  confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+ confirmThreadUnpin: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
  Schema.withDecodingDefault(Effect.succeed([])),
  ),
@@ -913,6 +914,7 @@ export const ClientSettingsPatch = Schema.Struct({
  confirmQuit: Schema.optionalKey(Schema.Boolean),
  confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
  confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
+ confirmThreadUnpin: Schema.optionalKey(Schema.Boolean),
  diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
  environmentIdentificationMode: Schema.optionalKey(EnvironmentIdentificationMode),
  glassOpacity: Schema.optionalKey(GlassOpacity),

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

@@ -21,6 +21,7 @@ const clientSettings: ClientSettings = {
  confirmQuit: true,
  confirmThreadArchive: true,
  confirmThreadDelete: false,
+ confirmThreadUnpin: false,
  dismissedProviderUpdateNotificationKeys: [],
  diffIgnoreWhitespace: true,
  environmentIdentificationMode: "artwork",

apps/web/src/components/ChatView.tsx

@@ -1273,7 +1273,7 @@ function ChatViewContent(props: ChatViewProps) {
  const threadSyncPhase = routeKind === "server" ? (props.threadSyncPhase ?? null) : null;
  const threadDetailLoading = threadSyncPhase === "loading";
  const handleNewThread = useNewThreadHandler();
- const { settleThread, pinThread, unpinThread } = useThreadActions();
+ const { settleThread, pinThread, confirmAndUnpinThread } = useThreadActions();
  const routeThreadRef = useMemo(
  () => scopeThreadRef(environmentId, threadId),
  [environmentId, threadId],
@@ -5146,17 +5146,19 @@ function ChatViewContent(props: ChatViewProps) {
  event.stopPropagation();
  if (!isServerThread || !activeThreadRef || !supportsPinning) return;
  const pinned = activeThreadPinned;
- void (pinned ? unpinThread(activeThreadRef) : pinThread(activeThreadRef)).then((result) => {
- if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
- const error = squashAtomCommandFailure(result);
- toastManager.add(
- stackedThreadToast({
- type: "error",
- title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
- description: error instanceof Error ? error.message : "An error occurred.",
- }),
- );
- });
+ void (pinned ? confirmAndUnpinThread(activeThreadRef) : pinThread(activeThreadRef)).then(
+ (result) => {
+ if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+ const error = squashAtomCommandFailure(result);
+ toastManager.add(
+ stackedThreadToast({
+ type: "error",
+ title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ }),
+ );
+ },
+ );
  return;
  }
 
@@ -5284,7 +5286,7 @@ function ChatViewContent(props: ChatViewProps) {
  settleThread,
  supportsPinning,
  supportsSettlement,
-unpinThread,
+confirmAndUnpinThread,
  toggleRightPanel,
  toggleRightPanelMaximized,
  toggleTerminalVisibility,

apps/web/src/components/Sidebar.tsx

@@ -1749,7 +1749,7 @@ export default function Sidebar() {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  reorderPinnedThread,
  archiveThread,
  deleteThread,
@@ -2709,7 +2709,7 @@ export default function Sidebar() {
  const attemptUnpin = useCallback(
  (threadRef: ScopedThreadRef) => {
  void (async () => {
- const result = await unpinThread(threadRef);
+ const result = await confirmAndUnpinThread(threadRef);
  if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
  const error = squashAtomCommandFailure(result);
  toastManager.add(
@@ -2722,7 +2722,7 @@ export default function Sidebar() {
  }
  })();
  },
- [unpinThread],
+ [confirmAndUnpinThread],
  );
 
  const handlePinnedDragEnd = useCallback(

apps/web/src/components/settings/SettingsPanels.tsx

@@ -526,6 +526,9 @@ export function useSettingsRestore(onRestored?: () => void) {
  ...(settings.addProjectBaseDirectory !== DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory
  ? ["Add project base directory"]
  : []),
+ ...(settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin
+ ? ["Unpin confirmation"]
+ : []),
  ...(settings.confirmThreadArchive !== DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive
  ? ["Archive confirmation"]
  : []),
@@ -554,6 +557,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  settings.confirmQuit,
  settings.confirmThreadArchive,
  settings.confirmThreadDelete,
+ settings.confirmThreadUnpin,
  settings.addProjectBaseDirectory,
  settings.defaultThreadEnvMode,
  settings.newWorktreesStartFromOrigin,
@@ -666,6 +670,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
  confirmThreadArchive: DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive,
  confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
  confirmQuit: DEFAULT_UNIFIED_SETTINGS.confirmQuit,
  textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
  fontFamilySans: DEFAULT_UNIFIED_SETTINGS.fontFamilySans,
@@ -2313,6 +2318,32 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ {...searchableSetting("unpin-confirmation")}
+ description="Ask before unpinning a thread from the pinned section."
+ resetAction={
+ settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin ? (
+ <SettingResetButton
+ label="unpin confirmation"
+ onClick={() =>
+ updateSettings({
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Switch
+ checked={settings.confirmThreadUnpin}
+ onCheckedChange={(checked) =>
+ updateSettings({ confirmThreadUnpin: Boolean(checked) })
+ }
+ aria-label="Confirm thread unpinning"
+ />
+ }
+ />
+
  <SettingsRow
  {...searchableSetting("archive-confirmation")}
  description="Require a second click on the inline archive action before a thread is archived."

apps/web/src/components/settings/settingsSearch.test.ts

@@ -56,6 +56,14 @@ describe("searchSettings", () => {
  ]);
  });
 
+ it("lists thread confirmations in panel order", () => {
+ expect(searchSettings("confirmation").map((item) => item.id)).toEqual([
+ "unpin-confirmation",
+ "archive-confirmation",
+ "delete-confirmation",
+ ]);
+ });
+
  it("returns no results for an empty query", () => {
  expect(searchSettings(" ", ITEMS)).toEqual([]);
  });

apps/web/src/components/settings/settingsSearch.ts

@@ -152,6 +152,11 @@ export const SETTINGS_SEARCH_ITEMS = [
  title: "Add project starts in",
  to: "/settings/general",
  },
+ {
+ id: "unpin-confirmation",
+ title: "Unpin confirmation",
+ to: "/settings/general",
+ },
  {
  id: "archive-confirmation",
  title: "Archive confirmation",

apps/web/src/hooks/useThreadActionMenu.ts

@@ -71,7 +71,7 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  archiveThread,
  deleteThread,
  } = useThreadActions();
@@ -215,9 +215,10 @@ export function useThreadActionMenu(input: {
  case "pin":
  await reportFailure("Failed to pin thread", () => pinThread(threadRef));
  return;
- case "unpin":
- await reportFailure("Failed to unpin thread", () => unpinThread(threadRef));
+ case "unpin": {
+ await reportFailure("Failed to unpin thread", () => confirmAndUnpinThread(threadRef));
  return;
+ }
  case "rename":
  onStartRename();
  return;
@@ -315,6 +316,7 @@ export function useThreadActionMenu(input: {
  changeRequest,
  confirmThreadArchive,
  confirmThreadDelete,
+ confirmAndUnpinThread,
  copyBranchToClipboard,
  copyPathToClipboard,
  copyThreadIdToClipboard,
@@ -328,7 +330,6 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  threadRef,
  timestampFormat,
- unpinThread,
  unsettleThread,
  unsnoozeThread,
  updateThreadMetadata,

apps/web/src/hooks/useThreadActions.test.ts

@@ -1,7 +1,7 @@
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
-import { ThreadArchiveBlockedError } from "./useThreadActions";
+import { requestThreadUnpinConfirmation, ThreadArchiveBlockedError } from "./useThreadActions";
 
 describe("ThreadArchiveBlockedError", () => {
  it("keeps the blocked thread context with the fixed message", () => {
@@ -17,3 +17,57 @@ describe("ThreadArchiveBlockedError", () => {
  expect(error.message).toBe("Cannot archive a running thread.");
  });
 });
+
+describe("requestThreadUnpinConfirmation", () => {
+ it("skips the dialog when confirmation is disabled", async () => {
+ let callCount = 0;
+ const result = await requestThreadUnpinConfirmation({
+ enabled: false,
+ title: "Pinned thread",
+ confirm: async () => {
+ callCount += 1;
+ return false;
+ },
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ expect(callCount).toBe(0);
+ });
+
+ it("degrades gracefully when dialogs are unavailable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: null,
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ });
+
+ it("uses the thread title and returns the user's decision", async () => {
+ let message = "";
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Release prep",
+ confirm: async (nextMessage) => {
+ message = nextMessage;
+ return false;
+ },
+ });
+
+ expect(message).toBe(
+ 'Unpin thread "Release prep"?\nThis will move the thread out of your pinned section.',
+ );
+ expect(result).toMatchObject({ _tag: "Success", value: false });
+ });
+
+ it("keeps dialog failures observable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: () => Promise.reject(new Error("dialog unavailable")),
+ });
+
+ expect(result._tag).toBe("Failure");
+ });
+});

apps/web/src/hooks/useThreadActions.ts

@@ -136,6 +136,26 @@ export class ThreadPinReorderUnsupportedError extends Schema.TaggedErrorClass<Th
  }
 }
 
+export async function requestThreadUnpinConfirmation(input: {
+ enabled: boolean;
+ title: string;
+ confirm: ((message: string) => Promise<boolean>) | null;
+}) {
+ const { confirm } = input;
+ if (!input.enabled || confirm === null) {
+ return AsyncResult.success(true);
+ }
+
+ return settlePromise(() =>
+ confirm(
+ [
+ `Unpin thread "${input.title}"?`,
+ "This will move the thread out of your pinned section.",
+ ].join("\n"),
+ ),
+ );
+}
+
 export function useThreadActions() {
  const closeTerminal = useAtomCommand(terminalEnvironment.close);
  const archiveThreadMutation = useAtomCommand(threadEnvironment.archive, {
@@ -177,6 +197,7 @@ export function useThreadActions() {
  });
  const sidebarThreadSortOrder = useClientSettings((settings) => settings.sidebarThreadSortOrder);
  const confirmThreadDelete = useClientSettings((settings) => settings.confirmThreadDelete);
+ const confirmThreadUnpin = useClientSettings((settings) => settings.confirmThreadUnpin);
  const clearComposerDraftForThread = useComposerDraftStore((store) => store.clearDraftThread);
  const clearProjectDraftThreadById = useComposerDraftStore(
  (store) => store.clearProjectDraftThreadById,
@@ -590,6 +611,26 @@ export function useThreadActions() {
  [unpinThreadMutation],
  );
 
+ const confirmAndUnpinThread = useCallback(
+ async (target: ScopedThreadRef) => {
+ const localApi = readLocalApi();
+ const resolved = resolveThreadTarget(target);
+ const confirmationResult = await requestThreadUnpinConfirmation({
+ enabled: confirmThreadUnpin,
+ title: resolved?.thread.title ?? "this thread",
+ confirm: localApi ? (message) => localApi.dialogs.confirm(message) : null,
+ });
+ if (confirmationResult._tag === "Failure") {
+ return confirmationResult;
+ }
+ if (!confirmationResult.value) {
+ return AsyncResult.success(undefined);
+ }
+ return unpinThread(target);
+ },
+ [confirmThreadUnpin, resolveThreadTarget, unpinThread],
+ );
+
  const reorderPinnedThread = useCallback(
  async (target: ScopedThreadRef, orderKey: string) => {
  // Callers (the sidebar drag handler) only enable dragging on
@@ -709,11 +750,13 @@ export function useThreadActions() {
  unsnoozeThread,
  pinThread,
  unpinThread,
+ confirmAndUnpinThread,
  reorderPinnedThread,
  }),
  [
  archiveThread,
  confirmAndDeleteThread,
+ confirmAndUnpinThread,
  deleteThread,
  pinThread,
  reorderPinnedThread,

docs/user/thread-sidebar.md

@@ -4,6 +4,9 @@ Pin a thread from its context menu to keep it in the pinned section above your a
 `mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of
 their project, including when you connect to more than one environment.
 
+To require confirmation before unpinning, enable **Settings → General → Unpin confirmation**. The
+confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.
+
 Pinned threads follow the auto-settle policy in **Settings → General**. Choose exactly one policy:
 settle when a pull request merges or closes, settle after a configurable period of inactivity, or
 never auto-settle. **Never** leaves every automatic path off, so threads settle only when you choose

packages/contracts/src/settings.test.ts

@@ -141,6 +141,12 @@ describe("ClientSettings sidebar", () => {
  );
  });
 
+ it("keeps unpin confirmation opt-in and patchable", () => {
+ expect(decodeClientSettings({}).confirmThreadUnpin).toBe(false);
+ expect(decodeClientSettingsPatch({ confirmThreadUnpin: true }).confirmThreadUnpin).toBe(true);
+ expect(() => decodeClientSettingsPatch({ confirmThreadUnpin: "yes" })).toThrow();
+ });
+
  it("allows auto-settle by inactivity to be disabled", () => {
  expect(
  decodeClientSettings({ sidebarAutoSettleAfterDays: null }).sidebarAutoSettleAfterDays,

packages/contracts/src/settings.ts

@@ -170,6 +170,7 @@ export const ClientSettingsSchema = Schema.Struct({
  confirmQuit: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
  confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+ confirmThreadUnpin: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
  Schema.withDecodingDefault(Effect.succeed([])),
  ),
@@ -913,6 +914,7 @@ export const ClientSettingsPatch = Schema.Struct({
  confirmQuit: Schema.optionalKey(Schema.Boolean),
  confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
  confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
+ confirmThreadUnpin: Schema.optionalKey(Schema.Boolean),
  diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
  environmentIdentificationMode: Schema.optionalKey(EnvironmentIdentificationMode),
  glassOpacity: Schema.optionalKey(GlassOpacity),

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

@@ -21,6 +21,7 @@ const clientSettings: ClientSettings = {
  confirmQuit: true,
  confirmThreadArchive: true,
  confirmThreadDelete: false,
+ confirmThreadUnpin: false,
  dismissedProviderUpdateNotificationKeys: [],
  diffIgnoreWhitespace: true,
  environmentIdentificationMode: "artwork",

apps/web/src/components/ChatView.tsx

@@ -1273,7 +1273,7 @@ function ChatViewContent(props: ChatViewProps) {
  const threadSyncPhase = routeKind === "server" ? (props.threadSyncPhase ?? null) : null;
  const threadDetailLoading = threadSyncPhase === "loading";
  const handleNewThread = useNewThreadHandler();
- const { settleThread, pinThread, unpinThread } = useThreadActions();
+ const { settleThread, pinThread, confirmAndUnpinThread } = useThreadActions();
  const routeThreadRef = useMemo(
  () => scopeThreadRef(environmentId, threadId),
  [environmentId, threadId],
@@ -5146,17 +5146,19 @@ function ChatViewContent(props: ChatViewProps) {
  event.stopPropagation();
  if (!isServerThread || !activeThreadRef || !supportsPinning) return;
  const pinned = activeThreadPinned;
- void (pinned ? unpinThread(activeThreadRef) : pinThread(activeThreadRef)).then((result) => {
- if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
- const error = squashAtomCommandFailure(result);
- toastManager.add(
- stackedThreadToast({
- type: "error",
- title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
- description: error instanceof Error ? error.message : "An error occurred.",
- }),
- );
- });
+ void (pinned ? confirmAndUnpinThread(activeThreadRef) : pinThread(activeThreadRef)).then(
+ (result) => {
+ if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+ const error = squashAtomCommandFailure(result);
+ toastManager.add(
+ stackedThreadToast({
+ type: "error",
+ title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ }),
+ );
+ },
+ );
  return;
  }
 
@@ -5284,7 +5286,7 @@ function ChatViewContent(props: ChatViewProps) {
  settleThread,
  supportsPinning,
  supportsSettlement,
-unpinThread,
+confirmAndUnpinThread,
  toggleRightPanel,
  toggleRightPanelMaximized,
  toggleTerminalVisibility,

apps/web/src/components/Sidebar.tsx

@@ -1749,7 +1749,7 @@ export default function Sidebar() {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  reorderPinnedThread,
  archiveThread,
  deleteThread,
@@ -2709,7 +2709,7 @@ export default function Sidebar() {
  const attemptUnpin = useCallback(
  (threadRef: ScopedThreadRef) => {
  void (async () => {
- const result = await unpinThread(threadRef);
+ const result = await confirmAndUnpinThread(threadRef);
  if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
  const error = squashAtomCommandFailure(result);
  toastManager.add(
@@ -2722,7 +2722,7 @@ export default function Sidebar() {
  }
  })();
  },
- [unpinThread],
+ [confirmAndUnpinThread],
  );
 
  const handlePinnedDragEnd = useCallback(

apps/web/src/components/settings/SettingsPanels.tsx

@@ -526,6 +526,9 @@ export function useSettingsRestore(onRestored?: () => void) {
  ...(settings.addProjectBaseDirectory !== DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory
  ? ["Add project base directory"]
  : []),
+ ...(settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin
+ ? ["Unpin confirmation"]
+ : []),
  ...(settings.confirmThreadArchive !== DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive
  ? ["Archive confirmation"]
  : []),
@@ -554,6 +557,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  settings.confirmQuit,
  settings.confirmThreadArchive,
  settings.confirmThreadDelete,
+ settings.confirmThreadUnpin,
  settings.addProjectBaseDirectory,
  settings.defaultThreadEnvMode,
  settings.newWorktreesStartFromOrigin,
@@ -666,6 +670,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
  confirmThreadArchive: DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive,
  confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
  confirmQuit: DEFAULT_UNIFIED_SETTINGS.confirmQuit,
  textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
  fontFamilySans: DEFAULT_UNIFIED_SETTINGS.fontFamilySans,
@@ -2313,6 +2318,32 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ {...searchableSetting("unpin-confirmation")}
+ description="Ask before unpinning a thread from the pinned section."
+ resetAction={
+ settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin ? (
+ <SettingResetButton
+ label="unpin confirmation"
+ onClick={() =>
+ updateSettings({
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Switch
+ checked={settings.confirmThreadUnpin}
+ onCheckedChange={(checked) =>
+ updateSettings({ confirmThreadUnpin: Boolean(checked) })
+ }
+ aria-label="Confirm thread unpinning"
+ />
+ }
+ />
+
  <SettingsRow
  {...searchableSetting("archive-confirmation")}
  description="Require a second click on the inline archive action before a thread is archived."

apps/web/src/components/settings/settingsSearch.test.ts

@@ -56,6 +56,14 @@ describe("searchSettings", () => {
  ]);
  });
 
+ it("lists thread confirmations in panel order", () => {
+ expect(searchSettings("confirmation").map((item) => item.id)).toEqual([
+ "unpin-confirmation",
+ "archive-confirmation",
+ "delete-confirmation",
+ ]);
+ });
+
  it("returns no results for an empty query", () => {
  expect(searchSettings(" ", ITEMS)).toEqual([]);
  });

apps/web/src/components/settings/settingsSearch.ts

@@ -152,6 +152,11 @@ export const SETTINGS_SEARCH_ITEMS = [
  title: "Add project starts in",
  to: "/settings/general",
  },
+ {
+ id: "unpin-confirmation",
+ title: "Unpin confirmation",
+ to: "/settings/general",
+ },
  {
  id: "archive-confirmation",
  title: "Archive confirmation",

apps/web/src/hooks/useThreadActionMenu.ts

@@ -71,7 +71,7 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  archiveThread,
  deleteThread,
  } = useThreadActions();
@@ -215,9 +215,10 @@ export function useThreadActionMenu(input: {
  case "pin":
  await reportFailure("Failed to pin thread", () => pinThread(threadRef));
  return;
- case "unpin":
- await reportFailure("Failed to unpin thread", () => unpinThread(threadRef));
+ case "unpin": {
+ await reportFailure("Failed to unpin thread", () => confirmAndUnpinThread(threadRef));
  return;
+ }
  case "rename":
  onStartRename();
  return;
@@ -315,6 +316,7 @@ export function useThreadActionMenu(input: {
  changeRequest,
  confirmThreadArchive,
  confirmThreadDelete,
+ confirmAndUnpinThread,
  copyBranchToClipboard,
  copyPathToClipboard,
  copyThreadIdToClipboard,
@@ -328,7 +330,6 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  threadRef,
  timestampFormat,
- unpinThread,
  unsettleThread,
  unsnoozeThread,
  updateThreadMetadata,

apps/web/src/hooks/useThreadActions.test.ts

@@ -1,7 +1,7 @@
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
-import { ThreadArchiveBlockedError } from "./useThreadActions";
+import { requestThreadUnpinConfirmation, ThreadArchiveBlockedError } from "./useThreadActions";
 
 describe("ThreadArchiveBlockedError", () => {
  it("keeps the blocked thread context with the fixed message", () => {
@@ -17,3 +17,57 @@ describe("ThreadArchiveBlockedError", () => {
  expect(error.message).toBe("Cannot archive a running thread.");
  });
 });
+
+describe("requestThreadUnpinConfirmation", () => {
+ it("skips the dialog when confirmation is disabled", async () => {
+ let callCount = 0;
+ const result = await requestThreadUnpinConfirmation({
+ enabled: false,
+ title: "Pinned thread",
+ confirm: async () => {
+ callCount += 1;
+ return false;
+ },
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ expect(callCount).toBe(0);
+ });
+
+ it("degrades gracefully when dialogs are unavailable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: null,
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ });
+
+ it("uses the thread title and returns the user's decision", async () => {
+ let message = "";
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Release prep",
+ confirm: async (nextMessage) => {
+ message = nextMessage;
+ return false;
+ },
+ });
+
+ expect(message).toBe(
+ 'Unpin thread "Release prep"?\nThis will move the thread out of your pinned section.',
+ );
+ expect(result).toMatchObject({ _tag: "Success", value: false });
+ });
+
+ it("keeps dialog failures observable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: () => Promise.reject(new Error("dialog unavailable")),
+ });
+
+ expect(result._tag).toBe("Failure");
+ });
+});

apps/web/src/hooks/useThreadActions.ts

@@ -136,6 +136,26 @@ export class ThreadPinReorderUnsupportedError extends Schema.TaggedErrorClass<Th
  }
 }
 
+export async function requestThreadUnpinConfirmation(input: {
+ enabled: boolean;
+ title: string;
+ confirm: ((message: string) => Promise<boolean>) | null;
+}) {
+ const { confirm } = input;
+ if (!input.enabled || confirm === null) {
+ return AsyncResult.success(true);
+ }
+
+ return settlePromise(() =>
+ confirm(
+ [
+ `Unpin thread "${input.title}"?`,
+ "This will move the thread out of your pinned section.",
+ ].join("\n"),
+ ),
+ );
+}
+
 export function useThreadActions() {
  const closeTerminal = useAtomCommand(terminalEnvironment.close);
  const archiveThreadMutation = useAtomCommand(threadEnvironment.archive, {
@@ -177,6 +197,7 @@ export function useThreadActions() {
  });
  const sidebarThreadSortOrder = useClientSettings((settings) => settings.sidebarThreadSortOrder);
  const confirmThreadDelete = useClientSettings((settings) => settings.confirmThreadDelete);
+ const confirmThreadUnpin = useClientSettings((settings) => settings.confirmThreadUnpin);
  const clearComposerDraftForThread = useComposerDraftStore((store) => store.clearDraftThread);
  const clearProjectDraftThreadById = useComposerDraftStore(
  (store) => store.clearProjectDraftThreadById,
@@ -590,6 +611,26 @@ export function useThreadActions() {
  [unpinThreadMutation],
  );
 
+ const confirmAndUnpinThread = useCallback(
+ async (target: ScopedThreadRef) => {
+ const localApi = readLocalApi();
+ const resolved = resolveThreadTarget(target);
+ const confirmationResult = await requestThreadUnpinConfirmation({
+ enabled: confirmThreadUnpin,
+ title: resolved?.thread.title ?? "this thread",
+ confirm: localApi ? (message) => localApi.dialogs.confirm(message) : null,
+ });
+ if (confirmationResult._tag === "Failure") {
+ return confirmationResult;
+ }
+ if (!confirmationResult.value) {
+ return AsyncResult.success(undefined);
+ }
+ return unpinThread(target);
+ },
+ [confirmThreadUnpin, resolveThreadTarget, unpinThread],
+ );
+
  const reorderPinnedThread = useCallback(
  async (target: ScopedThreadRef, orderKey: string) => {
  // Callers (the sidebar drag handler) only enable dragging on
@@ -709,11 +750,13 @@ export function useThreadActions() {
  unsnoozeThread,
  pinThread,
  unpinThread,
+ confirmAndUnpinThread,
  reorderPinnedThread,
  }),
  [
  archiveThread,
  confirmAndDeleteThread,
+ confirmAndUnpinThread,
  deleteThread,
  pinThread,
  reorderPinnedThread,

docs/user/thread-sidebar.md

@@ -4,6 +4,9 @@ Pin a thread from its context menu to keep it in the pinned section above your a
 `mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of
 their project, including when you connect to more than one environment.
 
+To require confirmation before unpinning, enable **Settings → General → Unpin confirmation**. The
+confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.
+
 Pinned threads follow the auto-settle policy in **Settings → General**. Choose exactly one policy:
 settle when a pull request merges or closes, settle after a configurable period of inactivity, or
 never auto-settle. **Never** leaves every automatic path off, so threads settle only when you choose

packages/contracts/src/settings.test.ts

@@ -141,6 +141,12 @@ describe("ClientSettings sidebar", () => {
  );
  });
 
+ it("keeps unpin confirmation opt-in and patchable", () => {
+ expect(decodeClientSettings({}).confirmThreadUnpin).toBe(false);
+ expect(decodeClientSettingsPatch({ confirmThreadUnpin: true }).confirmThreadUnpin).toBe(true);
+ expect(() => decodeClientSettingsPatch({ confirmThreadUnpin: "yes" })).toThrow();
+ });
+
  it("allows auto-settle by inactivity to be disabled", () => {
  expect(
  decodeClientSettings({ sidebarAutoSettleAfterDays: null }).sidebarAutoSettleAfterDays,

packages/contracts/src/settings.ts

@@ -170,6 +170,7 @@ export const ClientSettingsSchema = Schema.Struct({
  confirmQuit: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
  confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+ confirmThreadUnpin: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
  Schema.withDecodingDefault(Effect.succeed([])),
  ),
@@ -913,6 +914,7 @@ export const ClientSettingsPatch = Schema.Struct({
  confirmQuit: Schema.optionalKey(Schema.Boolean),
  confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
  confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
+ confirmThreadUnpin: Schema.optionalKey(Schema.Boolean),
  diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
  environmentIdentificationMode: Schema.optionalKey(EnvironmentIdentificationMode),
  glassOpacity: Schema.optionalKey(GlassOpacity),

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

@@ -21,6 +21,7 @@ const clientSettings: ClientSettings = {
  confirmQuit: true,
  confirmThreadArchive: true,
  confirmThreadDelete: false,
+ confirmThreadUnpin: false,
  dismissedProviderUpdateNotificationKeys: [],
  diffIgnoreWhitespace: true,
  environmentIdentificationMode: "artwork",

apps/web/src/components/ChatView.tsx

@@ -1273,7 +1273,7 @@ function ChatViewContent(props: ChatViewProps) {
  const threadSyncPhase = routeKind === "server" ? (props.threadSyncPhase ?? null) : null;
  const threadDetailLoading = threadSyncPhase === "loading";
  const handleNewThread = useNewThreadHandler();
- const { settleThread, pinThread, unpinThread } = useThreadActions();
+ const { settleThread, pinThread, confirmAndUnpinThread } = useThreadActions();
  const routeThreadRef = useMemo(
  () => scopeThreadRef(environmentId, threadId),
  [environmentId, threadId],
@@ -5146,17 +5146,19 @@ function ChatViewContent(props: ChatViewProps) {
  event.stopPropagation();
  if (!isServerThread || !activeThreadRef || !supportsPinning) return;
  const pinned = activeThreadPinned;
- void (pinned ? unpinThread(activeThreadRef) : pinThread(activeThreadRef)).then((result) => {
- if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
- const error = squashAtomCommandFailure(result);
- toastManager.add(
- stackedThreadToast({
- type: "error",
- title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
- description: error instanceof Error ? error.message : "An error occurred.",
- }),
- );
- });
+ void (pinned ? confirmAndUnpinThread(activeThreadRef) : pinThread(activeThreadRef)).then(
+ (result) => {
+ if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+ const error = squashAtomCommandFailure(result);
+ toastManager.add(
+ stackedThreadToast({
+ type: "error",
+ title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ }),
+ );
+ },
+ );
  return;
  }
 
@@ -5284,7 +5286,7 @@ function ChatViewContent(props: ChatViewProps) {
  settleThread,
  supportsPinning,
  supportsSettlement,
-unpinThread,
+confirmAndUnpinThread,
  toggleRightPanel,
  toggleRightPanelMaximized,
  toggleTerminalVisibility,

apps/web/src/components/Sidebar.tsx

@@ -1749,7 +1749,7 @@ export default function Sidebar() {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  reorderPinnedThread,
  archiveThread,
  deleteThread,
@@ -2709,7 +2709,7 @@ export default function Sidebar() {
  const attemptUnpin = useCallback(
  (threadRef: ScopedThreadRef) => {
  void (async () => {
- const result = await unpinThread(threadRef);
+ const result = await confirmAndUnpinThread(threadRef);
  if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
  const error = squashAtomCommandFailure(result);
  toastManager.add(
@@ -2722,7 +2722,7 @@ export default function Sidebar() {
  }
  })();
  },
- [unpinThread],
+ [confirmAndUnpinThread],
  );
 
  const handlePinnedDragEnd = useCallback(

apps/web/src/components/settings/SettingsPanels.tsx

@@ -526,6 +526,9 @@ export function useSettingsRestore(onRestored?: () => void) {
  ...(settings.addProjectBaseDirectory !== DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory
  ? ["Add project base directory"]
  : []),
+ ...(settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin
+ ? ["Unpin confirmation"]
+ : []),
  ...(settings.confirmThreadArchive !== DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive
  ? ["Archive confirmation"]
  : []),
@@ -554,6 +557,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  settings.confirmQuit,
  settings.confirmThreadArchive,
  settings.confirmThreadDelete,
+ settings.confirmThreadUnpin,
  settings.addProjectBaseDirectory,
  settings.defaultThreadEnvMode,
  settings.newWorktreesStartFromOrigin,
@@ -666,6 +670,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
  confirmThreadArchive: DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive,
  confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
  confirmQuit: DEFAULT_UNIFIED_SETTINGS.confirmQuit,
  textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
  fontFamilySans: DEFAULT_UNIFIED_SETTINGS.fontFamilySans,
@@ -2313,6 +2318,32 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ {...searchableSetting("unpin-confirmation")}
+ description="Ask before unpinning a thread from the pinned section."
+ resetAction={
+ settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin ? (
+ <SettingResetButton
+ label="unpin confirmation"
+ onClick={() =>
+ updateSettings({
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Switch
+ checked={settings.confirmThreadUnpin}
+ onCheckedChange={(checked) =>
+ updateSettings({ confirmThreadUnpin: Boolean(checked) })
+ }
+ aria-label="Confirm thread unpinning"
+ />
+ }
+ />
+
  <SettingsRow
  {...searchableSetting("archive-confirmation")}
  description="Require a second click on the inline archive action before a thread is archived."

apps/web/src/components/settings/settingsSearch.test.ts

@@ -56,6 +56,14 @@ describe("searchSettings", () => {
  ]);
  });
 
+ it("lists thread confirmations in panel order", () => {
+ expect(searchSettings("confirmation").map((item) => item.id)).toEqual([
+ "unpin-confirmation",
+ "archive-confirmation",
+ "delete-confirmation",
+ ]);
+ });
+
  it("returns no results for an empty query", () => {
  expect(searchSettings(" ", ITEMS)).toEqual([]);
  });

apps/web/src/components/settings/settingsSearch.ts

@@ -152,6 +152,11 @@ export const SETTINGS_SEARCH_ITEMS = [
  title: "Add project starts in",
  to: "/settings/general",
  },
+ {
+ id: "unpin-confirmation",
+ title: "Unpin confirmation",
+ to: "/settings/general",
+ },
  {
  id: "archive-confirmation",
  title: "Archive confirmation",

apps/web/src/hooks/useThreadActionMenu.ts

@@ -71,7 +71,7 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  archiveThread,
  deleteThread,
  } = useThreadActions();
@@ -215,9 +215,10 @@ export function useThreadActionMenu(input: {
  case "pin":
  await reportFailure("Failed to pin thread", () => pinThread(threadRef));
  return;
- case "unpin":
- await reportFailure("Failed to unpin thread", () => unpinThread(threadRef));
+ case "unpin": {
+ await reportFailure("Failed to unpin thread", () => confirmAndUnpinThread(threadRef));
  return;
+ }
  case "rename":
  onStartRename();
  return;
@@ -315,6 +316,7 @@ export function useThreadActionMenu(input: {
  changeRequest,
  confirmThreadArchive,
  confirmThreadDelete,
+ confirmAndUnpinThread,
  copyBranchToClipboard,
  copyPathToClipboard,
  copyThreadIdToClipboard,
@@ -328,7 +330,6 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  threadRef,
  timestampFormat,
- unpinThread,
  unsettleThread,
  unsnoozeThread,
  updateThreadMetadata,

apps/web/src/hooks/useThreadActions.test.ts

@@ -1,7 +1,7 @@
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
-import { ThreadArchiveBlockedError } from "./useThreadActions";
+import { requestThreadUnpinConfirmation, ThreadArchiveBlockedError } from "./useThreadActions";
 
 describe("ThreadArchiveBlockedError", () => {
  it("keeps the blocked thread context with the fixed message", () => {
@@ -17,3 +17,57 @@ describe("ThreadArchiveBlockedError", () => {
  expect(error.message).toBe("Cannot archive a running thread.");
  });
 });
+
+describe("requestThreadUnpinConfirmation", () => {
+ it("skips the dialog when confirmation is disabled", async () => {
+ let callCount = 0;
+ const result = await requestThreadUnpinConfirmation({
+ enabled: false,
+ title: "Pinned thread",
+ confirm: async () => {
+ callCount += 1;
+ return false;
+ },
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ expect(callCount).toBe(0);
+ });
+
+ it("degrades gracefully when dialogs are unavailable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: null,
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ });
+
+ it("uses the thread title and returns the user's decision", async () => {
+ let message = "";
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Release prep",
+ confirm: async (nextMessage) => {
+ message = nextMessage;
+ return false;
+ },
+ });
+
+ expect(message).toBe(
+ 'Unpin thread "Release prep"?\nThis will move the thread out of your pinned section.',
+ );
+ expect(result).toMatchObject({ _tag: "Success", value: false });
+ });
+
+ it("keeps dialog failures observable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: () => Promise.reject(new Error("dialog unavailable")),
+ });
+
+ expect(result._tag).toBe("Failure");
+ });
+});

apps/web/src/hooks/useThreadActions.ts

@@ -136,6 +136,26 @@ export class ThreadPinReorderUnsupportedError extends Schema.TaggedErrorClass<Th
  }
 }
 
+export async function requestThreadUnpinConfirmation(input: {
+ enabled: boolean;
+ title: string;
+ confirm: ((message: string) => Promise<boolean>) | null;
+}) {
+ const { confirm } = input;
+ if (!input.enabled || confirm === null) {
+ return AsyncResult.success(true);
+ }
+
+ return settlePromise(() =>
+ confirm(
+ [
+ `Unpin thread "${input.title}"?`,
+ "This will move the thread out of your pinned section.",
+ ].join("\n"),
+ ),
+ );
+}
+
 export function useThreadActions() {
  const closeTerminal = useAtomCommand(terminalEnvironment.close);
  const archiveThreadMutation = useAtomCommand(threadEnvironment.archive, {
@@ -177,6 +197,7 @@ export function useThreadActions() {
  });
  const sidebarThreadSortOrder = useClientSettings((settings) => settings.sidebarThreadSortOrder);
  const confirmThreadDelete = useClientSettings((settings) => settings.confirmThreadDelete);
+ const confirmThreadUnpin = useClientSettings((settings) => settings.confirmThreadUnpin);
  const clearComposerDraftForThread = useComposerDraftStore((store) => store.clearDraftThread);
  const clearProjectDraftThreadById = useComposerDraftStore(
  (store) => store.clearProjectDraftThreadById,
@@ -590,6 +611,26 @@ export function useThreadActions() {
  [unpinThreadMutation],
  );
 
+ const confirmAndUnpinThread = useCallback(
+ async (target: ScopedThreadRef) => {
+ const localApi = readLocalApi();
+ const resolved = resolveThreadTarget(target);
+ const confirmationResult = await requestThreadUnpinConfirmation({
+ enabled: confirmThreadUnpin,
+ title: resolved?.thread.title ?? "this thread",
+ confirm: localApi ? (message) => localApi.dialogs.confirm(message) : null,
+ });
+ if (confirmationResult._tag === "Failure") {
+ return confirmationResult;
+ }
+ if (!confirmationResult.value) {
+ return AsyncResult.success(undefined);
+ }
+ return unpinThread(target);
+ },
+ [confirmThreadUnpin, resolveThreadTarget, unpinThread],
+ );
+
  const reorderPinnedThread = useCallback(
  async (target: ScopedThreadRef, orderKey: string) => {
  // Callers (the sidebar drag handler) only enable dragging on
@@ -709,11 +750,13 @@ export function useThreadActions() {
  unsnoozeThread,
  pinThread,
  unpinThread,
+ confirmAndUnpinThread,
  reorderPinnedThread,
  }),
  [
  archiveThread,
  confirmAndDeleteThread,
+ confirmAndUnpinThread,
  deleteThread,
  pinThread,
  reorderPinnedThread,

docs/user/thread-sidebar.md

@@ -4,6 +4,9 @@ Pin a thread from its context menu to keep it in the pinned section above your a
 `mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of
 their project, including when you connect to more than one environment.
 
+To require confirmation before unpinning, enable **Settings → General → Unpin confirmation**. The
+confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.
+
 Pinned threads follow the auto-settle policy in **Settings → General**. Choose exactly one policy:
 settle when a pull request merges or closes, settle after a configurable period of inactivity, or
 never auto-settle. **Never** leaves every automatic path off, so threads settle only when you choose

packages/contracts/src/settings.test.ts

@@ -141,6 +141,12 @@ describe("ClientSettings sidebar", () => {
  );
  });
 
+ it("keeps unpin confirmation opt-in and patchable", () => {
+ expect(decodeClientSettings({}).confirmThreadUnpin).toBe(false);
+ expect(decodeClientSettingsPatch({ confirmThreadUnpin: true }).confirmThreadUnpin).toBe(true);
+ expect(() => decodeClientSettingsPatch({ confirmThreadUnpin: "yes" })).toThrow();
+ });
+
  it("allows auto-settle by inactivity to be disabled", () => {
  expect(
  decodeClientSettings({ sidebarAutoSettleAfterDays: null }).sidebarAutoSettleAfterDays,

packages/contracts/src/settings.ts

@@ -170,6 +170,7 @@ export const ClientSettingsSchema = Schema.Struct({
  confirmQuit: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
  confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+ confirmThreadUnpin: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
  Schema.withDecodingDefault(Effect.succeed([])),
  ),
@@ -913,6 +914,7 @@ export const ClientSettingsPatch = Schema.Struct({
  confirmQuit: Schema.optionalKey(Schema.Boolean),
  confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
  confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
+ confirmThreadUnpin: Schema.optionalKey(Schema.Boolean),
  diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
  environmentIdentificationMode: Schema.optionalKey(EnvironmentIdentificationMode),
  glassOpacity: Schema.optionalKey(GlassOpacity),

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

@@ -21,6 +21,7 @@ const clientSettings: ClientSettings = {
  confirmQuit: true,
  confirmThreadArchive: true,
  confirmThreadDelete: false,
+ confirmThreadUnpin: false,
  dismissedProviderUpdateNotificationKeys: [],
  diffIgnoreWhitespace: true,
  environmentIdentificationMode: "artwork",

apps/web/src/components/ChatView.tsx

@@ -1273,7 +1273,7 @@ function ChatViewContent(props: ChatViewProps) {
  const threadSyncPhase = routeKind === "server" ? (props.threadSyncPhase ?? null) : null;
  const threadDetailLoading = threadSyncPhase === "loading";
  const handleNewThread = useNewThreadHandler();
- const { settleThread, pinThread, unpinThread } = useThreadActions();
+ const { settleThread, pinThread, confirmAndUnpinThread } = useThreadActions();
  const routeThreadRef = useMemo(
  () => scopeThreadRef(environmentId, threadId),
  [environmentId, threadId],
@@ -5146,17 +5146,19 @@ function ChatViewContent(props: ChatViewProps) {
  event.stopPropagation();
  if (!isServerThread || !activeThreadRef || !supportsPinning) return;
  const pinned = activeThreadPinned;
- void (pinned ? unpinThread(activeThreadRef) : pinThread(activeThreadRef)).then((result) => {
- if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
- const error = squashAtomCommandFailure(result);
- toastManager.add(
- stackedThreadToast({
- type: "error",
- title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
- description: error instanceof Error ? error.message : "An error occurred.",
- }),
- );
- });
+ void (pinned ? confirmAndUnpinThread(activeThreadRef) : pinThread(activeThreadRef)).then(
+ (result) => {
+ if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+ const error = squashAtomCommandFailure(result);
+ toastManager.add(
+ stackedThreadToast({
+ type: "error",
+ title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ }),
+ );
+ },
+ );
  return;
  }
 
@@ -5284,7 +5286,7 @@ function ChatViewContent(props: ChatViewProps) {
  settleThread,
  supportsPinning,
  supportsSettlement,
-unpinThread,
+confirmAndUnpinThread,
  toggleRightPanel,
  toggleRightPanelMaximized,
  toggleTerminalVisibility,

apps/web/src/components/Sidebar.tsx

@@ -1749,7 +1749,7 @@ export default function Sidebar() {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  reorderPinnedThread,
  archiveThread,
  deleteThread,
@@ -2709,7 +2709,7 @@ export default function Sidebar() {
  const attemptUnpin = useCallback(
  (threadRef: ScopedThreadRef) => {
  void (async () => {
- const result = await unpinThread(threadRef);
+ const result = await confirmAndUnpinThread(threadRef);
  if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
  const error = squashAtomCommandFailure(result);
  toastManager.add(
@@ -2722,7 +2722,7 @@ export default function Sidebar() {
  }
  })();
  },
- [unpinThread],
+ [confirmAndUnpinThread],
  );
 
  const handlePinnedDragEnd = useCallback(

apps/web/src/components/settings/SettingsPanels.tsx

@@ -526,6 +526,9 @@ export function useSettingsRestore(onRestored?: () => void) {
  ...(settings.addProjectBaseDirectory !== DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory
  ? ["Add project base directory"]
  : []),
+ ...(settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin
+ ? ["Unpin confirmation"]
+ : []),
  ...(settings.confirmThreadArchive !== DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive
  ? ["Archive confirmation"]
  : []),
@@ -554,6 +557,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  settings.confirmQuit,
  settings.confirmThreadArchive,
  settings.confirmThreadDelete,
+ settings.confirmThreadUnpin,
  settings.addProjectBaseDirectory,
  settings.defaultThreadEnvMode,
  settings.newWorktreesStartFromOrigin,
@@ -666,6 +670,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
  confirmThreadArchive: DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive,
  confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
  confirmQuit: DEFAULT_UNIFIED_SETTINGS.confirmQuit,
  textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
  fontFamilySans: DEFAULT_UNIFIED_SETTINGS.fontFamilySans,
@@ -2313,6 +2318,32 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ {...searchableSetting("unpin-confirmation")}
+ description="Ask before unpinning a thread from the pinned section."
+ resetAction={
+ settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin ? (
+ <SettingResetButton
+ label="unpin confirmation"
+ onClick={() =>
+ updateSettings({
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Switch
+ checked={settings.confirmThreadUnpin}
+ onCheckedChange={(checked) =>
+ updateSettings({ confirmThreadUnpin: Boolean(checked) })
+ }
+ aria-label="Confirm thread unpinning"
+ />
+ }
+ />
+
  <SettingsRow
  {...searchableSetting("archive-confirmation")}
  description="Require a second click on the inline archive action before a thread is archived."

apps/web/src/components/settings/settingsSearch.test.ts

@@ -56,6 +56,14 @@ describe("searchSettings", () => {
  ]);
  });
 
+ it("lists thread confirmations in panel order", () => {
+ expect(searchSettings("confirmation").map((item) => item.id)).toEqual([
+ "unpin-confirmation",
+ "archive-confirmation",
+ "delete-confirmation",
+ ]);
+ });
+
  it("returns no results for an empty query", () => {
  expect(searchSettings(" ", ITEMS)).toEqual([]);
  });

apps/web/src/components/settings/settingsSearch.ts

@@ -152,6 +152,11 @@ export const SETTINGS_SEARCH_ITEMS = [
  title: "Add project starts in",
  to: "/settings/general",
  },
+ {
+ id: "unpin-confirmation",
+ title: "Unpin confirmation",
+ to: "/settings/general",
+ },
  {
  id: "archive-confirmation",
  title: "Archive confirmation",

apps/web/src/hooks/useThreadActionMenu.ts

@@ -71,7 +71,7 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  archiveThread,
  deleteThread,
  } = useThreadActions();
@@ -215,9 +215,10 @@ export function useThreadActionMenu(input: {
  case "pin":
  await reportFailure("Failed to pin thread", () => pinThread(threadRef));
  return;
- case "unpin":
- await reportFailure("Failed to unpin thread", () => unpinThread(threadRef));
+ case "unpin": {
+ await reportFailure("Failed to unpin thread", () => confirmAndUnpinThread(threadRef));
  return;
+ }
  case "rename":
  onStartRename();
  return;
@@ -315,6 +316,7 @@ export function useThreadActionMenu(input: {
  changeRequest,
  confirmThreadArchive,
  confirmThreadDelete,
+ confirmAndUnpinThread,
  copyBranchToClipboard,
  copyPathToClipboard,
  copyThreadIdToClipboard,
@@ -328,7 +330,6 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  threadRef,
  timestampFormat,
- unpinThread,
  unsettleThread,
  unsnoozeThread,
  updateThreadMetadata,

apps/web/src/hooks/useThreadActions.test.ts

@@ -1,7 +1,7 @@
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
-import { ThreadArchiveBlockedError } from "./useThreadActions";
+import { requestThreadUnpinConfirmation, ThreadArchiveBlockedError } from "./useThreadActions";
 
 describe("ThreadArchiveBlockedError", () => {
  it("keeps the blocked thread context with the fixed message", () => {
@@ -17,3 +17,57 @@ describe("ThreadArchiveBlockedError", () => {
  expect(error.message).toBe("Cannot archive a running thread.");
  });
 });
+
+describe("requestThreadUnpinConfirmation", () => {
+ it("skips the dialog when confirmation is disabled", async () => {
+ let callCount = 0;
+ const result = await requestThreadUnpinConfirmation({
+ enabled: false,
+ title: "Pinned thread",
+ confirm: async () => {
+ callCount += 1;
+ return false;
+ },
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ expect(callCount).toBe(0);
+ });
+
+ it("degrades gracefully when dialogs are unavailable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: null,
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ });
+
+ it("uses the thread title and returns the user's decision", async () => {
+ let message = "";
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Release prep",
+ confirm: async (nextMessage) => {
+ message = nextMessage;
+ return false;
+ },
+ });
+
+ expect(message).toBe(
+ 'Unpin thread "Release prep"?\nThis will move the thread out of your pinned section.',
+ );
+ expect(result).toMatchObject({ _tag: "Success", value: false });
+ });
+
+ it("keeps dialog failures observable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: () => Promise.reject(new Error("dialog unavailable")),
+ });
+
+ expect(result._tag).toBe("Failure");
+ });
+});

apps/web/src/hooks/useThreadActions.ts

@@ -136,6 +136,26 @@ export class ThreadPinReorderUnsupportedError extends Schema.TaggedErrorClass<Th
  }
 }
 
+export async function requestThreadUnpinConfirmation(input: {
+ enabled: boolean;
+ title: string;
+ confirm: ((message: string) => Promise<boolean>) | null;
+}) {
+ const { confirm } = input;
+ if (!input.enabled || confirm === null) {
+ return AsyncResult.success(true);
+ }
+
+ return settlePromise(() =>
+ confirm(
+ [
+ `Unpin thread "${input.title}"?`,
+ "This will move the thread out of your pinned section.",
+ ].join("\n"),
+ ),
+ );
+}
+
 export function useThreadActions() {
  const closeTerminal = useAtomCommand(terminalEnvironment.close);
  const archiveThreadMutation = useAtomCommand(threadEnvironment.archive, {
@@ -177,6 +197,7 @@ export function useThreadActions() {
  });
  const sidebarThreadSortOrder = useClientSettings((settings) => settings.sidebarThreadSortOrder);
  const confirmThreadDelete = useClientSettings((settings) => settings.confirmThreadDelete);
+ const confirmThreadUnpin = useClientSettings((settings) => settings.confirmThreadUnpin);
  const clearComposerDraftForThread = useComposerDraftStore((store) => store.clearDraftThread);
  const clearProjectDraftThreadById = useComposerDraftStore(
  (store) => store.clearProjectDraftThreadById,
@@ -590,6 +611,26 @@ export function useThreadActions() {
  [unpinThreadMutation],
  );
 
+ const confirmAndUnpinThread = useCallback(
+ async (target: ScopedThreadRef) => {
+ const localApi = readLocalApi();
+ const resolved = resolveThreadTarget(target);
+ const confirmationResult = await requestThreadUnpinConfirmation({
+ enabled: confirmThreadUnpin,
+ title: resolved?.thread.title ?? "this thread",
+ confirm: localApi ? (message) => localApi.dialogs.confirm(message) : null,
+ });
+ if (confirmationResult._tag === "Failure") {
+ return confirmationResult;
+ }
+ if (!confirmationResult.value) {
+ return AsyncResult.success(undefined);
+ }
+ return unpinThread(target);
+ },
+ [confirmThreadUnpin, resolveThreadTarget, unpinThread],
+ );
+
  const reorderPinnedThread = useCallback(
  async (target: ScopedThreadRef, orderKey: string) => {
  // Callers (the sidebar drag handler) only enable dragging on
@@ -709,11 +750,13 @@ export function useThreadActions() {
  unsnoozeThread,
  pinThread,
  unpinThread,
+ confirmAndUnpinThread,
  reorderPinnedThread,
  }),
  [
  archiveThread,
  confirmAndDeleteThread,
+ confirmAndUnpinThread,
  deleteThread,
  pinThread,
  reorderPinnedThread,

docs/user/thread-sidebar.md

@@ -4,6 +4,9 @@ Pin a thread from its context menu to keep it in the pinned section above your a
 `mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of
 their project, including when you connect to more than one environment.
 
+To require confirmation before unpinning, enable **Settings → General → Unpin confirmation**. The
+confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.
+
 Pinned threads follow the auto-settle policy in **Settings → General**. Choose exactly one policy:
 settle when a pull request merges or closes, settle after a configurable period of inactivity, or
 never auto-settle. **Never** leaves every automatic path off, so threads settle only when you choose

packages/contracts/src/settings.test.ts

@@ -141,6 +141,12 @@ describe("ClientSettings sidebar", () => {
  );
  });
 
+ it("keeps unpin confirmation opt-in and patchable", () => {
+ expect(decodeClientSettings({}).confirmThreadUnpin).toBe(false);
+ expect(decodeClientSettingsPatch({ confirmThreadUnpin: true }).confirmThreadUnpin).toBe(true);
+ expect(() => decodeClientSettingsPatch({ confirmThreadUnpin: "yes" })).toThrow();
+ });
+
  it("allows auto-settle by inactivity to be disabled", () => {
  expect(
  decodeClientSettings({ sidebarAutoSettleAfterDays: null }).sidebarAutoSettleAfterDays,

packages/contracts/src/settings.ts

@@ -170,6 +170,7 @@ export const ClientSettingsSchema = Schema.Struct({
  confirmQuit: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
  confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+ confirmThreadUnpin: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
  Schema.withDecodingDefault(Effect.succeed([])),
  ),
@@ -913,6 +914,7 @@ export const ClientSettingsPatch = Schema.Struct({
  confirmQuit: Schema.optionalKey(Schema.Boolean),
  confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
  confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
+ confirmThreadUnpin: Schema.optionalKey(Schema.Boolean),
  diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
  environmentIdentificationMode: Schema.optionalKey(EnvironmentIdentificationMode),
  glassOpacity: Schema.optionalKey(GlassOpacity),

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

@@ -21,6 +21,7 @@ const clientSettings: ClientSettings = {
  confirmQuit: true,
  confirmThreadArchive: true,
  confirmThreadDelete: false,
+ confirmThreadUnpin: false,
  dismissedProviderUpdateNotificationKeys: [],
  diffIgnoreWhitespace: true,
  environmentIdentificationMode: "artwork",

apps/web/src/components/ChatView.tsx

@@ -1273,7 +1273,7 @@ function ChatViewContent(props: ChatViewProps) {
  const threadSyncPhase = routeKind === "server" ? (props.threadSyncPhase ?? null) : null;
  const threadDetailLoading = threadSyncPhase === "loading";
  const handleNewThread = useNewThreadHandler();
- const { settleThread, pinThread, unpinThread } = useThreadActions();
+ const { settleThread, pinThread, confirmAndUnpinThread } = useThreadActions();
  const routeThreadRef = useMemo(
  () => scopeThreadRef(environmentId, threadId),
  [environmentId, threadId],
@@ -5146,17 +5146,19 @@ function ChatViewContent(props: ChatViewProps) {
  event.stopPropagation();
  if (!isServerThread || !activeThreadRef || !supportsPinning) return;
  const pinned = activeThreadPinned;
- void (pinned ? unpinThread(activeThreadRef) : pinThread(activeThreadRef)).then((result) => {
- if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
- const error = squashAtomCommandFailure(result);
- toastManager.add(
- stackedThreadToast({
- type: "error",
- title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
- description: error instanceof Error ? error.message : "An error occurred.",
- }),
- );
- });
+ void (pinned ? confirmAndUnpinThread(activeThreadRef) : pinThread(activeThreadRef)).then(
+ (result) => {
+ if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+ const error = squashAtomCommandFailure(result);
+ toastManager.add(
+ stackedThreadToast({
+ type: "error",
+ title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ }),
+ );
+ },
+ );
  return;
  }
 
@@ -5284,7 +5286,7 @@ function ChatViewContent(props: ChatViewProps) {
  settleThread,
  supportsPinning,
  supportsSettlement,
-unpinThread,
+confirmAndUnpinThread,
  toggleRightPanel,
  toggleRightPanelMaximized,
  toggleTerminalVisibility,

apps/web/src/components/Sidebar.tsx

@@ -1749,7 +1749,7 @@ export default function Sidebar() {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  reorderPinnedThread,
  archiveThread,
  deleteThread,
@@ -2709,7 +2709,7 @@ export default function Sidebar() {
  const attemptUnpin = useCallback(
  (threadRef: ScopedThreadRef) => {
  void (async () => {
- const result = await unpinThread(threadRef);
+ const result = await confirmAndUnpinThread(threadRef);
  if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
  const error = squashAtomCommandFailure(result);
  toastManager.add(
@@ -2722,7 +2722,7 @@ export default function Sidebar() {
  }
  })();
  },
- [unpinThread],
+ [confirmAndUnpinThread],
  );
 
  const handlePinnedDragEnd = useCallback(

apps/web/src/components/settings/SettingsPanels.tsx

@@ -526,6 +526,9 @@ export function useSettingsRestore(onRestored?: () => void) {
  ...(settings.addProjectBaseDirectory !== DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory
  ? ["Add project base directory"]
  : []),
+ ...(settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin
+ ? ["Unpin confirmation"]
+ : []),
  ...(settings.confirmThreadArchive !== DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive
  ? ["Archive confirmation"]
  : []),
@@ -554,6 +557,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  settings.confirmQuit,
  settings.confirmThreadArchive,
  settings.confirmThreadDelete,
+ settings.confirmThreadUnpin,
  settings.addProjectBaseDirectory,
  settings.defaultThreadEnvMode,
  settings.newWorktreesStartFromOrigin,
@@ -666,6 +670,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
  confirmThreadArchive: DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive,
  confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
  confirmQuit: DEFAULT_UNIFIED_SETTINGS.confirmQuit,
  textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
  fontFamilySans: DEFAULT_UNIFIED_SETTINGS.fontFamilySans,
@@ -2313,6 +2318,32 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ {...searchableSetting("unpin-confirmation")}
+ description="Ask before unpinning a thread from the pinned section."
+ resetAction={
+ settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin ? (
+ <SettingResetButton
+ label="unpin confirmation"
+ onClick={() =>
+ updateSettings({
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Switch
+ checked={settings.confirmThreadUnpin}
+ onCheckedChange={(checked) =>
+ updateSettings({ confirmThreadUnpin: Boolean(checked) })
+ }
+ aria-label="Confirm thread unpinning"
+ />
+ }
+ />
+
  <SettingsRow
  {...searchableSetting("archive-confirmation")}
  description="Require a second click on the inline archive action before a thread is archived."

apps/web/src/components/settings/settingsSearch.test.ts

@@ -56,6 +56,14 @@ describe("searchSettings", () => {
  ]);
  });
 
+ it("lists thread confirmations in panel order", () => {
+ expect(searchSettings("confirmation").map((item) => item.id)).toEqual([
+ "unpin-confirmation",
+ "archive-confirmation",
+ "delete-confirmation",
+ ]);
+ });
+
  it("returns no results for an empty query", () => {
  expect(searchSettings(" ", ITEMS)).toEqual([]);
  });

apps/web/src/components/settings/settingsSearch.ts

@@ -152,6 +152,11 @@ export const SETTINGS_SEARCH_ITEMS = [
  title: "Add project starts in",
  to: "/settings/general",
  },
+ {
+ id: "unpin-confirmation",
+ title: "Unpin confirmation",
+ to: "/settings/general",
+ },
  {
  id: "archive-confirmation",
  title: "Archive confirmation",

apps/web/src/hooks/useThreadActionMenu.ts

@@ -71,7 +71,7 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  archiveThread,
  deleteThread,
  } = useThreadActions();
@@ -215,9 +215,10 @@ export function useThreadActionMenu(input: {
  case "pin":
  await reportFailure("Failed to pin thread", () => pinThread(threadRef));
  return;
- case "unpin":
- await reportFailure("Failed to unpin thread", () => unpinThread(threadRef));
+ case "unpin": {
+ await reportFailure("Failed to unpin thread", () => confirmAndUnpinThread(threadRef));
  return;
+ }
  case "rename":
  onStartRename();
  return;
@@ -315,6 +316,7 @@ export function useThreadActionMenu(input: {
  changeRequest,
  confirmThreadArchive,
  confirmThreadDelete,
+ confirmAndUnpinThread,
  copyBranchToClipboard,
  copyPathToClipboard,
  copyThreadIdToClipboard,
@@ -328,7 +330,6 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  threadRef,
  timestampFormat,
- unpinThread,
  unsettleThread,
  unsnoozeThread,
  updateThreadMetadata,

apps/web/src/hooks/useThreadActions.test.ts

@@ -1,7 +1,7 @@
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
-import { ThreadArchiveBlockedError } from "./useThreadActions";
+import { requestThreadUnpinConfirmation, ThreadArchiveBlockedError } from "./useThreadActions";
 
 describe("ThreadArchiveBlockedError", () => {
  it("keeps the blocked thread context with the fixed message", () => {
@@ -17,3 +17,57 @@ describe("ThreadArchiveBlockedError", () => {
  expect(error.message).toBe("Cannot archive a running thread.");
  });
 });
+
+describe("requestThreadUnpinConfirmation", () => {
+ it("skips the dialog when confirmation is disabled", async () => {
+ let callCount = 0;
+ const result = await requestThreadUnpinConfirmation({
+ enabled: false,
+ title: "Pinned thread",
+ confirm: async () => {
+ callCount += 1;
+ return false;
+ },
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ expect(callCount).toBe(0);
+ });
+
+ it("degrades gracefully when dialogs are unavailable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: null,
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ });
+
+ it("uses the thread title and returns the user's decision", async () => {
+ let message = "";
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Release prep",
+ confirm: async (nextMessage) => {
+ message = nextMessage;
+ return false;
+ },
+ });
+
+ expect(message).toBe(
+ 'Unpin thread "Release prep"?\nThis will move the thread out of your pinned section.',
+ );
+ expect(result).toMatchObject({ _tag: "Success", value: false });
+ });
+
+ it("keeps dialog failures observable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: () => Promise.reject(new Error("dialog unavailable")),
+ });
+
+ expect(result._tag).toBe("Failure");
+ });
+});

apps/web/src/hooks/useThreadActions.ts

@@ -136,6 +136,26 @@ export class ThreadPinReorderUnsupportedError extends Schema.TaggedErrorClass<Th
  }
 }
 
+export async function requestThreadUnpinConfirmation(input: {
+ enabled: boolean;
+ title: string;
+ confirm: ((message: string) => Promise<boolean>) | null;
+}) {
+ const { confirm } = input;
+ if (!input.enabled || confirm === null) {
+ return AsyncResult.success(true);
+ }
+
+ return settlePromise(() =>
+ confirm(
+ [
+ `Unpin thread "${input.title}"?`,
+ "This will move the thread out of your pinned section.",
+ ].join("\n"),
+ ),
+ );
+}
+
 export function useThreadActions() {
  const closeTerminal = useAtomCommand(terminalEnvironment.close);
  const archiveThreadMutation = useAtomCommand(threadEnvironment.archive, {
@@ -177,6 +197,7 @@ export function useThreadActions() {
  });
  const sidebarThreadSortOrder = useClientSettings((settings) => settings.sidebarThreadSortOrder);
  const confirmThreadDelete = useClientSettings((settings) => settings.confirmThreadDelete);
+ const confirmThreadUnpin = useClientSettings((settings) => settings.confirmThreadUnpin);
  const clearComposerDraftForThread = useComposerDraftStore((store) => store.clearDraftThread);
  const clearProjectDraftThreadById = useComposerDraftStore(
  (store) => store.clearProjectDraftThreadById,
@@ -590,6 +611,26 @@ export function useThreadActions() {
  [unpinThreadMutation],
  );
 
+ const confirmAndUnpinThread = useCallback(
+ async (target: ScopedThreadRef) => {
+ const localApi = readLocalApi();
+ const resolved = resolveThreadTarget(target);
+ const confirmationResult = await requestThreadUnpinConfirmation({
+ enabled: confirmThreadUnpin,
+ title: resolved?.thread.title ?? "this thread",
+ confirm: localApi ? (message) => localApi.dialogs.confirm(message) : null,
+ });
+ if (confirmationResult._tag === "Failure") {
+ return confirmationResult;
+ }
+ if (!confirmationResult.value) {
+ return AsyncResult.success(undefined);
+ }
+ return unpinThread(target);
+ },
+ [confirmThreadUnpin, resolveThreadTarget, unpinThread],
+ );
+
  const reorderPinnedThread = useCallback(
  async (target: ScopedThreadRef, orderKey: string) => {
  // Callers (the sidebar drag handler) only enable dragging on
@@ -709,11 +750,13 @@ export function useThreadActions() {
  unsnoozeThread,
  pinThread,
  unpinThread,
+ confirmAndUnpinThread,
  reorderPinnedThread,
  }),
  [
  archiveThread,
  confirmAndDeleteThread,
+ confirmAndUnpinThread,
  deleteThread,
  pinThread,
  reorderPinnedThread,

docs/user/thread-sidebar.md

@@ -4,6 +4,9 @@ Pin a thread from its context menu to keep it in the pinned section above your a
 `mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of
 their project, including when you connect to more than one environment.
 
+To require confirmation before unpinning, enable **Settings → General → Unpin confirmation**. The
+confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.
+
 Pinned threads follow the auto-settle policy in **Settings → General**. Choose exactly one policy:
 settle when a pull request merges or closes, settle after a configurable period of inactivity, or
 never auto-settle. **Never** leaves every automatic path off, so threads settle only when you choose

packages/contracts/src/settings.test.ts

@@ -141,6 +141,12 @@ describe("ClientSettings sidebar", () => {
  );
  });
 
+ it("keeps unpin confirmation opt-in and patchable", () => {
+ expect(decodeClientSettings({}).confirmThreadUnpin).toBe(false);
+ expect(decodeClientSettingsPatch({ confirmThreadUnpin: true }).confirmThreadUnpin).toBe(true);
+ expect(() => decodeClientSettingsPatch({ confirmThreadUnpin: "yes" })).toThrow();
+ });
+
  it("allows auto-settle by inactivity to be disabled", () => {
  expect(
  decodeClientSettings({ sidebarAutoSettleAfterDays: null }).sidebarAutoSettleAfterDays,

packages/contracts/src/settings.ts

@@ -170,6 +170,7 @@ export const ClientSettingsSchema = Schema.Struct({
  confirmQuit: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
  confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+ confirmThreadUnpin: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
  Schema.withDecodingDefault(Effect.succeed([])),
  ),
@@ -913,6 +914,7 @@ export const ClientSettingsPatch = Schema.Struct({
  confirmQuit: Schema.optionalKey(Schema.Boolean),
  confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
  confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
+ confirmThreadUnpin: Schema.optionalKey(Schema.Boolean),
  diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
  environmentIdentificationMode: Schema.optionalKey(EnvironmentIdentificationMode),
  glassOpacity: Schema.optionalKey(GlassOpacity),

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

@@ -21,6 +21,7 @@ const clientSettings: ClientSettings = {
  confirmQuit: true,
  confirmThreadArchive: true,
  confirmThreadDelete: false,
+ confirmThreadUnpin: false,
  dismissedProviderUpdateNotificationKeys: [],
  diffIgnoreWhitespace: true,
  environmentIdentificationMode: "artwork",

apps/web/src/components/ChatView.tsx

@@ -1273,7 +1273,7 @@ function ChatViewContent(props: ChatViewProps) {
  const threadSyncPhase = routeKind === "server" ? (props.threadSyncPhase ?? null) : null;
  const threadDetailLoading = threadSyncPhase === "loading";
  const handleNewThread = useNewThreadHandler();
- const { settleThread, pinThread, unpinThread } = useThreadActions();
+ const { settleThread, pinThread, confirmAndUnpinThread } = useThreadActions();
  const routeThreadRef = useMemo(
  () => scopeThreadRef(environmentId, threadId),
  [environmentId, threadId],
@@ -5146,17 +5146,19 @@ function ChatViewContent(props: ChatViewProps) {
  event.stopPropagation();
  if (!isServerThread || !activeThreadRef || !supportsPinning) return;
  const pinned = activeThreadPinned;
- void (pinned ? unpinThread(activeThreadRef) : pinThread(activeThreadRef)).then((result) => {
- if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
- const error = squashAtomCommandFailure(result);
- toastManager.add(
- stackedThreadToast({
- type: "error",
- title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
- description: error instanceof Error ? error.message : "An error occurred.",
- }),
- );
- });
+ void (pinned ? confirmAndUnpinThread(activeThreadRef) : pinThread(activeThreadRef)).then(
+ (result) => {
+ if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+ const error = squashAtomCommandFailure(result);
+ toastManager.add(
+ stackedThreadToast({
+ type: "error",
+ title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ }),
+ );
+ },
+ );
  return;
  }
 
@@ -5284,7 +5286,7 @@ function ChatViewContent(props: ChatViewProps) {
  settleThread,
  supportsPinning,
  supportsSettlement,
-unpinThread,
+confirmAndUnpinThread,
  toggleRightPanel,
  toggleRightPanelMaximized,
  toggleTerminalVisibility,

apps/web/src/components/Sidebar.tsx

@@ -1749,7 +1749,7 @@ export default function Sidebar() {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  reorderPinnedThread,
  archiveThread,
  deleteThread,
@@ -2709,7 +2709,7 @@ export default function Sidebar() {
  const attemptUnpin = useCallback(
  (threadRef: ScopedThreadRef) => {
  void (async () => {
- const result = await unpinThread(threadRef);
+ const result = await confirmAndUnpinThread(threadRef);
  if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
  const error = squashAtomCommandFailure(result);
  toastManager.add(
@@ -2722,7 +2722,7 @@ export default function Sidebar() {
  }
  })();
  },
- [unpinThread],
+ [confirmAndUnpinThread],
  );
 
  const handlePinnedDragEnd = useCallback(

apps/web/src/components/settings/SettingsPanels.tsx

@@ -526,6 +526,9 @@ export function useSettingsRestore(onRestored?: () => void) {
  ...(settings.addProjectBaseDirectory !== DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory
  ? ["Add project base directory"]
  : []),
+ ...(settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin
+ ? ["Unpin confirmation"]
+ : []),
  ...(settings.confirmThreadArchive !== DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive
  ? ["Archive confirmation"]
  : []),
@@ -554,6 +557,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  settings.confirmQuit,
  settings.confirmThreadArchive,
  settings.confirmThreadDelete,
+ settings.confirmThreadUnpin,
  settings.addProjectBaseDirectory,
  settings.defaultThreadEnvMode,
  settings.newWorktreesStartFromOrigin,
@@ -666,6 +670,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
  confirmThreadArchive: DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive,
  confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
  confirmQuit: DEFAULT_UNIFIED_SETTINGS.confirmQuit,
  textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
  fontFamilySans: DEFAULT_UNIFIED_SETTINGS.fontFamilySans,
@@ -2313,6 +2318,32 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ {...searchableSetting("unpin-confirmation")}
+ description="Ask before unpinning a thread from the pinned section."
+ resetAction={
+ settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin ? (
+ <SettingResetButton
+ label="unpin confirmation"
+ onClick={() =>
+ updateSettings({
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Switch
+ checked={settings.confirmThreadUnpin}
+ onCheckedChange={(checked) =>
+ updateSettings({ confirmThreadUnpin: Boolean(checked) })
+ }
+ aria-label="Confirm thread unpinning"
+ />
+ }
+ />
+
  <SettingsRow
  {...searchableSetting("archive-confirmation")}
  description="Require a second click on the inline archive action before a thread is archived."

apps/web/src/components/settings/settingsSearch.test.ts

@@ -56,6 +56,14 @@ describe("searchSettings", () => {
  ]);
  });
 
+ it("lists thread confirmations in panel order", () => {
+ expect(searchSettings("confirmation").map((item) => item.id)).toEqual([
+ "unpin-confirmation",
+ "archive-confirmation",
+ "delete-confirmation",
+ ]);
+ });
+
  it("returns no results for an empty query", () => {
  expect(searchSettings(" ", ITEMS)).toEqual([]);
  });

apps/web/src/components/settings/settingsSearch.ts

@@ -152,6 +152,11 @@ export const SETTINGS_SEARCH_ITEMS = [
  title: "Add project starts in",
  to: "/settings/general",
  },
+ {
+ id: "unpin-confirmation",
+ title: "Unpin confirmation",
+ to: "/settings/general",
+ },
  {
  id: "archive-confirmation",
  title: "Archive confirmation",

apps/web/src/hooks/useThreadActionMenu.ts

@@ -71,7 +71,7 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  archiveThread,
  deleteThread,
  } = useThreadActions();
@@ -215,9 +215,10 @@ export function useThreadActionMenu(input: {
  case "pin":
  await reportFailure("Failed to pin thread", () => pinThread(threadRef));
  return;
- case "unpin":
- await reportFailure("Failed to unpin thread", () => unpinThread(threadRef));
+ case "unpin": {
+ await reportFailure("Failed to unpin thread", () => confirmAndUnpinThread(threadRef));
  return;
+ }
  case "rename":
  onStartRename();
  return;
@@ -315,6 +316,7 @@ export function useThreadActionMenu(input: {
  changeRequest,
  confirmThreadArchive,
  confirmThreadDelete,
+ confirmAndUnpinThread,
  copyBranchToClipboard,
  copyPathToClipboard,
  copyThreadIdToClipboard,
@@ -328,7 +330,6 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  threadRef,
  timestampFormat,
- unpinThread,
  unsettleThread,
  unsnoozeThread,
  updateThreadMetadata,

apps/web/src/hooks/useThreadActions.test.ts

@@ -1,7 +1,7 @@
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
-import { ThreadArchiveBlockedError } from "./useThreadActions";
+import { requestThreadUnpinConfirmation, ThreadArchiveBlockedError } from "./useThreadActions";
 
 describe("ThreadArchiveBlockedError", () => {
  it("keeps the blocked thread context with the fixed message", () => {
@@ -17,3 +17,57 @@ describe("ThreadArchiveBlockedError", () => {
  expect(error.message).toBe("Cannot archive a running thread.");
  });
 });
+
+describe("requestThreadUnpinConfirmation", () => {
+ it("skips the dialog when confirmation is disabled", async () => {
+ let callCount = 0;
+ const result = await requestThreadUnpinConfirmation({
+ enabled: false,
+ title: "Pinned thread",
+ confirm: async () => {
+ callCount += 1;
+ return false;
+ },
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ expect(callCount).toBe(0);
+ });
+
+ it("degrades gracefully when dialogs are unavailable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: null,
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ });
+
+ it("uses the thread title and returns the user's decision", async () => {
+ let message = "";
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Release prep",
+ confirm: async (nextMessage) => {
+ message = nextMessage;
+ return false;
+ },
+ });
+
+ expect(message).toBe(
+ 'Unpin thread "Release prep"?\nThis will move the thread out of your pinned section.',
+ );
+ expect(result).toMatchObject({ _tag: "Success", value: false });
+ });
+
+ it("keeps dialog failures observable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: () => Promise.reject(new Error("dialog unavailable")),
+ });
+
+ expect(result._tag).toBe("Failure");
+ });
+});

apps/web/src/hooks/useThreadActions.ts

@@ -136,6 +136,26 @@ export class ThreadPinReorderUnsupportedError extends Schema.TaggedErrorClass<Th
  }
 }
 
+export async function requestThreadUnpinConfirmation(input: {
+ enabled: boolean;
+ title: string;
+ confirm: ((message: string) => Promise<boolean>) | null;
+}) {
+ const { confirm } = input;
+ if (!input.enabled || confirm === null) {
+ return AsyncResult.success(true);
+ }
+
+ return settlePromise(() =>
+ confirm(
+ [
+ `Unpin thread "${input.title}"?`,
+ "This will move the thread out of your pinned section.",
+ ].join("\n"),
+ ),
+ );
+}
+
 export function useThreadActions() {
  const closeTerminal = useAtomCommand(terminalEnvironment.close);
  const archiveThreadMutation = useAtomCommand(threadEnvironment.archive, {
@@ -177,6 +197,7 @@ export function useThreadActions() {
  });
  const sidebarThreadSortOrder = useClientSettings((settings) => settings.sidebarThreadSortOrder);
  const confirmThreadDelete = useClientSettings((settings) => settings.confirmThreadDelete);
+ const confirmThreadUnpin = useClientSettings((settings) => settings.confirmThreadUnpin);
  const clearComposerDraftForThread = useComposerDraftStore((store) => store.clearDraftThread);
  const clearProjectDraftThreadById = useComposerDraftStore(
  (store) => store.clearProjectDraftThreadById,
@@ -590,6 +611,26 @@ export function useThreadActions() {
  [unpinThreadMutation],
  );
 
+ const confirmAndUnpinThread = useCallback(
+ async (target: ScopedThreadRef) => {
+ const localApi = readLocalApi();
+ const resolved = resolveThreadTarget(target);
+ const confirmationResult = await requestThreadUnpinConfirmation({
+ enabled: confirmThreadUnpin,
+ title: resolved?.thread.title ?? "this thread",
+ confirm: localApi ? (message) => localApi.dialogs.confirm(message) : null,
+ });
+ if (confirmationResult._tag === "Failure") {
+ return confirmationResult;
+ }
+ if (!confirmationResult.value) {
+ return AsyncResult.success(undefined);
+ }
+ return unpinThread(target);
+ },
+ [confirmThreadUnpin, resolveThreadTarget, unpinThread],
+ );
+
  const reorderPinnedThread = useCallback(
  async (target: ScopedThreadRef, orderKey: string) => {
  // Callers (the sidebar drag handler) only enable dragging on
@@ -709,11 +750,13 @@ export function useThreadActions() {
  unsnoozeThread,
  pinThread,
  unpinThread,
+ confirmAndUnpinThread,
  reorderPinnedThread,
  }),
  [
  archiveThread,
  confirmAndDeleteThread,
+ confirmAndUnpinThread,
  deleteThread,
  pinThread,
  reorderPinnedThread,

docs/user/thread-sidebar.md

@@ -4,6 +4,9 @@ Pin a thread from its context menu to keep it in the pinned section above your a
 `mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of
 their project, including when you connect to more than one environment.
 
+To require confirmation before unpinning, enable **Settings → General → Unpin confirmation**. The
+confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.
+
 Pinned threads follow the auto-settle policy in **Settings → General**. Choose exactly one policy:
 settle when a pull request merges or closes, settle after a configurable period of inactivity, or
 never auto-settle. **Never** leaves every automatic path off, so threads settle only when you choose

packages/contracts/src/settings.test.ts

@@ -141,6 +141,12 @@ describe("ClientSettings sidebar", () => {
  );
  });
 
+ it("keeps unpin confirmation opt-in and patchable", () => {
+ expect(decodeClientSettings({}).confirmThreadUnpin).toBe(false);
+ expect(decodeClientSettingsPatch({ confirmThreadUnpin: true }).confirmThreadUnpin).toBe(true);
+ expect(() => decodeClientSettingsPatch({ confirmThreadUnpin: "yes" })).toThrow();
+ });
+
  it("allows auto-settle by inactivity to be disabled", () => {
  expect(
  decodeClientSettings({ sidebarAutoSettleAfterDays: null }).sidebarAutoSettleAfterDays,

packages/contracts/src/settings.ts

@@ -170,6 +170,7 @@ export const ClientSettingsSchema = Schema.Struct({
  confirmQuit: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
  confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+ confirmThreadUnpin: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
  Schema.withDecodingDefault(Effect.succeed([])),
  ),
@@ -913,6 +914,7 @@ export const ClientSettingsPatch = Schema.Struct({
  confirmQuit: Schema.optionalKey(Schema.Boolean),
  confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
  confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
+ confirmThreadUnpin: Schema.optionalKey(Schema.Boolean),
  diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
  environmentIdentificationMode: Schema.optionalKey(EnvironmentIdentificationMode),
  glassOpacity: Schema.optionalKey(GlassOpacity),

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

@@ -21,6 +21,7 @@ const clientSettings: ClientSettings = {
  confirmQuit: true,
  confirmThreadArchive: true,
  confirmThreadDelete: false,
+ confirmThreadUnpin: false,
  dismissedProviderUpdateNotificationKeys: [],
  diffIgnoreWhitespace: true,
  environmentIdentificationMode: "artwork",

apps/web/src/components/ChatView.tsx

@@ -1273,7 +1273,7 @@ function ChatViewContent(props: ChatViewProps) {
  const threadSyncPhase = routeKind === "server" ? (props.threadSyncPhase ?? null) : null;
  const threadDetailLoading = threadSyncPhase === "loading";
  const handleNewThread = useNewThreadHandler();
- const { settleThread, pinThread, unpinThread } = useThreadActions();
+ const { settleThread, pinThread, confirmAndUnpinThread } = useThreadActions();
  const routeThreadRef = useMemo(
  () => scopeThreadRef(environmentId, threadId),
  [environmentId, threadId],
@@ -5146,17 +5146,19 @@ function ChatViewContent(props: ChatViewProps) {
  event.stopPropagation();
  if (!isServerThread || !activeThreadRef || !supportsPinning) return;
  const pinned = activeThreadPinned;
- void (pinned ? unpinThread(activeThreadRef) : pinThread(activeThreadRef)).then((result) => {
- if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
- const error = squashAtomCommandFailure(result);
- toastManager.add(
- stackedThreadToast({
- type: "error",
- title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
- description: error instanceof Error ? error.message : "An error occurred.",
- }),
- );
- });
+ void (pinned ? confirmAndUnpinThread(activeThreadRef) : pinThread(activeThreadRef)).then(
+ (result) => {
+ if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+ const error = squashAtomCommandFailure(result);
+ toastManager.add(
+ stackedThreadToast({
+ type: "error",
+ title: pinned ? "Failed to unpin thread" : "Failed to pin thread",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ }),
+ );
+ },
+ );
  return;
  }
 
@@ -5284,7 +5286,7 @@ function ChatViewContent(props: ChatViewProps) {
  settleThread,
  supportsPinning,
  supportsSettlement,
-unpinThread,
+confirmAndUnpinThread,
  toggleRightPanel,
  toggleRightPanelMaximized,
  toggleTerminalVisibility,

apps/web/src/components/Sidebar.tsx

@@ -1749,7 +1749,7 @@ export default function Sidebar() {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  reorderPinnedThread,
  archiveThread,
  deleteThread,
@@ -2709,7 +2709,7 @@ export default function Sidebar() {
  const attemptUnpin = useCallback(
  (threadRef: ScopedThreadRef) => {
  void (async () => {
- const result = await unpinThread(threadRef);
+ const result = await confirmAndUnpinThread(threadRef);
  if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
  const error = squashAtomCommandFailure(result);
  toastManager.add(
@@ -2722,7 +2722,7 @@ export default function Sidebar() {
  }
  })();
  },
- [unpinThread],
+ [confirmAndUnpinThread],
  );
 
  const handlePinnedDragEnd = useCallback(

apps/web/src/components/settings/SettingsPanels.tsx

@@ -526,6 +526,9 @@ export function useSettingsRestore(onRestored?: () => void) {
  ...(settings.addProjectBaseDirectory !== DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory
  ? ["Add project base directory"]
  : []),
+ ...(settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin
+ ? ["Unpin confirmation"]
+ : []),
  ...(settings.confirmThreadArchive !== DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive
  ? ["Archive confirmation"]
  : []),
@@ -554,6 +557,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  settings.confirmQuit,
  settings.confirmThreadArchive,
  settings.confirmThreadDelete,
+ settings.confirmThreadUnpin,
  settings.addProjectBaseDirectory,
  settings.defaultThreadEnvMode,
  settings.newWorktreesStartFromOrigin,
@@ -666,6 +670,7 @@ export function useSettingsRestore(onRestored?: () => void) {
  addProjectBaseDirectory: DEFAULT_UNIFIED_SETTINGS.addProjectBaseDirectory,
  confirmThreadArchive: DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive,
  confirmThreadDelete: DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete,
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
  confirmQuit: DEFAULT_UNIFIED_SETTINGS.confirmQuit,
  textGenerationModelSelection: DEFAULT_UNIFIED_SETTINGS.textGenerationModelSelection,
  fontFamilySans: DEFAULT_UNIFIED_SETTINGS.fontFamilySans,
@@ -2313,6 +2318,32 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ {...searchableSetting("unpin-confirmation")}
+ description="Ask before unpinning a thread from the pinned section."
+ resetAction={
+ settings.confirmThreadUnpin !== DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin ? (
+ <SettingResetButton
+ label="unpin confirmation"
+ onClick={() =>
+ updateSettings({
+ confirmThreadUnpin: DEFAULT_UNIFIED_SETTINGS.confirmThreadUnpin,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Switch
+ checked={settings.confirmThreadUnpin}
+ onCheckedChange={(checked) =>
+ updateSettings({ confirmThreadUnpin: Boolean(checked) })
+ }
+ aria-label="Confirm thread unpinning"
+ />
+ }
+ />
+
  <SettingsRow
  {...searchableSetting("archive-confirmation")}
  description="Require a second click on the inline archive action before a thread is archived."

apps/web/src/components/settings/settingsSearch.test.ts

@@ -56,6 +56,14 @@ describe("searchSettings", () => {
  ]);
  });
 
+ it("lists thread confirmations in panel order", () => {
+ expect(searchSettings("confirmation").map((item) => item.id)).toEqual([
+ "unpin-confirmation",
+ "archive-confirmation",
+ "delete-confirmation",
+ ]);
+ });
+
  it("returns no results for an empty query", () => {
  expect(searchSettings(" ", ITEMS)).toEqual([]);
  });

apps/web/src/components/settings/settingsSearch.ts

@@ -152,6 +152,11 @@ export const SETTINGS_SEARCH_ITEMS = [
  title: "Add project starts in",
  to: "/settings/general",
  },
+ {
+ id: "unpin-confirmation",
+ title: "Unpin confirmation",
+ to: "/settings/general",
+ },
  {
  id: "archive-confirmation",
  title: "Archive confirmation",

apps/web/src/hooks/useThreadActionMenu.ts

@@ -71,7 +71,7 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  unsnoozeThread,
  pinThread,
-unpinThread,
+confirmAndUnpinThread,
  archiveThread,
  deleteThread,
  } = useThreadActions();
@@ -215,9 +215,10 @@ export function useThreadActionMenu(input: {
  case "pin":
  await reportFailure("Failed to pin thread", () => pinThread(threadRef));
  return;
- case "unpin":
- await reportFailure("Failed to unpin thread", () => unpinThread(threadRef));
+ case "unpin": {
+ await reportFailure("Failed to unpin thread", () => confirmAndUnpinThread(threadRef));
  return;
+ }
  case "rename":
  onStartRename();
  return;
@@ -315,6 +316,7 @@ export function useThreadActionMenu(input: {
  changeRequest,
  confirmThreadArchive,
  confirmThreadDelete,
+ confirmAndUnpinThread,
  copyBranchToClipboard,
  copyPathToClipboard,
  copyThreadIdToClipboard,
@@ -328,7 +330,6 @@ export function useThreadActionMenu(input: {
  snoozeThread,
  threadRef,
  timestampFormat,
- unpinThread,
  unsettleThread,
  unsnoozeThread,
  updateThreadMetadata,

apps/web/src/hooks/useThreadActions.test.ts

@@ -1,7 +1,7 @@
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
 
-import { ThreadArchiveBlockedError } from "./useThreadActions";
+import { requestThreadUnpinConfirmation, ThreadArchiveBlockedError } from "./useThreadActions";
 
 describe("ThreadArchiveBlockedError", () => {
  it("keeps the blocked thread context with the fixed message", () => {
@@ -17,3 +17,57 @@ describe("ThreadArchiveBlockedError", () => {
  expect(error.message).toBe("Cannot archive a running thread.");
  });
 });
+
+describe("requestThreadUnpinConfirmation", () => {
+ it("skips the dialog when confirmation is disabled", async () => {
+ let callCount = 0;
+ const result = await requestThreadUnpinConfirmation({
+ enabled: false,
+ title: "Pinned thread",
+ confirm: async () => {
+ callCount += 1;
+ return false;
+ },
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ expect(callCount).toBe(0);
+ });
+
+ it("degrades gracefully when dialogs are unavailable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: null,
+ });
+
+ expect(result).toMatchObject({ _tag: "Success", value: true });
+ });
+
+ it("uses the thread title and returns the user's decision", async () => {
+ let message = "";
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Release prep",
+ confirm: async (nextMessage) => {
+ message = nextMessage;
+ return false;
+ },
+ });
+
+ expect(message).toBe(
+ 'Unpin thread "Release prep"?\nThis will move the thread out of your pinned section.',
+ );
+ expect(result).toMatchObject({ _tag: "Success", value: false });
+ });
+
+ it("keeps dialog failures observable", async () => {
+ const result = await requestThreadUnpinConfirmation({
+ enabled: true,
+ title: "Pinned thread",
+ confirm: () => Promise.reject(new Error("dialog unavailable")),
+ });
+
+ expect(result._tag).toBe("Failure");
+ });
+});

apps/web/src/hooks/useThreadActions.ts

@@ -136,6 +136,26 @@ export class ThreadPinReorderUnsupportedError extends Schema.TaggedErrorClass<Th
  }
 }
 
+export async function requestThreadUnpinConfirmation(input: {
+ enabled: boolean;
+ title: string;
+ confirm: ((message: string) => Promise<boolean>) | null;
+}) {
+ const { confirm } = input;
+ if (!input.enabled || confirm === null) {
+ return AsyncResult.success(true);
+ }
+
+ return settlePromise(() =>
+ confirm(
+ [
+ `Unpin thread "${input.title}"?`,
+ "This will move the thread out of your pinned section.",
+ ].join("\n"),
+ ),
+ );
+}
+
 export function useThreadActions() {
  const closeTerminal = useAtomCommand(terminalEnvironment.close);
  const archiveThreadMutation = useAtomCommand(threadEnvironment.archive, {
@@ -177,6 +197,7 @@ export function useThreadActions() {
  });
  const sidebarThreadSortOrder = useClientSettings((settings) => settings.sidebarThreadSortOrder);
  const confirmThreadDelete = useClientSettings((settings) => settings.confirmThreadDelete);
+ const confirmThreadUnpin = useClientSettings((settings) => settings.confirmThreadUnpin);
  const clearComposerDraftForThread = useComposerDraftStore((store) => store.clearDraftThread);
  const clearProjectDraftThreadById = useComposerDraftStore(
  (store) => store.clearProjectDraftThreadById,
@@ -590,6 +611,26 @@ export function useThreadActions() {
  [unpinThreadMutation],
  );
 
+ const confirmAndUnpinThread = useCallback(
+ async (target: ScopedThreadRef) => {
+ const localApi = readLocalApi();
+ const resolved = resolveThreadTarget(target);
+ const confirmationResult = await requestThreadUnpinConfirmation({
+ enabled: confirmThreadUnpin,
+ title: resolved?.thread.title ?? "this thread",
+ confirm: localApi ? (message) => localApi.dialogs.confirm(message) : null,
+ });
+ if (confirmationResult._tag === "Failure") {
+ return confirmationResult;
+ }
+ if (!confirmationResult.value) {
+ return AsyncResult.success(undefined);
+ }
+ return unpinThread(target);
+ },
+ [confirmThreadUnpin, resolveThreadTarget, unpinThread],
+ );
+
  const reorderPinnedThread = useCallback(
  async (target: ScopedThreadRef, orderKey: string) => {
  // Callers (the sidebar drag handler) only enable dragging on
@@ -709,11 +750,13 @@ export function useThreadActions() {
  unsnoozeThread,
  pinThread,
  unpinThread,
+ confirmAndUnpinThread,
  reorderPinnedThread,
  }),
  [
  archiveThread,
  confirmAndDeleteThread,
+ confirmAndUnpinThread,
  deleteThread,
  pinThread,
  reorderPinnedThread,

docs/user/thread-sidebar.md

@@ -4,6 +4,9 @@ Pin a thread from its context menu to keep it in the pinned section above your a
 `mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of
 their project, including when you connect to more than one environment.
 
+To require confirmation before unpinning, enable **Settings → General → Unpin confirmation**. The
+confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.
+
 Pinned threads follow the auto-settle policy in **Settings → General**. Choose exactly one policy:
 settle when a pull request merges or closes, settle after a configurable period of inactivity, or
 never auto-settle. **Never** leaves every automatic path off, so threads settle only when you choose

packages/contracts/src/settings.test.ts

@@ -141,6 +141,12 @@ describe("ClientSettings sidebar", () => {
  );
  });
 
+ it("keeps unpin confirmation opt-in and patchable", () => {
+ expect(decodeClientSettings({}).confirmThreadUnpin).toBe(false);
+ expect(decodeClientSettingsPatch({ confirmThreadUnpin: true }).confirmThreadUnpin).toBe(true);
+ expect(() => decodeClientSettingsPatch({ confirmThreadUnpin: "yes" })).toThrow();
+ });
+
  it("allows auto-settle by inactivity to be disabled", () => {
  expect(
  decodeClientSettings({ sidebarAutoSettleAfterDays: null }).sidebarAutoSettleAfterDays,

packages/contracts/src/settings.ts

@@ -170,6 +170,7 @@ export const ClientSettingsSchema = Schema.Struct({
  confirmQuit: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
  confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+ confirmThreadUnpin: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
  dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
  Schema.withDecodingDefault(Effect.succeed([])),
  ),
@@ -913,6 +914,7 @@ export const ClientSettingsPatch = Schema.Struct({
  confirmQuit: Schema.optionalKey(Schema.Boolean),
  confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
  confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
+ confirmThreadUnpin: Schema.optionalKey(Schema.Boolean),
  diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
  environmentIdentificationMode: Schema.optionalKey(EnvironmentIdentificationMode),
  glassOpacity: Schema.optionalKey(GlassOpacity),