fix(server): parse pid start times in stable locale

* feat(app): add auto-expand reasoning setting

* chore: add cross-env mise tool

* fix(app): stabilize web export and settings detail placement

* Revert "chore: add cross-env mise tool"

This reverts commit f56a367e0c.

* perf(app): narrow settings reads in agent stream

---------

Co-authored-by: Mohamed Boudra <boudra.moha@gmail.com>

docs/development.md

@@ -303,6 +303,8 @@ npm run build:app-deps     # highlight -> protocol -> client -> expo-two-way-aud
 
 Use `npm run build:server` whenever you have changed any daemon/server-facing package and need clean cross-package types or runtime behavior.
 
+The app Metro config disables Watchman and uses Metro's node crawler for exports. Keep that invariant unless you have verified production app exports on machines with and without Watchman installed; distro Watchman builds can differ in capabilities and change Metro's crawl behavior.
+
 For tighter loops, you can rebuild a single workspace:
 
 - Changed `packages/protocol/src/*` or `packages/client/src/*`: `npm run build:client`.

docs/mobile-testing.md

@@ -198,6 +198,19 @@ for i in $(seq 1 "$ITERATIONS"); do
 done
 ```
 
+### Android audio focus interruptions
+
+Voice mode uses the custom `expo-two-way-audio` Android module, so incoming calls and other system audio owners must be tested with emulator/system commands, not a JS-only test. To verify that voice resume handles denied audio focus without crashing:
+
+```bash
+adb shell am start -n sh.paseo/.MainActivity
+# Start voice mode in an existing composer, then background Paseo with Home.
+adb emu gsm call 5551234
+# Foreground Paseo while the call is still ringing.
+```
+
+Expected result: Paseo does not throw `RuntimeException: Audio focus request failed`; native audio reports an interruption and voice mode stops or pauses coherently.
+
 ## Unistyles + Reanimated
 
 ### The crash

nix/npm-deps.hash

@@ -1 +1 @@
-sha256-G88S68t7czYE7YtBIuRdkI85+GpVKEZUMZQtcnN73BA=
+sha256-RtZABQl17BlUyvFiFw9W5g2E/dpNlrOWpuCdV8wZk5o=

packages/app/e2e/diff-row-alignment.spec.ts

@@ -218,6 +218,38 @@ test("changes diff keeps code rows aligned with the gutter", async ({ page }) =>
   });
 });
 
+test("changes diff switches between flat and tree file lists", async ({ page }) => {
+  const workspace = await createWorkspaceWithMountedTabDiff();
+  await useUnwrappedDiffLines(page);
+  await openWorkspaceChanges(page, workspace);
+
+  await expectFlatFileList(page);
+  await expect(page.getByTestId("changes-toggle-layout")).toBeVisible();
+  await expect(page.getByTestId("changes-layout-unified")).toHaveCount(0);
+  await expect(page.getByTestId("changes-layout-split")).toHaveCount(0);
+
+  await page.getByTestId("changes-options-menu").click();
+  await expect(page.getByTestId("changes-options-menu-content")).toBeVisible();
+  await expect(page.getByTestId("changes-toggle-whitespace")).toContainText("Hide whitespace");
+  await expect(page.getByTestId("changes-toggle-wrap-lines")).toContainText("Wrap long lines");
+  await expect(page.getByTestId("changes-refresh")).toContainText("Refresh");
+  await page.getByTestId("changes-toggle-whitespace").click();
+  await page.getByTestId("changes-options-menu").click();
+  await expect(page.getByTestId("changes-toggle-whitespace")).toContainText("Show whitespace");
+  await page.keyboard.press("Escape");
+
+  await scrollToLowerUnwrappedDiffRows(page);
+  await page.getByTestId("changes-toggle-view-mode").click();
+  await expect(page.getByTestId("diff-folder-src")).toBeVisible();
+  await expect(page.getByTestId("diff-file-0")).toBeVisible();
+
+  await page.getByTestId("diff-folder-src-toggle").click();
+  await expect(page.getByTestId("diff-file-0")).toHaveCount(0);
+
+  await page.getByTestId("changes-toggle-view-mode").click();
+  await expectFlatFileList(page);
+});
+
 test("changes diff keeps unwrapped gutter and code rows aligned after code size changes", async ({
   page,
 }) => {
@@ -266,13 +298,24 @@ async function useUnwrappedDiffLines(page: Page): Promise<void> {
     ({ preferencesKey }) => {
       localStorage.setItem(
         preferencesKey,
-        JSON.stringify({ layout: "unified", wrapLines: false, hideWhitespace: false }),
+        JSON.stringify({
+          layout: "unified",
+          viewMode: "flat",
+          wrapLines: false,
+          hideWhitespace: false,
+        }),
       );
     },
     { preferencesKey: CHANGES_PREFERENCES_KEY },
   );
 }
 
+async function expectFlatFileList(page: Page): Promise<void> {
+  await expect(page.locator('[data-testid^="diff-folder-"]')).toHaveCount(0);
+  await expect(page.getByTestId("diff-file-0")).toContainText("use-mounted-tab-set.ts");
+  await expect(page.getByTestId("diff-file-0")).toContainText("src");
+}
+
 async function expectDiffCodeFontSize(page: Page, fontSize: number): Promise<void> {
   await expect
     .poll(async () => {

packages/app/metro.config.cjs

@@ -14,6 +14,12 @@ const customWebPlatform = (process.env.PASEO_WEB_PLATFORM ?? "")
 
 const config = getDefaultConfig(projectRoot);
 const defaultResolveRequest = config.resolver.resolveRequest ?? resolve;
+
+// Keep app exports deterministic across dev machines and CI. Metro's Watchman
+// crawler behavior depends on the host Watchman build/capabilities, while the
+// node crawler is the path used when Watchman is absent.
+config.resolver.useWatchman = false;
+
 const escapedAppSrcRoot = appSrcRoot
   .split(path.sep)
   .map((segment) => segment.replace(/[|\\{}()[\]^$+*?.]/g, "\\$&"))

packages/app/src/agent-stream/view.tsx

@@ -52,6 +52,7 @@ import type { AgentScreenAgent } from "@/hooks/use-agent-screen-state-machine";
 import { useSessionStore } from "@/stores/session-store";
 import { useFileExplorerActions } from "@/hooks/use-file-explorer-actions";
 import { useLoadOlderAgentHistory } from "@/hooks/use-load-older-agent-history";
+import { useSettings } from "@/hooks/use-settings";
 import type { ToastApi } from "@/components/toast-host";
 import type { DaemonClient } from "@getpaseo/client/internal/daemon-client";
 import { ToolCallDetailsContent } from "@/components/tool-call-details";
@@ -318,6 +319,7 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
   ) {
     const { t } = useTranslation();
     const router = useRouter();
+    const autoExpandReasoning = useSettings((settings) => settings.autoExpandReasoning);
     const viewportRef = useRef<StreamViewportHandle | null>(null);
     const isMobile = useIsCompactFormFactor();
     const streamRenderStrategy = useMemo(
@@ -633,10 +635,12 @@ const AgentStreamViewComponent = forwardRef<AgentStreamViewHandle, AgentStreamVi
             args={item.text}
             status={item.status === "ready" ? "completed" : "executing"}
             isLastInSequence={layoutItem.isLastInToolSequence}
+            defaultExpanded={autoExpandReasoning}
+            forceInline={autoExpandReasoning}
           />
         );
       },
-      [setInlineDetailsExpanded],
+      [autoExpandReasoning, setInlineDetailsExpanded],
     );
 
     const renderToolCallItem = useCallback(

packages/app/src/app/_layout.tsx

@@ -37,6 +37,7 @@ import { LeftSidebar } from "@/components/left-sidebar";
 import { CompactExplorerSidebarHost } from "@/components/compact-explorer-sidebar-host";
 import { ProjectPickerModal } from "@/components/project-picker-modal";
 import { ProviderSettingsHost } from "@/components/provider-settings-host";
+import { RootErrorBoundary } from "@/components/root-error-boundary";
 import { WorkspaceSetupDialog } from "@/components/workspace-setup-dialog";
 import { WorkspaceShortcutTargetsSubscriber } from "@/components/workspace-shortcut-targets-subscriber";
 import { FloatingPanelPortalHost } from "@/components/ui/floating-panel-portal";
@@ -998,31 +999,27 @@ function RuntimeProviders({ children }: { children: ReactNode }) {
   );
 }
 
-// PortalProvider must stay inside normal app-wide context providers here.
+// PortalProvider must stay inside normal app-wide context providers.
 // `@gorhom/portal` renders portaled children at the host's location in the
 // tree, so any context a portaled sheet might consume (QueryClient, theme,
-// auth, settings, …) must wrap PortalProvider — not be wrapped by it.
+// auth, settings, ...) must wrap PortalProvider, not be wrapped by it.
 // BottomSheetModalProvider is the exception: Gorhom modals consume portal
 // context and need one shared provider for sibling sheets to stack.
 function RootProviders({ children }: { children: ReactNode }) {
   return (
-    <QueryProvider>
-      <I18nProvider>
-        <SafeAreaProvider>
-          <KeyboardProvider>
-            <KeyboardShiftProvider>
-              <PortalProvider>
-                <BottomSheetModalProvider>{children}</BottomSheetModalProvider>
-              </PortalProvider>
-            </KeyboardShiftProvider>
-          </KeyboardProvider>
-        </SafeAreaProvider>
-      </I18nProvider>
-    </QueryProvider>
+    <SafeAreaProvider>
+      <KeyboardProvider>
+        <KeyboardShiftProvider>
+          <PortalProvider>
+            <BottomSheetModalProvider>{children}</BottomSheetModalProvider>
+          </PortalProvider>
+        </KeyboardShiftProvider>
+      </KeyboardProvider>
+    </SafeAreaProvider>
   );
 }
 
-export default function RootLayout() {
+function RootAppTree() {
   return (
     <GestureHandlerRootView style={flexStyle}>
       <View style={layoutStyles.surfaceFill}>
@@ -1036,6 +1033,18 @@ export default function RootLayout() {
   );
 }
 
+export default function RootLayout() {
+  return (
+    <QueryProvider>
+      <I18nProvider>
+        <RootErrorBoundary>
+          <RootAppTree />
+        </RootErrorBoundary>
+      </I18nProvider>
+    </QueryProvider>
+  );
+}
+
 const layoutStyles = StyleSheet.create((theme) => ({
   surfaceFill: {
     flex: 1,

packages/app/src/components/context-window-meter.tsx

@@ -117,7 +117,7 @@ export function ContextWindowMeter({
     (nextOpen: boolean) => {
       setIsTooltipOpen(nextOpen);
       if (nextOpen) {
-        void refreshProviderUsage();
+        void refreshProviderUsage().catch(() => {});
       }
     },
     [refreshProviderUsage],

packages/app/src/components/file-explorer-pane.tsx

@@ -19,7 +19,6 @@ import * as Clipboard from "expo-clipboard";
 import { SvgXml } from "react-native-svg";
 import {
   ChevronDown,
-  ChevronRight,
   Copy,
   Download,
   Eye,
@@ -28,6 +27,7 @@ import {
   RotateCw,
 } from "lucide-react-native";
 import { getFileIconSvg } from "@/components/material-file-icons";
+import { TreeChevron, TreeIndentGuides, TREE_INDENT_PER_LEVEL } from "@/components/tree-primitives";
 import { LoadingSpinner } from "@/components/ui/loading-spinner";
 import type { AgentFileExplorerState, ExplorerEntry } from "@/stores/session-store";
 import { useHosts } from "@/runtime/host-runtime";
@@ -55,8 +55,6 @@ const SORT_OPTIONS: { value: SortOption }[] = [
   { value: "size" },
 ];
 
-const INDENT_PER_LEVEL = 16;
-
 function formatFileSize({ size }: { size: number }): string {
   if (size < 1024) {
     return `${size} B`;
@@ -129,7 +127,7 @@ function TreeRowItem({
   const pressableStyle = useCallback(
     ({ hovered, pressed }: PressableStateCallbackType & { hovered?: boolean }) => [
       styles.entryRow,
-      { paddingLeft: theme.spacing[2] + depth * INDENT_PER_LEVEL },
+      { paddingLeft: theme.spacing[2] + depth * TREE_INDENT_PER_LEVEL },
       (Boolean(hovered) || pressed || isSelected) && styles.entryRowActive,
     ],
     [depth, isSelected, theme.spacing],
@@ -143,11 +141,6 @@ function TreeRowItem({
     onDownloadEntry(entry);
   }, [onDownloadEntry, entry]);
 
-  const chevronStyle = useMemo(
-    () => [styles.chevron, isExpanded && styles.chevronExpanded],
-    [isExpanded],
-  );
-
   const copyLeading = useMemo(
     () => <Copy size={14} color={theme.colors.foregroundMuted} />,
     [theme.colors.foregroundMuted],
@@ -159,7 +152,7 @@ function TreeRowItem({
 
   return (
     <Pressable onPress={handlePress} style={pressableStyle}>
-      {depth > 0 && Array.from({ length: depth }, (_, i) => <IndentGuide key={i} index={i} />)}
+      <TreeIndentGuides depth={depth} />
       <View style={styles.entryInfo}>
         <View style={styles.entryIcon}>
           {(() => {
@@ -167,11 +160,7 @@ function TreeRowItem({
               return <SvgXml xml={getFileIconSvg(entry.name)} width={16} height={16} />;
             }
             if (loading) return <ActivityIndicator size="small" />;
-            return (
-              <View style={chevronStyle}>
-                <ChevronRight size={16} color={theme.colors.foregroundMuted} />
-              </View>
-            );
+            return <TreeChevron expanded={isExpanded} />;
           })()}
         </View>
         <Text style={styles.entryName} numberOfLines={1}>
@@ -1149,13 +1138,6 @@ const styles = StyleSheet.create((theme) => ({
   entryRowActive: {
     backgroundColor: theme.colors.surfaceSidebarHover,
   },
-  indentGuide: {
-    position: "absolute",
-    top: 0,
-    bottom: 0,
-    width: 1,
-    backgroundColor: theme.colors.surface2,
-  },
   entryInfo: {
     flex: 1,
     flexDirection: "row",
@@ -1163,16 +1145,6 @@ const styles = StyleSheet.create((theme) => ({
     gap: theme.spacing[2],
     minWidth: 0,
   },
-  chevron: {
-    width: 16,
-    height: 16,
-    alignItems: "center",
-    justifyContent: "center",
-    flexShrink: 0,
-  },
-  chevronExpanded: {
-    transform: [{ rotate: "90deg" }],
-  },
   entryIcon: {
     flexShrink: 0,
   },
@@ -1302,16 +1274,3 @@ const styles = StyleSheet.create((theme) => ({
 }));
 
 const TREE_PANE_CONTAINER_STYLE = [styles.treePane, styles.treePaneFill];
-
-interface IndentGuideProps {
-  index: number;
-}
-
-function IndentGuide({ index }: IndentGuideProps) {
-  const { theme } = useUnistyles();
-  const guideStyle = useMemo(
-    () => [styles.indentGuide, { left: theme.spacing[3] + index * INDENT_PER_LEVEL + 4 }],
-    [index, theme.spacing],
-  );
-  return <View style={guideStyle} />;
-}

packages/app/src/components/message.tsx

@@ -3038,6 +3038,8 @@ interface ToolCallProps {
   onInlineDetailsHoverChange?: (hovered: boolean) => void;
   onInlineDetailsExpandedChange?: (expanded: boolean) => void;
   onOpenFilePath?: (filePath: string) => void;
+  defaultExpanded?: boolean;
+  forceInline?: boolean;
 }
 
 export const ToolCall = memo(function ToolCall({
@@ -3054,11 +3056,14 @@ export const ToolCall = memo(function ToolCall({
   onInlineDetailsHoverChange,
   onInlineDetailsExpandedChange,
   onOpenFilePath,
+  defaultExpanded,
+  forceInline = false,
 }: ToolCallProps) {
   const { openToolCall } = useToolCallSheet();
-  const [isExpanded, setIsExpanded] = useState(false);
+  const [isExpanded, setIsExpanded] = useState(defaultExpanded ?? false);
 
   const isMobile = useIsCompactFormFactor();
+  const shouldRenderInline = !isMobile || forceInline;
 
   const effectiveDetail = useMemo<ToolCallDetail | undefined>(() => {
     if (detail) {
@@ -3096,7 +3101,7 @@ export const ToolCall = memo(function ToolCall({
   }, [presentation.openFilePath, onOpenFilePath]);
 
   const handleToggle = useCallback(() => {
-    if (isMobile) {
+    if (!shouldRenderInline) {
       openToolCall({
         displayName: presentation.displayName,
         summary: presentation.summary,
@@ -3109,7 +3114,7 @@ export const ToolCall = memo(function ToolCall({
       setIsExpanded((prev) => !prev);
     }
   }, [
-    isMobile,
+    shouldRenderInline,
     openToolCall,
     presentation.displayName,
     presentation.summary,
@@ -3120,22 +3125,22 @@ export const ToolCall = memo(function ToolCall({
   ]);
 
   useEffect(() => {
-    if (!onInlineDetailsHoverChange || isMobile || isExpanded) {
+    if (!onInlineDetailsHoverChange || !shouldRenderInline || isExpanded) {
       return;
     }
     onInlineDetailsHoverChange(false);
-  }, [isExpanded, isMobile, onInlineDetailsHoverChange]);
+  }, [isExpanded, shouldRenderInline, onInlineDetailsHoverChange]);
 
   useEffect(() => {
     if (!onInlineDetailsExpandedChange) {
       return;
     }
-    if (isMobile) {
+    if (!shouldRenderInline) {
       onInlineDetailsExpandedChange(false);
       return;
     }
     onInlineDetailsExpandedChange(isExpanded);
-  }, [isExpanded, isMobile, onInlineDetailsExpandedChange]);
+  }, [isExpanded, shouldRenderInline, onInlineDetailsExpandedChange]);
 
   useEffect(() => {
     if (!onInlineDetailsExpandedChange) {
@@ -3148,7 +3153,7 @@ export const ToolCall = memo(function ToolCall({
 
   // Render inline details for desktop
   const renderDetails = useCallback(() => {
-    if (isMobile) return null;
+    if (!shouldRenderInline) return null;
     return (
       <ToolCallDetailsContent
         detail={effectiveDetail}
@@ -3157,7 +3162,7 @@ export const ToolCall = memo(function ToolCall({
         showLoadingSkeleton={presentation.isLoadingDetails}
       />
     );
-  }, [isMobile, effectiveDetail, presentation.errorText, presentation.isLoadingDetails]);
+  }, [shouldRenderInline, effectiveDetail, presentation.errorText, presentation.isLoadingDetails]);
 
   if (presentation.isPlan && effectiveDetail?.type === "plan") {
     return (
@@ -3175,10 +3180,10 @@ export const ToolCall = memo(function ToolCall({
       label={presentation.displayName}
       secondaryLabel={presentation.summary}
       icon={presentation.icon}
-      isExpanded={!isMobile && isExpanded}
+      isExpanded={shouldRenderInline && isExpanded}
       onToggle={presentation.canOpenDetails ? handleToggle : undefined}
       onOpenFile={handleOpenFile}
-      renderDetails={presentation.canOpenDetails && !isMobile ? renderDetails : undefined}
+      renderDetails={presentation.canOpenDetails && shouldRenderInline ? renderDetails : undefined}
       isLoading={status === "running" || status === "executing"}
       isError={status === "failed"}
       isLastInSequence={isLastInSequence}
@@ -3200,5 +3205,7 @@ function areToolCallPropsEqual(previous: ToolCallProps, next: ToolCallProps) {
   if (previous.isLastInSequence !== next.isLastInSequence) return false;
   if (previous.disableOuterSpacing !== next.disableOuterSpacing) return false;
   if (previous.onOpenFilePath !== next.onOpenFilePath) return false;
+  if (previous.defaultExpanded !== next.defaultExpanded) return false;
+  if (previous.forceInline !== next.forceInline) return false;
   return true;
 }

packages/app/src/components/root-error-boundary.tsx

@@ -0,0 +1,157 @@
+import React, { Component, Fragment, type ErrorInfo, type ReactNode } from "react";
+import { Pressable, ScrollView, Text, View } from "react-native";
+import type { PressableStateCallbackType, StyleProp, ViewStyle } from "react-native";
+import { useTranslation } from "react-i18next";
+import { StyleSheet } from "react-native-unistyles";
+import { formatCaughtValue } from "./root-error-details";
+
+interface RootErrorBoundaryProps {
+  children: ReactNode;
+}
+
+interface RootErrorBoundaryState {
+  error: string | null;
+  resetKey: number;
+}
+
+export class RootErrorBoundary extends Component<RootErrorBoundaryProps, RootErrorBoundaryState> {
+  state: RootErrorBoundaryState = {
+    error: null,
+    resetKey: 0,
+  };
+
+  static getDerivedStateFromError(error: unknown): Partial<RootErrorBoundaryState> {
+    return { error: formatCaughtValue(error) };
+  }
+
+  componentDidCatch(error: unknown, errorInfo: ErrorInfo) {
+    console.error("[RootErrorBoundary] Unhandled render error", {
+      error: formatCaughtValue(error),
+      componentStack: errorInfo.componentStack,
+    });
+  }
+
+  retry = () => {
+    this.setState(({ resetKey }) => ({
+      error: null,
+      resetKey: resetKey + 1,
+    }));
+  };
+
+  render() {
+    const { error, resetKey } = this.state;
+    if (error !== null) {
+      return <RootErrorFallback error={error} onRetry={this.retry} />;
+    }
+
+    return <Fragment key={resetKey}>{this.props.children}</Fragment>;
+  }
+}
+
+interface RootErrorFallbackProps {
+  error: string;
+  onRetry: () => void;
+}
+
+function RootErrorFallback({ error, onRetry }: RootErrorFallbackProps) {
+  const { t } = useTranslation();
+
+  return (
+    <ScrollView
+      style={styles.container}
+      contentContainerStyle={styles.contentContainer}
+      testID="root-error-boundary"
+    >
+      <View style={styles.content}>
+        <Text style={styles.kicker}>{t("rootError.kicker")}</Text>
+        <Text style={styles.title}>{t("rootError.title")}</Text>
+        <Text style={styles.body}>{t("rootError.body")}</Text>
+        <View style={styles.messageBox}>
+          <Text style={styles.messageLabel}>{t("rootError.details")}</Text>
+          <Text style={styles.message}>{error}</Text>
+        </View>
+        <Pressable
+          accessibilityRole="button"
+          onPress={onRetry}
+          style={retryButtonStyle}
+          testID="root-error-boundary-retry"
+        >
+          <Text style={styles.retryButtonText}>{t("common.actions.retry")}</Text>
+        </Pressable>
+      </View>
+    </ScrollView>
+  );
+}
+
+function retryButtonStyle({ pressed }: PressableStateCallbackType): StyleProp<ViewStyle> {
+  return [styles.retryButton, pressed ? styles.retryButtonPressed : null];
+}
+
+const styles = StyleSheet.create((theme) => ({
+  container: {
+    flex: 1,
+    backgroundColor: theme.colors.surface0,
+  },
+  contentContainer: {
+    flexGrow: 1,
+    justifyContent: "center",
+    paddingHorizontal: theme.spacing[6],
+    paddingVertical: theme.spacing[8],
+  },
+  content: {
+    alignSelf: "center",
+    width: "100%",
+    maxWidth: 520,
+    gap: theme.spacing[4],
+  },
+  kicker: {
+    color: theme.colors.destructive,
+    fontSize: theme.fontSize.sm,
+    fontWeight: theme.fontWeight.semibold,
+  },
+  title: {
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.xl,
+    fontWeight: theme.fontWeight.semibold,
+  },
+  body: {
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.base,
+    lineHeight: 22,
+  },
+  messageBox: {
+    gap: theme.spacing[2],
+    borderWidth: 1,
+    borderColor: theme.colors.borderAccent,
+    borderRadius: theme.borderRadius.lg,
+    backgroundColor: theme.colors.surface1,
+    padding: theme.spacing[4],
+  },
+  messageLabel: {
+    color: theme.colors.foregroundMuted,
+    fontSize: theme.fontSize.xs,
+    fontWeight: theme.fontWeight.semibold,
+  },
+  message: {
+    color: theme.colors.foreground,
+    fontSize: theme.fontSize.sm,
+    lineHeight: 20,
+  },
+  retryButton: {
+    alignSelf: "flex-start",
+    minHeight: 40,
+    justifyContent: "center",
+    borderRadius: theme.borderRadius.md,
+    backgroundColor: theme.colors.accent,
+    paddingHorizontal: theme.spacing[4],
+    paddingVertical: theme.spacing[2],
+  },
+  retryButtonPressed: {
+    opacity: 0.85,
+  },
+  retryButtonText: {
+    color: theme.colors.accentForeground,
+    fontSize: theme.fontSize.sm,
+    fontWeight: theme.fontWeight.semibold,
+  },
+}));

packages/app/src/components/root-error-details.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { formatCaughtValue } from "./root-error-details";
+
+describe("formatCaughtValue", () => {
+  it("preserves details for Error values", () => {
+    class RouteRenderError extends Error {
+      code = "E_ROUTE_RENDER";
+      cause = "workspace route";
+
+      constructor() {
+        super("route render exploded");
+        this.name = "RouteRenderError";
+        this.stack = "RouteRenderError: route render exploded\n    at WorkspaceRoute";
+      }
+    }
+
+    const details = formatCaughtValue(new RouteRenderError());
+
+    expect(details).toContain("Name: RouteRenderError");
+    expect(details).toContain("Message: route render exploded");
+    expect(details).toContain("Stack:");
+    expect(details).toContain("RouteRenderError: route render exploded");
+    expect(details).toContain("Cause:");
+    expect(details).toContain("workspace route");
+    expect(details).toContain("E_ROUTE_RENDER");
+  });
+
+  it("does not duplicate aggregate errors as custom fields", () => {
+    const error = new AggregateError([new Error("first failure")], "multiple failures");
+    const details = formatCaughtValue(error);
+
+    expect(details).toContain("Errors:");
+    expect(details).toContain("first failure");
+    expect(details).not.toContain("Fields:");
+  });
+
+  it("preserves null aggregate error values", () => {
+    class ErrorWithNullableErrors extends Error {
+      errors = null;
+    }
+
+    const details = formatCaughtValue(new ErrorWithNullableErrors("nullable errors"));
+
+    expect(details).toContain("Errors:\nnull");
+    expect(details).not.toContain("Fields:");
+  });
+
+  it("does not throw for malformed Error text fields", () => {
+    const error = new Error("fallback");
+    Object.defineProperties(error, {
+      name: { configurable: true, value: null },
+      message: { configurable: true, value: 42 },
+      stack: { configurable: true, value: { frame: "bad stack" } },
+    });
+
+    const details = formatCaughtValue(error);
+
+    expect(details).toContain("Name: null");
+    expect(details).toContain("Message: 42");
+    expect(details).toContain('"frame": "bad stack"');
+  });
+
+  it("marks recursive Error causes", () => {
+    const error = new Error("self cause");
+    Object.defineProperty(error, "cause", { configurable: true, value: error });
+
+    const details = formatCaughtValue(error);
+
+    expect(details).toContain("Cause:\n[Circular Error]");
+  });
+
+  it("returns fallback details when Error properties throw", () => {
+    const error = new Error("fallback");
+    Object.defineProperty(error, "message", {
+      configurable: true,
+      get() {
+        throw new Error("bad message getter");
+      },
+    });
+
+    const details = formatCaughtValue(error);
+
+    expect(details).toContain("[Unserializable value]");
+    expect(details).toContain("Details unavailable:");
+    expect(details).toContain("Error: bad message getter");
+  });
+
+  it("renders string thrown values as the string", () => {
+    expect(formatCaughtValue("plain failure")).toBe("plain failure");
+  });
+
+  it("preserves empty string thrown values", () => {
+    expect(formatCaughtValue("")).toBe("");
+  });
+
+  it("renders numeric thrown values without extra category text", () => {
+    const details = formatCaughtValue(42);
+
+    expect(details).toBe("42");
+    expect(details).not.toContain("non-Error");
+  });
+
+  it("renders circular objects as JSON with circular markers", () => {
+    const value: { label: string; self?: unknown } = { label: "loop" };
+    value.self = value;
+
+    expect(formatCaughtValue(value)).toBe('{\n  "label": "loop",\n  "self": "[Circular]"\n}');
+  });
+});

packages/app/src/components/root-error-details.ts

@@ -0,0 +1,155 @@
+export function formatCaughtValue(value: unknown): string {
+  try {
+    return formatCaughtValueWithSeenErrors(value, new WeakSet<Error>());
+  } catch (formattingError) {
+    return formatFormattingFailure(value, formattingError);
+  }
+}
+
+function formatCaughtValueWithSeenErrors(value: unknown, seenErrors: WeakSet<Error>): string {
+  if (value instanceof Error) {
+    return formatError(value, seenErrors);
+  }
+
+  if (typeof value === "string") {
+    return value;
+  }
+
+  if (value === null || value === undefined) {
+    return safeString(value);
+  }
+
+  if (typeof value !== "object" && typeof value !== "function") {
+    return safeString(value);
+  }
+
+  return stringifyJson(value, seenErrors) ?? safeString(value);
+}
+
+function formatError(error: Error, seenErrors: WeakSet<Error>): string {
+  if (seenErrors.has(error)) {
+    return "[Circular Error]";
+  }
+
+  seenErrors.add(error);
+  const sections: string[] = [];
+  const name = formatErrorTextProperty(Reflect.get(error, "name"), seenErrors);
+  const message = formatErrorTextProperty(Reflect.get(error, "message"), seenErrors);
+  const stack = formatErrorTextProperty(Reflect.get(error, "stack"), seenErrors);
+
+  if (name) {
+    sections.push(`Name: ${name}`);
+  }
+  if (message) {
+    sections.push(`Message: ${message}`);
+  }
+  if (stack) {
+    sections.push(`Stack:\n${stack}`);
+  }
+
+  const errorCause = getErrorCause(error);
+  if (errorCause.hasCause) {
+    sections.push(`Cause:\n${formatCaughtValueWithSeenErrors(errorCause.value, seenErrors)}`);
+  }
+
+  const aggregateErrors = getAggregateErrors(error);
+  if (aggregateErrors.hasErrors) {
+    sections.push(`Errors:\n${formatCaughtValueWithSeenErrors(aggregateErrors.value, seenErrors)}`);
+  }
+
+  const fields = getErrorFields(error);
+  if (fields !== null) {
+    sections.push(`Fields:\n${stringifyJson(fields, seenErrors) ?? safeString(fields)}`);
+  }
+
+  seenErrors.delete(error);
+  return sections.join("\n\n") || safeString(error);
+}
+
+function formatErrorTextProperty(value: unknown, seenErrors: WeakSet<Error>): string | null {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed || null;
+  }
+  if (value === undefined) {
+    return null;
+  }
+  return stringifyJson(value, seenErrors) ?? safeString(value);
+}
+
+function getErrorCause(error: Error): { hasCause: boolean; value: unknown } {
+  if (!Reflect.has(error, "cause")) {
+    return { hasCause: false, value: null };
+  }
+  return { hasCause: true, value: Reflect.get(error, "cause") };
+}
+
+function getAggregateErrors(error: Error): { hasErrors: boolean; value: unknown } {
+  if (!Reflect.has(error, "errors")) {
+    return { hasErrors: false, value: null };
+  }
+  return { hasErrors: true, value: Reflect.get(error, "errors") };
+}
+
+function getErrorFields(error: Error): Record<string, unknown> | null {
+  const fields: Record<string, unknown> = {};
+  for (const key of Object.keys(error)) {
+    if (
+      key === "name" ||
+      key === "message" ||
+      key === "stack" ||
+      key === "cause" ||
+      key === "errors"
+    ) {
+      continue;
+    }
+    fields[key] = Reflect.get(error, key);
+  }
+
+  return Object.keys(fields).length > 0 ? fields : null;
+}
+
+function stringifyJson(value: unknown, seenErrors: WeakSet<Error>): string | null {
+  const seen = new WeakSet<object>();
+  try {
+    const serialized = JSON.stringify(
+      value,
+      (_key, nestedValue: unknown) => {
+        if (nestedValue instanceof Error) {
+          return formatError(nestedValue, seenErrors);
+        }
+        if (typeof nestedValue === "bigint") {
+          return String(nestedValue);
+        }
+        if (nestedValue !== null && typeof nestedValue === "object") {
+          if (seen.has(nestedValue)) {
+            return "[Circular]";
+          }
+          seen.add(nestedValue);
+        }
+        return nestedValue;
+      },
+      2,
+    );
+    return typeof serialized === "string" ? serialized : null;
+  } catch {
+    return null;
+  }
+}
+
+function safeString(value: unknown): string {
+  try {
+    return String(value);
+  } catch {
+    return "[Unserializable value]";
+  }
+}
+
+function formatFormattingFailure(value: unknown, formattingError: unknown): string {
+  const valueText = safeString(value);
+  const formattingErrorText = safeString(formattingError);
+  if (formattingErrorText === "[Unserializable value]") {
+    return valueText;
+  }
+  return `${valueText}\n\nDetails unavailable:\n${formattingErrorText}`;
+}

packages/app/src/components/tree-primitives.tsx

@@ -0,0 +1,82 @@
+import { useMemo } from "react";
+import { View } from "react-native";
+import { StyleSheet, withUnistyles } from "react-native-unistyles";
+import { ChevronRight } from "lucide-react-native";
+import { SPACING, type Theme } from "@/styles/theme";
+import { inlineUnistylesStyle } from "@/styles/unistyles-inline-style";
+
+// Shared presentation primitives for the app's directory trees. Both the Files
+// explorer (server-loaded listings) and the Changes view (client-built from diff
+// paths) render different data, but their ROWS should look identical — same
+// indentation, guide lines, and chevron. Keep those here so the two trees can't
+// drift apart.
+export const TREE_INDENT_PER_LEVEL = 16;
+
+/** Left padding for a tree row at `depth`. Shared by folder rows and file headers
+ * in the Changes tree so their indentation can't drift apart. */
+export function treeRowPaddingLeft(depth: number): number {
+  return SPACING[3] + depth * TREE_INDENT_PER_LEVEL;
+}
+
+const foregroundMutedIconColorMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
+
+const ThemedChevronRight = withUnistyles(ChevronRight);
+
+/**
+ * Vertical guide lines connecting nested rows to their ancestors — one line per
+ * ancestor depth level, positioned absolutely within the (relative) row. Renders
+ * nothing at depth 0.
+ */
+export function TreeIndentGuides({ depth }: { depth: number }) {
+  const guides = useMemo(
+    () =>
+      Array.from({ length: depth }, (_, index) => ({
+        key: index,
+        style: [
+          styles.indentGuide,
+          inlineUnistylesStyle({ left: SPACING[3] + index * TREE_INDENT_PER_LEVEL + 4 }),
+        ],
+      })),
+    [depth],
+  );
+  return (
+    <>
+      {guides.map((guide) => (
+        <View key={guide.key} style={guide.style} pointerEvents="none" />
+      ))}
+    </>
+  );
+}
+
+/** Rotating disclosure chevron for a directory row (points right; rotates down when expanded). */
+export function TreeChevron({ expanded }: { expanded: boolean }) {
+  return (
+    <View style={expanded ? CHEVRON_EXPANDED_STYLE : styles.chevron}>
+      <ThemedChevronRight size={16} uniProps={foregroundMutedIconColorMapping} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme: Theme) => ({
+  indentGuide: {
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    width: 1,
+    backgroundColor: theme.colors.surface2,
+  },
+  chevron: {
+    width: 16,
+    height: 16,
+    alignItems: "center",
+    justifyContent: "center",
+    flexShrink: 0,
+  },
+  chevronExpanded: {
+    transform: [{ rotate: "90deg" }],
+  },
+}));
+
+// Stable module-level style ref so TreeChevron passes a constant array, not one created
+// per render — satisfies react-perf (no inline-array prop) without a per-render useMemo.
+const CHEVRON_EXPANDED_STYLE = [styles.chevron, styles.chevronExpanded];

packages/app/src/contexts/voice-context.tsx

@@ -125,6 +125,11 @@ export function VoiceProvider({ children }: VoiceProviderProps) {
       onVolumeLevel: (level) => {
         runtime?.handleCaptureVolume(level);
       },
+      onInterruption: () => {
+        void runtime?.stopVoice().catch((error) => {
+          console.error("[VoiceEngine] Failed to stop after audio interruption:", error);
+        });
+      },
       onError: (error) => {
         console.error("[VoiceEngine] Capture error:", error);
       },

packages/app/src/git/diff-flat-items.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import { buildDiffFlatItems, sumHeightsBefore, type DiffFlatItem } from "./diff-flat-items";
+import type { ParsedDiffFile } from "@/git/use-diff-query";
+
+function createFile(path: string, additions = 1, deletions = 0): ParsedDiffFile {
+  return { path, isNew: false, isDeleted: false, additions, deletions, hunks: [] };
+}
+
+function summarize(items: DiffFlatItem[]): string[] {
+  return items.map((item) => {
+    if (item.type === "folder") {
+      return `${"  ".repeat(item.depth)}[${item.displayName}]${item.collapsed ? " (collapsed)" : ""}`;
+    }
+    const base = item.file.path.split("/").pop();
+    return `${"  ".repeat(item.depth)}${item.type === "body" ? "body:" : ""}${base}`;
+  });
+}
+
+describe("buildDiffFlatItems", () => {
+  const files = [createFile("src/app/a.ts"), createFile("src/app/nested/b.ts")];
+
+  it("emits a body and a sticky index for each expanded file", () => {
+    const { items, stickyHeaderIndices } = buildDiffFlatItems({
+      files: [createFile("a.ts"), createFile("b.ts")],
+      viewMode: "tree",
+      collapsedFolders: new Set(),
+      expandedPaths: new Set(["a.ts"]),
+    });
+    // Root-level files (no folder): header, body (for expanded a.ts), header
+    expect(summarize(items)).toEqual(["a.ts", "body:a.ts", "b.ts"]);
+    // sticky points at the header (index 0), not the body
+    expect(stickyHeaderIndices).toEqual([0]);
+    expect(items[0].type).toBe("header");
+  });
+
+  it("emits the old flat list without folder rows or indentation", () => {
+    const { items, stickyHeaderIndices } = buildDiffFlatItems({
+      files,
+      viewMode: "flat",
+      collapsedFolders: new Set(),
+      expandedPaths: new Set(["src/app/a.ts"]),
+    });
+
+    expect(summarize(items)).toEqual(["a.ts", "body:a.ts", "b.ts"]);
+    expect(stickyHeaderIndices).toEqual([0]);
+    expect(items.every((item) => item.type !== "folder")).toBe(true);
+  });
+
+  it("groups files under compressed folder rows, all expanded by default", () => {
+    const { items } = buildDiffFlatItems({
+      files,
+      viewMode: "tree",
+      collapsedFolders: new Set(),
+      expandedPaths: new Set(),
+    });
+    // dirs sort before files within a level: [nested] precedes a.ts
+    expect(summarize(items)).toEqual(["[src/app]", "  [nested]", "    b.ts", "  a.ts"]);
+  });
+
+  it("collapsing a folder hides its descendants but keeps the row", () => {
+    const { items } = buildDiffFlatItems({
+      files,
+      viewMode: "tree",
+      collapsedFolders: new Set(["src/app/nested"]),
+      expandedPaths: new Set(),
+    });
+    expect(summarize(items)).toEqual(["[src/app]", "  [nested] (collapsed)", "  a.ts"]);
+  });
+
+  it("collapsing an ancestor hides everything below it", () => {
+    const { items } = buildDiffFlatItems({
+      files,
+      viewMode: "tree",
+      collapsedFolders: new Set(["src/app"]),
+      expandedPaths: new Set(),
+    });
+    expect(summarize(items)).toEqual(["[src/app] (collapsed)"]);
+  });
+
+  it("derives sticky indices file-headers-only from the post-collapse list", () => {
+    // dirs-first: [src/app], [nested], b.ts, a.ts. Expanding a.ts puts its
+    // header at index 3, with the body right after.
+    const { items, stickyHeaderIndices } = buildDiffFlatItems({
+      files,
+      viewMode: "tree",
+      collapsedFolders: new Set(),
+      expandedPaths: new Set(["src/app/a.ts"]),
+    });
+    expect(summarize(items)).toEqual([
+      "[src/app]",
+      "  [nested]",
+      "    b.ts",
+      "  a.ts",
+      "  body:a.ts",
+    ]);
+    expect(stickyHeaderIndices).toEqual([3]);
+    for (const idx of stickyHeaderIndices) {
+      expect(items[idx].type).toBe("header");
+    }
+  });
+
+  it("maps tree file rows back to their original files array index", () => {
+    const { items } = buildDiffFlatItems({
+      files,
+      viewMode: "tree",
+      collapsedFolders: new Set(),
+      expandedPaths: new Set(),
+    });
+    // Tree order is b.ts (fileIndex 1) then a.ts (fileIndex 0)
+    const headers = items.filter((i) => i.type === "header");
+    expect(headers.map((h) => (h.type === "header" ? h.fileIndex : -1))).toEqual([1, 0]);
+  });
+});
+
+describe("sumHeightsBefore", () => {
+  const items = buildDiffFlatItems({
+    files: [createFile("src/a.ts"), createFile("src/b.ts")],
+    viewMode: "tree",
+    collapsedFolders: new Set(),
+    expandedPaths: new Set(),
+  }).items; // [folder, a.ts, b.ts]
+
+  const heightFor = (item: DiffFlatItem) => (item.type === "folder" ? 10 : 20);
+
+  it("sums the heights of items before the index, counting folder rows", () => {
+    expect(sumHeightsBefore(items, 0, heightFor)).toBe(0);
+    expect(sumHeightsBefore(items, 1, heightFor)).toBe(10); // folder above a.ts
+    expect(sumHeightsBefore(items, 2, heightFor)).toBe(30); // folder + a.ts above b.ts
+  });
+
+  it("clamps an out-of-range index to the list length", () => {
+    expect(sumHeightsBefore(items, 999, heightFor)).toBe(50);
+  });
+});

packages/app/src/git/diff-flat-items.ts

@@ -0,0 +1,121 @@
+import type { ParsedDiffFile } from "@/git/use-diff-query";
+import {
+  buildDiffTree,
+  compressSingleChildChains,
+  flattenDiffTree,
+  type DiffTreeDirNode,
+} from "@/git/diff-tree";
+
+// The row model for the Changes FlatList. `fileIndex` is the file's index within
+// the (path-sorted) `files` array — a stable identity for testIDs/keys that is
+// independent of folder rows and collapse state. `depth` drives indentation.
+export type DiffFlatItem =
+  | {
+      type: "folder";
+      dirPath: string;
+      displayName: string;
+      depth: number;
+      collapsed: boolean;
+      additions: number;
+      deletions: number;
+    }
+  | { type: "header"; file: ParsedDiffFile; fileIndex: number; isExpanded: boolean; depth: number }
+  | { type: "body"; file: ParsedDiffFile; fileIndex: number; depth: number };
+
+export interface DiffFlatItemsResult {
+  items: DiffFlatItem[];
+  /** Indices into `items` of expanded file headers — folder rows are never sticky. */
+  stickyHeaderIndices: number[];
+}
+
+export interface BuildDiffFlatItemsInput {
+  files: ParsedDiffFile[];
+  viewMode: "flat" | "tree";
+  /** Full uncompressed directory paths that are collapsed (empty = all expanded). */
+  collapsedFolders: ReadonlySet<string>;
+  /** File paths whose diff body is expanded. */
+  expandedPaths: ReadonlySet<string>;
+  /**
+   * Pre-built compressed tree (from the same `files`). Pass it to avoid rebuilding
+   * the tree on every collapse toggle; omitted callers (tests) build it internally.
+   */
+  tree?: DiffTreeDirNode;
+}
+
+/**
+ * Build the FlatList item model plus its sticky-header indices: files grouped
+ * under directory rows, single-child chains compressed, descendants of collapsed
+ * folders omitted.
+ *
+ * Sticky indices are derived from the FINAL (post-collapse) item list and only
+ * ever point at expanded FILE headers, so folder rows can't stack or collide in
+ * the sticky header stack.
+ */
+export function buildDiffFlatItems({
+  files,
+  viewMode,
+  collapsedFolders,
+  expandedPaths,
+  tree,
+}: BuildDiffFlatItemsInput): DiffFlatItemsResult {
+  const items: DiffFlatItem[] = [];
+  const stickyHeaderIndices: number[] = [];
+
+  const pushFile = (file: ParsedDiffFile, fileIndex: number, depth: number): void => {
+    const isExpanded = expandedPaths.has(file.path);
+    items.push({ type: "header", file, fileIndex, isExpanded, depth });
+    if (isExpanded) {
+      stickyHeaderIndices.push(items.length - 1);
+      items.push({ type: "body", file, fileIndex, depth });
+    }
+  };
+
+  if (viewMode === "flat") {
+    for (const [fileIndex, file] of files.entries()) {
+      pushFile(file, fileIndex, 0);
+    }
+    return { items, stickyHeaderIndices };
+  }
+
+  const indexByPath = new Map(files.map((file, index) => [file.path, index]));
+  const compressedTree = tree ?? compressSingleChildChains(buildDiffTree(files));
+  const rows = flattenDiffTree(compressedTree, collapsedFolders);
+
+  for (const row of rows) {
+    if (row.kind === "folder") {
+      items.push({
+        type: "folder",
+        dirPath: row.dirPath,
+        displayName: row.displayName,
+        depth: row.depth,
+        collapsed: collapsedFolders.has(row.dirPath),
+        additions: row.additions,
+        deletions: row.deletions,
+      });
+      continue;
+    }
+    const fileIndex = indexByPath.get(row.file.path);
+    if (fileIndex === undefined) {
+      // Should never happen: the tree is built from the same `files` array.
+      continue;
+    }
+    pushFile(row.file, fileIndex, row.depth);
+  }
+
+  return { items, stickyHeaderIndices };
+}
+
+/** Cumulative height of every item before `index`. Single source of truth for
+ * FlatList's getItemLayout AND the collapse scroll-anchor math. */
+export function sumHeightsBefore(
+  items: DiffFlatItem[],
+  index: number,
+  heightFor: (item: DiffFlatItem) => number,
+): number {
+  let offset = 0;
+  const end = Math.min(index, items.length);
+  for (let i = 0; i < end; i++) {
+    offset += heightFor(items[i]);
+  }
+  return Math.max(0, offset);
+}

packages/app/src/git/diff-folder-row.tsx

@@ -0,0 +1,124 @@
+import { useCallback, useMemo } from "react";
+import {
+  View,
+  Text,
+  Pressable,
+  type LayoutChangeEvent,
+  type PressableStateCallbackType,
+} from "react-native";
+import { StyleSheet } from "react-native-unistyles";
+import { DiffStat } from "@/components/diff-stat";
+import { TreeChevron, TreeIndentGuides, treeRowPaddingLeft } from "@/components/tree-primitives";
+import { type Theme } from "@/styles/theme";
+import { inlineUnistylesStyle } from "@/styles/unistyles-inline-style";
+
+interface DiffFolderRowProps {
+  /** full uncompressed directory path — the collapse identity */
+  dirPath: string;
+  displayName: string;
+  depth: number;
+  collapsed: boolean;
+  additions: number;
+  deletions: number;
+  onToggle: (dirPath: string) => void;
+  onHeightChange?: (height: number) => void;
+  testID?: string;
+}
+
+function folderRowPressableStyle({
+  hovered,
+  pressed,
+}: PressableStateCallbackType & { hovered?: boolean }) {
+  // Subtle background highlight on hover/press, matching the Files explorer rows
+  // (entryRowActive) — no opacity darken.
+  return [styles.folderRow, (Boolean(hovered) || pressed) && styles.folderRowActive];
+}
+
+export function DiffFolderRow({
+  dirPath,
+  displayName,
+  depth,
+  collapsed,
+  additions,
+  deletions,
+  onToggle,
+  onHeightChange,
+  testID,
+}: DiffFolderRowProps) {
+  const handlePress = useCallback(() => {
+    onToggle(dirPath);
+  }, [dirPath, onToggle]);
+
+  const handleLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      onHeightChange?.(event.nativeEvent.layout.height);
+    },
+    [onHeightChange],
+  );
+
+  const leftStyle = useMemo(
+    () => [styles.left, inlineUnistylesStyle({ paddingLeft: treeRowPaddingLeft(depth) })],
+    [depth],
+  );
+
+  const accessibilityState = useMemo(() => ({ expanded: !collapsed }), [collapsed]);
+
+  return (
+    <View style={styles.container} onLayout={handleLayout} testID={testID}>
+      <TreeIndentGuides depth={depth} />
+      <Pressable
+        onPress={handlePress}
+        style={folderRowPressableStyle}
+        accessibilityRole="button"
+        accessibilityState={accessibilityState}
+        testID={testID ? `${testID}-toggle` : undefined}
+      >
+        <View style={leftStyle}>
+          <TreeChevron expanded={!collapsed} />
+          <Text style={styles.folderName} numberOfLines={1}>
+            {displayName}
+          </Text>
+        </View>
+        <View style={styles.right}>
+          <DiffStat additions={additions} deletions={deletions} />
+        </View>
+      </Pressable>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((theme: Theme) => ({
+  container: {
+    overflow: "hidden",
+  },
+  folderRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    paddingRight: theme.spacing[2],
+    paddingVertical: theme.spacing[2],
+    gap: theme.spacing[1],
+    minWidth: 0,
+  },
+  folderRowActive: {
+    backgroundColor: theme.colors.surfaceSidebarHover,
+  },
+  left: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing[1],
+    flex: 1,
+    minWidth: 0,
+  },
+  right: {
+    flexDirection: "row",
+    alignItems: "center",
+    flexShrink: 0,
+  },
+  folderName: {
+    fontSize: theme.fontSize.sm,
+    fontWeight: theme.fontWeight.normal,
+    color: theme.colors.foreground,
+    flexShrink: 1,
+    minWidth: 0,
+  },
+}));

packages/app/src/git/diff-pane.tsx

@@ -36,8 +36,10 @@ import {
   ChevronDown,
   Columns2,
   Download,
+  FolderTree,
   GitCommitHorizontal,
   GitMerge,
+  List,
   ListChevronsDownUp,
   ListChevronsUpDown,
   Pilcrow,
@@ -52,6 +54,12 @@ import {
   type DiffLine,
   type HighlightToken,
 } from "@/git/use-diff-query";
+import { buildDiffFlatItems, sumHeightsBefore, type DiffFlatItem } from "@/git/diff-flat-items";
+import { buildDiffTree, collectDirPaths, compressSingleChildChains } from "@/git/diff-tree";
+import { DiffFolderRow } from "@/git/diff-folder-row";
+import { TreeIndentGuides, treeRowPaddingLeft } from "@/components/tree-primitives";
+import { SvgXml } from "react-native-svg";
+import { getFileIconSvg } from "@/components/material-file-icons";
 import { useCheckoutStatusQuery } from "@/git/use-status-query";
 import { useCheckoutPrStatusQuery } from "@/git/use-pr-status-query";
 import { useChangesPreferences } from "@/hooks/use-changes-preferences";
@@ -191,6 +199,10 @@ function HighlightedText({
 interface DiffFileSectionProps {
   file: ParsedDiffFile;
   isExpanded: boolean;
+  /** Tree indentation level (0 on the flat/mobile path). */
+  depth?: number;
+  /** Show the muted directory suffix (flat list); false inside the folder tree. */
+  showDir?: boolean;
   onToggle: (path: string) => void;
   onHeaderHeightChange?: (path: string, height: number) => void;
   testID?: string;
@@ -889,6 +901,8 @@ function SplitDiffColumn({
 const DiffFileHeader = memo(function DiffFileHeader({
   file,
   isExpanded,
+  depth = 0,
+  showDir = true,
   onToggle,
   onHeaderHeightChange,
   testID,
@@ -940,13 +954,27 @@ const DiffFileHeader = memo(function DiffFileHeader({
     [isExpanded],
   );
 
+  const headerPressableStyle = useCallback(
+    (state: PressableStateCallbackType) =>
+      depth > 0
+        ? [
+            fileHeaderPressableStyle(state),
+            inlineUnistylesStyle({ paddingLeft: treeRowPaddingLeft(depth) }),
+          ]
+        : fileHeaderPressableStyle(state),
+    [depth],
+  );
+
+  const fileName = file.path.split("/").pop() ?? file.path;
+
   return (
     <View style={containerStyle} onLayout={handleLayout} testID={testID}>
+      <TreeIndentGuides depth={depth} />
       <Tooltip delayDuration={300} enabledOnDesktop enabledOnMobile={false}>
         <TooltipTrigger asChild>
           <Pressable
             testID={testID ? `${testID}-toggle` : undefined}
-            style={fileHeaderPressableStyle}
+            style={headerPressableStyle}
             // Android: prevent parent pan/scroll gestures from canceling the tap release.
             cancelable={false}
             onPressIn={handlePressIn}
@@ -954,14 +982,25 @@ const DiffFileHeader = memo(function DiffFileHeader({
             onPress={toggleExpanded}
           >
             <View style={styles.fileHeaderLeft}>
+              {showDir ? null : (
+                <View style={styles.fileIcon}>
+                  <SvgXml xml={getFileIconSvg(fileName)} width={16} height={16} />
+                </View>
+              )}
               <Text style={styles.fileName} numberOfLines={1}>
-                {file.path.split("/").pop()}
-              </Text>
-              <Text style={styles.fileDir} numberOfLines={1}>
-                {file.path.includes("/")
-                  ? ` ${file.path.slice(0, file.path.lastIndexOf("/"))}`
-                  : ""}
+                {fileName}
               </Text>
+              {showDir ? (
+                <Text style={styles.fileDir} numberOfLines={1}>
+                  {file.path.includes("/")
+                    ? ` ${file.path.slice(0, file.path.lastIndexOf("/"))}`
+                    : ""}
+                </Text>
+              ) : (
+                // Flex spacer in tree mode (no dir suffix) so the New/Deleted badge
+                // stays right-aligned next to the diff stats, as in the flat list.
+                <View style={styles.fileDirSpacer} />
+              )}
               {file.isNew && (
                 <View style={styles.newBadge}>
                   <Text style={styles.newBadgeText}>{t("workspace.git.diff.newFile")}</Text>
@@ -1181,7 +1220,6 @@ type PressableStyleFn = (
   state: PressableStateCallbackType & { hovered?: boolean; open?: boolean },
 ) => StyleProp<ViewStyle>;
 
-const foregroundIconColorMapping = (theme: Theme) => ({ color: theme.colors.foreground });
 const foregroundMutedIconColorMapping = (theme: Theme) => ({ color: theme.colors.foregroundMuted });
 
 const ThemedActivityIndicator = withUnistyles(ActivityIndicator);
@@ -1191,6 +1229,8 @@ const ThemedPilcrow = withUnistyles(Pilcrow);
 const ThemedWrapText = withUnistyles(WrapText);
 const ThemedListChevronsDownUp = withUnistyles(ListChevronsDownUp);
 const ThemedListChevronsUpDown = withUnistyles(ListChevronsUpDown);
+const ThemedFolderTree = withUnistyles(FolderTree);
+const ThemedList = withUnistyles(List);
 const ThemedGitCommitHorizontal = withUnistyles(GitCommitHorizontal);
 const ThemedDownload = withUnistyles(Download);
 const ThemedUpload = withUnistyles(Upload);
@@ -1201,101 +1241,89 @@ const ThemedRefreshCcw = withUnistyles(RefreshCcw);
 const ThemedArchive = withUnistyles(Archive);
 const ThemedChevronDown = withUnistyles(ChevronDown);
 
-interface DiffLayoutToggleGroupProps {
+const DIFF_OPTIONS_WHITESPACE_ICON = (
+  <ThemedPilcrow size={14} uniProps={foregroundMutedIconColorMapping} />
+);
+const DIFF_OPTIONS_WRAP_ICON = (
+  <ThemedWrapText size={14} uniProps={foregroundMutedIconColorMapping} />
+);
+
+interface DiffLayoutToggleProps {
   layout: "unified" | "split";
-  unifiedToggleStyle: PressableStyleFn;
-  splitToggleStyle: PressableStyleFn;
-  onUnified: () => void;
-  onSplit: () => void;
-}
-
-function DiffLayoutToggleGroup({
-  layout,
-  unifiedToggleStyle,
-  splitToggleStyle,
-  onUnified,
-  onSplit,
-}: DiffLayoutToggleGroupProps) {
-  const { t } = useTranslation();
-  const unifiedLabel = t("workspace.git.diff.unified");
-  const splitLabel = t("workspace.git.diff.split");
-  return (
-    <View style={styles.toggleButtonGroup}>
-      <Tooltip delayDuration={300}>
-        <TooltipTrigger asChild>
-          <Pressable
-            accessibilityRole="button"
-            accessibilityLabel={unifiedLabel}
-            testID="changes-layout-unified"
-            onPress={onUnified}
-            style={unifiedToggleStyle}
-          >
-            <ThemedAlignJustify
-              size={14}
-              uniProps={
-                layout === "unified" ? foregroundIconColorMapping : foregroundMutedIconColorMapping
-              }
-            />
-          </Pressable>
-        </TooltipTrigger>
-        <TooltipContent side="bottom">
-          <Text style={styles.tooltipText}>{unifiedLabel}</Text>
-        </TooltipContent>
-      </Tooltip>
-      <Tooltip delayDuration={300}>
-        <TooltipTrigger asChild>
-          <Pressable
-            accessibilityRole="button"
-            accessibilityLabel={splitLabel}
-            testID="changes-layout-split"
-            onPress={onSplit}
-            style={splitToggleStyle}
-          >
-            <ThemedColumns2
-              size={14}
-              uniProps={
-                layout === "split" ? foregroundIconColorMapping : foregroundMutedIconColorMapping
-              }
-            />
-          </Pressable>
-        </TooltipTrigger>
-        <TooltipContent side="bottom">
-          <Text style={styles.tooltipText}>{splitLabel}</Text>
-        </TooltipContent>
-      </Tooltip>
-    </View>
-  );
-}
-
-interface DiffWhitespaceToggleProps {
-  hideWhitespace: boolean;
   isMobile: boolean;
   toggleStyle: PressableStyleFn;
   onToggle: () => void;
 }
 
-function DiffWhitespaceToggle({
-  hideWhitespace,
-  isMobile,
-  toggleStyle,
-  onToggle,
-}: DiffWhitespaceToggleProps) {
+function DiffLayoutToggle({ layout, isMobile, toggleStyle, onToggle }: DiffLayoutToggleProps) {
   const { t } = useTranslation();
-  const label = t("workspace.git.diff.hideWhitespace");
+  const label =
+    layout === "unified"
+      ? t("workspace.git.diff.switchToSplit")
+      : t("workspace.git.diff.switchToUnified");
   return (
     <Tooltip delayDuration={300}>
       <TooltipTrigger asChild>
         <Pressable
           accessibilityRole="button"
           accessibilityLabel={label}
-          testID="changes-toggle-whitespace"
+          testID="changes-toggle-layout"
+          onPress={onToggle}
+          style={toggleStyle}
+        >
+          {layout === "unified" ? (
+            <ThemedColumns2 size={isMobile ? 18 : 14} uniProps={foregroundMutedIconColorMapping} />
+          ) : (
+            <ThemedAlignJustify
+              size={isMobile ? 18 : 14}
+              uniProps={foregroundMutedIconColorMapping}
+            />
+          )}
+        </Pressable>
+      </TooltipTrigger>
+      <TooltipContent side="bottom">
+        <Text style={styles.tooltipText}>{label}</Text>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+interface DiffViewModeToggleProps {
+  viewMode: "flat" | "tree";
+  isMobile: boolean;
+  toggleStyle: PressableStyleFn;
+  onToggle: () => void;
+}
+
+function DiffViewModeToggle({
+  viewMode,
+  isMobile,
+  toggleStyle,
+  onToggle,
+}: DiffViewModeToggleProps) {
+  const { t } = useTranslation();
+  const label =
+    viewMode === "flat"
+      ? t("workspace.git.diff.showTreeView")
+      : t("workspace.git.diff.showFlatView");
+  return (
+    <Tooltip delayDuration={300}>
+      <TooltipTrigger asChild>
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={label}
+          testID="changes-toggle-view-mode"
           style={toggleStyle}
           onPress={onToggle}
         >
-          <ThemedPilcrow
-            size={isMobile ? 18 : 14}
-            uniProps={hideWhitespace ? foregroundIconColorMapping : foregroundMutedIconColorMapping}
-          />
+          {viewMode === "flat" ? (
+            <ThemedFolderTree
+              size={isMobile ? 18 : 14}
+              uniProps={foregroundMutedIconColorMapping}
+            />
+          ) : (
+            <ThemedList size={isMobile ? 18 : 14} uniProps={foregroundMutedIconColorMapping} />
+          )}
         </Pressable>
       </TooltipTrigger>
       <TooltipContent side="bottom">
@@ -1306,50 +1334,33 @@ function DiffWhitespaceToggle({
 }
 
 interface DiffFilesToolbarProps {
-  wrapLines: boolean;
-  allExpanded: boolean;
+  allFileDiffsExpanded: boolean;
   isMobile: boolean;
-  wrapLinesToggleStyle: PressableStyleFn;
   expandAllToggleStyle: PressableStyleFn;
-  onToggleWrapLines: () => void;
   onToggleExpandAll: () => void;
 }
 
 function DiffFilesToolbar({
-  wrapLines,
-  allExpanded,
+  allFileDiffsExpanded,
   isMobile,
-  wrapLinesToggleStyle,
   expandAllToggleStyle,
-  onToggleWrapLines,
   onToggleExpandAll,
 }: DiffFilesToolbarProps) {
   const { t } = useTranslation();
-  const wrapLinesLabel = wrapLines
-    ? t("workspace.git.diff.scrollLongLines")
-    : t("workspace.git.diff.wrapLongLines");
-  const expandAllLabel = allExpanded
+  const expandAllLabel = allFileDiffsExpanded
     ? t("workspace.git.diff.collapseAll")
     : t("workspace.git.diff.expandAll");
   return (
     <View style={styles.diffStatusButtons}>
       <Tooltip delayDuration={300}>
         <TooltipTrigger asChild>
-          <Pressable style={wrapLinesToggleStyle} onPress={onToggleWrapLines}>
-            <ThemedWrapText
-              size={isMobile ? 18 : 14}
-              uniProps={wrapLines ? foregroundIconColorMapping : foregroundMutedIconColorMapping}
-            />
-          </Pressable>
-        </TooltipTrigger>
-        <TooltipContent side="bottom">
-          <Text style={styles.tooltipText}>{wrapLinesLabel}</Text>
-        </TooltipContent>
-      </Tooltip>
-      <Tooltip delayDuration={300}>
-        <TooltipTrigger asChild>
-          <Pressable style={expandAllToggleStyle} onPress={onToggleExpandAll}>
-            {allExpanded ? (
+          <Pressable
+            accessibilityRole="button"
+            accessibilityLabel={expandAllLabel}
+            style={expandAllToggleStyle}
+            onPress={onToggleExpandAll}
+          >
+            {allFileDiffsExpanded ? (
               <ThemedListChevronsDownUp
                 size={isMobile ? 18 : 14}
                 uniProps={foregroundMutedIconColorMapping}
@@ -1370,53 +1381,105 @@ function DiffFilesToolbar({
   );
 }
 
-interface DiffRefreshButtonProps {
+interface DiffOptionsMenuProps {
+  hideWhitespace: boolean;
+  isMobile: boolean;
   isRefreshing: boolean;
-  toggleStyle: PressableStyleFn;
-  onPress: () => void;
+  overflowToggleStyle: PressableStyleFn;
+  refreshSupported: boolean;
+  wrapLines: boolean;
+  onRefresh: () => void;
+  onToggleHideWhitespace: () => void;
+  onToggleWrapLines: () => void;
+}
+
+function DiffOptionsMenu({
+  hideWhitespace,
+  isMobile,
+  isRefreshing,
+  overflowToggleStyle,
+  refreshSupported,
+  wrapLines,
+  onRefresh,
+  onToggleHideWhitespace,
+  onToggleWrapLines,
+}: DiffOptionsMenuProps) {
+  const { t } = useTranslation();
+  const whitespaceLabel = hideWhitespace
+    ? t("workspace.git.diff.showWhitespace")
+    : t("workspace.git.diff.hideWhitespace");
+  const wrapLinesLabel = wrapLines
+    ? t("workspace.git.diff.scrollLongLines")
+    : t("workspace.git.diff.wrapLongLines");
+  const optionsLabel = t("workspace.git.diff.options");
+  const refreshIcon = useMemo(
+    () =>
+      isRefreshing ? (
+        <ThemedLoadingSpinner size={ICON_SIZE.sm} uniProps={foregroundMutedIconColorMapping} />
+      ) : (
+        <ThemedRotateCw size={ICON_SIZE.sm} uniProps={foregroundMutedIconColorMapping} />
+      ),
+    [isRefreshing],
+  );
+
+  return (
+    <DropdownMenu>
+      <Tooltip delayDuration={300}>
+        <TooltipTrigger asChild>
+          <DropdownMenuTrigger
+            accessibilityRole="button"
+            accessibilityLabel={optionsLabel}
+            testID="changes-options-menu"
+            style={overflowToggleStyle}
+          >
+            <ThemedChevronDown
+              size={isMobile ? 18 : 14}
+              uniProps={foregroundMutedIconColorMapping}
+            />
+          </DropdownMenuTrigger>
+        </TooltipTrigger>
+        <TooltipContent side="bottom">
+          <Text style={styles.tooltipText}>{optionsLabel}</Text>
+        </TooltipContent>
+      </Tooltip>
+      <DropdownMenuContent align="end" width={240} testID="changes-options-menu-content">
+        <DropdownMenuItem
+          leading={DIFF_OPTIONS_WHITESPACE_ICON}
+          selected={hideWhitespace}
+          testID="changes-toggle-whitespace"
+          onSelect={onToggleHideWhitespace}
+        >
+          {whitespaceLabel}
+        </DropdownMenuItem>
+        <DropdownMenuItem
+          leading={DIFF_OPTIONS_WRAP_ICON}
+          selected={wrapLines}
+          testID="changes-toggle-wrap-lines"
+          onSelect={onToggleWrapLines}
+        >
+          {wrapLinesLabel}
+        </DropdownMenuItem>
+        {refreshSupported ? (
+          <>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem
+              leading={refreshIcon}
+              disabled={isRefreshing}
+              testID="changes-refresh"
+              onSelect={onRefresh}
+            >
+              {isRefreshing ? t("workspace.git.diff.refreshing") : t("workspace.git.diff.refresh")}
+            </DropdownMenuItem>
+          </>
+        ) : null}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
 }
 
 const ThemedRotateCw = withUnistyles(RotateCw);
 const ThemedLoadingSpinner = withUnistyles(LoadingSpinner);
 
-function DiffRefreshButton({ isRefreshing, toggleStyle, onPress }: DiffRefreshButtonProps) {
-  const { t } = useTranslation();
-  const refreshLabel = t("workspace.git.diff.refresh");
-  return (
-    <Tooltip delayDuration={300}>
-      <TooltipTrigger asChild>
-        <Pressable
-          accessibilityRole="button"
-          accessibilityLabel={
-            isRefreshing ? t("workspace.git.diff.refreshing") : t("workspace.git.diff.refreshState")
-          }
-          testID="changes-refresh"
-          style={toggleStyle}
-          onPress={onPress}
-          disabled={isRefreshing}
-        >
-          <View style={styles.refreshIcon}>
-            {isRefreshing ? (
-              <ThemedLoadingSpinner
-                size={ICON_SIZE.sm}
-                uniProps={foregroundMutedIconColorMapping}
-              />
-            ) : (
-              <ThemedRotateCw size={ICON_SIZE.sm} uniProps={foregroundMutedIconColorMapping} />
-            )}
-          </View>
-        </Pressable>
-      </TooltipTrigger>
-      <TooltipContent side="bottom">
-        <Text style={styles.tooltipText}>{refreshLabel}</Text>
-      </TooltipContent>
-    </Tooltip>
-  );
-}
-
-type DiffFlatItem =
-  | { type: "header"; file: ParsedDiffFile; fileIndex: number; isExpanded: boolean }
-  | { type: "body"; file: ParsedDiffFile; fileIndex: number };
 type DiffFlatItemLayoutGetter = NonNullable<FlatListProps<DiffFlatItem>["getItemLayout"]>;
 
 function getUnifiedDiffLineCount(file: ParsedDiffFile): number {
@@ -1679,30 +1742,22 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
   const { preferences: changesPreferences, updatePreferences: updateChangesPreferences } =
     useChangesPreferences();
   const wrapLines = changesPreferences.wrapLines;
+  const viewMode = changesPreferences.viewMode;
   const effectiveLayout = canUseSplitLayout ? changesPreferences.layout : "unified";
 
   const handleToggleWrapLines = useCallback(() => {
     void updateChangesPreferences({ wrapLines: !wrapLines });
   }, [updateChangesPreferences, wrapLines]);
 
-  const handleLayoutChange = useCallback(
-    (nextLayout: "unified" | "split") => {
-      void updateChangesPreferences({ layout: nextLayout });
-    },
-    [updateChangesPreferences],
-  );
-
   const handleToggleHideWhitespace = useCallback(() => {
     void updateChangesPreferences({ hideWhitespace: !changesPreferences.hideWhitespace });
   }, [changesPreferences.hideWhitespace, updateChangesPreferences]);
 
-  const handleLayoutUnified = useCallback(() => {
-    handleLayoutChange("unified");
-  }, [handleLayoutChange]);
-
-  const handleLayoutSplit = useCallback(() => {
-    handleLayoutChange("split");
-  }, [handleLayoutChange]);
+  const handleToggleLayout = useCallback(() => {
+    void updateChangesPreferences({
+      layout: changesPreferences.layout === "unified" ? "split" : "unified",
+    });
+  }, [changesPreferences.layout, updateChangesPreferences]);
 
   const codeFontSize = appSettings.codeFontSize;
   const diffBodyLineHeight = Math.round(codeFontSize * 1.5);
@@ -1719,37 +1774,19 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
   }, [appSettings.monoFontFamily, codeFontSize, diffBodyLineHeight]);
   const diffModeTriggerStyle = useMemo(() => buildDiffModeTriggerStyle(), []);
 
-  const unifiedToggleStyle = useMemo(
-    () =>
-      buildToggleButtonStyle(changesPreferences.layout === "unified", [
-        styles.toggleButton,
-        styles.toggleButtonGroupStart,
-      ]),
-    [changesPreferences.layout],
+  const layoutToggleStyle = useMemo(
+    () => buildToggleButtonStyle(false, styles.expandAllButton),
+    [],
   );
 
-  const splitToggleStyle = useMemo(
-    () =>
-      buildToggleButtonStyle(changesPreferences.layout === "split", [
-        styles.toggleButton,
-        styles.toggleButtonGroupEnd,
-      ]),
-    [changesPreferences.layout],
-  );
-
-  const hideWhitespaceToggleStyle = useMemo(
-    () => buildToggleButtonStyle(changesPreferences.hideWhitespace, styles.expandAllButton),
-    [changesPreferences.hideWhitespace],
-  );
-
-  const wrapLinesToggleStyle = useMemo(
-    () => buildToggleButtonStyle(wrapLines, styles.expandAllButton),
-    [wrapLines],
+  const viewModeToggleStyle = useMemo(
+    () => buildToggleButtonStyle(viewMode === "tree", styles.expandAllButton),
+    [viewMode],
   );
 
   const expandAllToggleStyle = useMemo(() => buildExpandAllButtonStyle(), []);
 
-  const refreshToggleStyle = useMemo(() => buildExpandAllButtonStyle(), []);
+  const overflowToggleStyle = useMemo(() => buildExpandAllButtonStyle(), []);
 
   const toast = useToast();
   const refreshSupported = useSessionStore(
@@ -1892,7 +1929,40 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
     (state) => state.setDiffExpandedPathsForWorkspace,
   );
   const expandedPaths = useMemo(() => new Set(expandedPathsArray ?? []), [expandedPathsArray]);
+  // The Changes view groups files into a directory tree on every form factor,
+  // consistent with the Files explorer (which is also a tree on mobile).
+  const collapsedFoldersArray = usePanelStore((state) =>
+    workspaceStateKey ? state.diffCollapsedFoldersByWorkspace[workspaceStateKey] : undefined,
+  );
+  const setDiffCollapsedFoldersForWorkspace = usePanelStore(
+    (state) => state.setDiffCollapsedFoldersForWorkspace,
+  );
+  // Build the directory tree once per files-change; collapse/expand toggles only
+  // re-flatten it (they don't change tree shape).
+  const compressedTree = useMemo(() => compressSingleChildChains(buildDiffTree(files)), [files]);
+  // Every directory path currently in the tree — used by "collapse all folders" and to
+  // filter stale collapse state.
+  const allFolderPaths = useMemo(() => collectDirPaths(compressedTree), [compressedTree]);
+  const allFolderPathSet = useMemo(() => new Set(allFolderPaths), [allFolderPaths]);
+  // Effective collapsed set: intersect the persisted paths with the folders actually
+  // present, purely at render (no store-syncing effect). A folder that left the diff and
+  // reappears defaults to expanded; toggles write back this pruned set, so the stored
+  // array stays bounded. (empty = all folders expanded, the default)
+  const collapsedFolders = useMemo(
+    () => new Set((collapsedFoldersArray ?? []).filter((path) => allFolderPathSet.has(path))),
+    [collapsedFoldersArray, allFolderPathSet],
+  );
   const diffListRef = useRef<FlatList<DiffFlatItem>>(null);
+  const handleToggleViewMode = useCallback(() => {
+    const nextViewMode = viewMode === "flat" ? "tree" : "flat";
+    if (nextViewMode === "tree") {
+      diffListRef.current?.scrollToOffset({ offset: 0, animated: false });
+      if (workspaceStateKey) {
+        setDiffCollapsedFoldersForWorkspace(workspaceStateKey, []);
+      }
+    }
+    void updateChangesPreferences({ viewMode: nextViewMode });
+  }, [setDiffCollapsedFoldersForWorkspace, updateChangesPreferences, viewMode, workspaceStateKey]);
   const scrollbar = useWebScrollViewScrollbar(diffListRef, {
     enabled: showDesktopWebScrollbar,
   });
@@ -1900,26 +1970,23 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
   const diffListViewportHeightRef = useRef(0);
   const headerHeightByPathRef = useRef<Record<string, number>>({});
   const bodyHeightByKeyRef = useRef<Record<string, number>>({});
+  // Folder rows are a distinct kind; keep their height out of headerHeightByPathRef
+  // (Codex item 6) so file/folder heights can't collide by path.
+  const folderRowHeightRef = useRef<number>(0);
   const defaultHeaderHeightRef = useRef<number>(44);
   const [heightVersion, setHeightVersion] = useState(0);
   const diffBodyChromeHeight = BORDER_WIDTH[1] * 2;
   const statusBodyHeightEstimate = diffBodyChromeHeight + SPACING[4] * 2 + diffBodyLineHeight;
   const { flatItems, stickyHeaderIndices } = useMemo(() => {
-    const items: DiffFlatItem[] = [];
-    const stickyIndices: number[] = [];
-    for (let i = 0; i < files.length; i++) {
-      const file = files[i];
-      const isExpanded = expandedPaths.has(file.path);
-      items.push({ type: "header", file, fileIndex: i, isExpanded });
-      if (isExpanded) {
-        stickyIndices.push(items.length - 1);
-      }
-      if (isExpanded) {
-        items.push({ type: "body", file, fileIndex: i });
-      }
-    }
+    const { items, stickyHeaderIndices: stickyIndices } = buildDiffFlatItems({
+      files,
+      viewMode,
+      tree: compressedTree,
+      collapsedFolders,
+      expandedPaths,
+    });
     return { flatItems: items, stickyHeaderIndices: stickyIndices };
-  }, [expandedPaths, files]);
+  }, [compressedTree, collapsedFolders, expandedPaths, files, viewMode]);
 
   const getBodyHeightKey = useCallback(
     (file: ParsedDiffFile): string => {
@@ -1958,6 +2025,35 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
     [diffBodyChromeHeight, diffBodyLineHeight, effectiveLayout, statusBodyHeightEstimate],
   );
 
+  // Single height source of truth for both getItemLayout and the collapse
+  // scroll-anchor math. Folder rows use their own measured height (Codex item 6),
+  // falling back to the default header height before first measurement.
+  const getFlatItemHeight = useCallback(
+    (item: DiffFlatItem): number => {
+      if (item.type === "folder") {
+        return folderRowHeightRef.current || defaultHeaderHeightRef.current;
+      }
+      if (item.type === "header") {
+        return headerHeightByPathRef.current[item.file.path] ?? defaultHeaderHeightRef.current;
+      }
+      const bodyHeightKey = getBodyHeightKey(item.file);
+      return bodyHeightByKeyRef.current[bodyHeightKey] ?? estimateBodyHeight(item.file);
+    },
+    [estimateBodyHeight, getBodyHeightKey],
+  );
+
+  const handleFolderRowHeightChange = useCallback((height: number) => {
+    if (!Number.isFinite(height) || height <= 0) {
+      return;
+    }
+    const previousHeight = folderRowHeightRef.current;
+    if (previousHeight > 0 && Math.abs(previousHeight - height) <= DIFF_HEIGHT_CHANGE_EPSILON) {
+      return;
+    }
+    folderRowHeightRef.current = height;
+    setHeightVersion((version) => version + 1);
+  }, []);
+
   const handleHeaderHeightChange = useCallback((path: string, height: number) => {
     if (!Number.isFinite(height) || height <= 0) {
       return;
@@ -2013,23 +2109,24 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
     [scrollbar],
   );
 
-  const computeHeaderOffset = useCallback(
-    (path: string): number => {
-      const defaultHeaderHeight = defaultHeaderHeightRef.current;
-      let offset = 0;
-      for (const file of files) {
-        if (file.path === path) {
-          break;
-        }
-        offset += headerHeightByPathRef.current[file.path] ?? defaultHeaderHeight;
-        if (expandedPaths.has(file.path)) {
-          const bodyHeightKey = getBodyHeightKey(file);
-          offset += bodyHeightByKeyRef.current[bodyHeightKey] ?? estimateBodyHeight(file);
-        }
+  // Offset of the first item matching `predicate`, walking the SAME flatItems
+  // list getFlatItemLayout uses so folder rows are counted (single source of
+  // truth — Codex item 5 / finding 2).
+  const computeItemOffset = useCallback(
+    (predicate: (item: DiffFlatItem) => boolean): number | null => {
+      const index = flatItems.findIndex(predicate);
+      if (index < 0) {
+        return null;
       }
-      return Math.max(0, offset);
+      return sumHeightsBefore(flatItems, index, getFlatItemHeight);
     },
-    [estimateBodyHeight, expandedPaths, files, getBodyHeightKey],
+    [flatItems, getFlatItemHeight],
+  );
+
+  const computeHeaderOffset = useCallback(
+    (path: string): number =>
+      computeItemOffset((item) => item.type === "header" && item.file.path === path) ?? 0,
+    [computeItemOffset],
   );
 
   const handleToggleExpanded = useCallback(
@@ -2067,7 +2164,41 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
     [computeHeaderOffset, expandedPaths, setDiffExpandedPathsForWorkspace, workspaceStateKey],
   );
 
-  const allExpanded = useMemo(() => {
+  const handleToggleFolder = useCallback(
+    (dirPath: string) => {
+      if (!workspaceStateKey) {
+        return;
+      }
+      const isCurrentlyCollapsed = collapsedFolders.has(dirPath);
+      // Collapsing hides the subtree below this row; anchor to the folder row
+      // first so the viewport doesn't jump to a dead offset (Codex item 5).
+      if (!isCurrentlyCollapsed) {
+        const targetOffset = computeItemOffset(
+          (item) => item.type === "folder" && item.dirPath === dirPath,
+        );
+        const folderHeight = folderRowHeightRef.current || defaultHeaderHeightRef.current;
+        if (
+          targetOffset !== null &&
+          shouldAnchorHeaderBeforeCollapse({
+            headerOffset: targetOffset,
+            headerHeight: folderHeight,
+            viewportOffset: diffListScrollOffsetRef.current,
+            viewportHeight: diffListViewportHeightRef.current,
+          })
+        ) {
+          diffListRef.current?.scrollToOffset({ offset: targetOffset, animated: false });
+        }
+      }
+
+      const nextCollapsed = isCurrentlyCollapsed
+        ? Array.from(collapsedFolders).filter((path) => path !== dirPath)
+        : [...collapsedFolders, dirPath];
+      setDiffCollapsedFoldersForWorkspace(workspaceStateKey, nextCollapsed);
+    },
+    [collapsedFolders, computeItemOffset, setDiffCollapsedFoldersForWorkspace, workspaceStateKey],
+  );
+
+  const allFileDiffsExpanded = useMemo(() => {
     if (files.length === 0) return false;
     return files.every((file) => expandedPaths.has(file.path));
   }, [expandedPaths, files]);
@@ -2076,7 +2207,7 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
     if (!workspaceStateKey) {
       return;
     }
-    if (allExpanded) {
+    if (allFileDiffsExpanded) {
       setDiffExpandedPathsForWorkspace(workspaceStateKey, []);
     } else {
       setDiffExpandedPathsForWorkspace(
@@ -2084,15 +2215,32 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
         files.map((file) => file.path),
       );
     }
-  }, [allExpanded, files, setDiffExpandedPathsForWorkspace, workspaceStateKey]);
+  }, [allFileDiffsExpanded, files, setDiffExpandedPathsForWorkspace, workspaceStateKey]);
 
   const renderFlatItem = useCallback(
     ({ item }: { item: DiffFlatItem }) => {
+      if (item.type === "folder") {
+        return (
+          <DiffFolderRow
+            dirPath={item.dirPath}
+            displayName={item.displayName}
+            depth={item.depth}
+            collapsed={item.collapsed}
+            additions={item.additions}
+            deletions={item.deletions}
+            onToggle={handleToggleFolder}
+            onHeightChange={handleFolderRowHeightChange}
+            testID={`diff-folder-${item.dirPath}`}
+          />
+        );
+      }
       if (item.type === "header") {
         return (
           <DiffFileHeader
             file={item.file}
             isExpanded={item.isExpanded}
+            depth={item.depth}
+            showDir={viewMode === "flat"}
             onToggle={handleToggleExpanded}
             onHeaderHeightChange={handleHeaderHeightChange}
             testID={`diff-file-${item.fileIndex}`}
@@ -2117,40 +2265,25 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
       diffTextMetricsStyle,
       effectiveLayout,
       handleBodyHeightChange,
+      handleFolderRowHeightChange,
       handleHeaderHeightChange,
       handleToggleExpanded,
+      handleToggleFolder,
       reviewActions,
+      viewMode,
       wrapLines,
     ],
   );
 
   const flatKeyExtractor = useCallback(
-    (item: DiffFlatItem) => `${item.type}-${item.file.path}`,
+    (item: DiffFlatItem) =>
+      item.type === "folder" ? `folder-${item.dirPath}` : `${item.type}-${item.file.path}`,
     [],
   );
 
-  const getFlatItemHeight = useCallback(
-    (item: DiffFlatItem): number => {
-      if (item.type === "header") {
-        return headerHeightByPathRef.current[item.file.path] ?? defaultHeaderHeightRef.current;
-      }
-
-      const bodyHeightKey = getBodyHeightKey(item.file);
-      return bodyHeightByKeyRef.current[bodyHeightKey] ?? estimateBodyHeight(item.file);
-    },
-    [estimateBodyHeight, getBodyHeightKey],
-  );
-
   const getFlatItemLayout = useCallback<DiffFlatItemLayoutGetter>(
     (_data, index) => {
-      let offset = 0;
-      for (let itemIndex = 0; itemIndex < index; itemIndex += 1) {
-        const item = flatItems[itemIndex];
-        if (item) {
-          offset += getFlatItemHeight(item);
-        }
-      }
-
+      const offset = sumHeightsBefore(flatItems, index, getFlatItemHeight);
       const item = flatItems[index];
       const length = item ? getFlatItemHeight(item) : 0;
       return { length, offset, index };
@@ -2161,17 +2294,21 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
   const flatExtraData = useMemo(
     () => ({
       expandedPathsArray,
+      collapsedFoldersArray,
       effectiveLayout,
       diffBodyTypographyKey,
       heightVersion,
+      viewMode,
       wrapLines,
       reviewActions,
     }),
     [
       expandedPathsArray,
+      collapsedFoldersArray,
       effectiveLayout,
       diffBodyTypographyKey,
       heightVersion,
+      viewMode,
       wrapLines,
       reviewActions,
     ],
@@ -2301,38 +2438,40 @@ export function GitDiffPane({ serverId, workspaceId, cwd, enabled }: GitDiffPane
             </DropdownMenu>
             <View style={styles.diffStatusButtons}>
               {canUseSplitLayout ? (
-                <DiffLayoutToggleGroup
+                <DiffLayoutToggle
                   layout={changesPreferences.layout}
-                  unifiedToggleStyle={unifiedToggleStyle}
-                  splitToggleStyle={splitToggleStyle}
-                  onUnified={handleLayoutUnified}
-                  onSplit={handleLayoutSplit}
+                  isMobile={isMobile}
+                  toggleStyle={layoutToggleStyle}
+                  onToggle={handleToggleLayout}
+                />
+              ) : null}
+              {files.length > 0 ? (
+                <DiffViewModeToggle
+                  viewMode={viewMode}
+                  isMobile={isMobile}
+                  toggleStyle={viewModeToggleStyle}
+                  onToggle={handleToggleViewMode}
                 />
               ) : null}
-              <DiffWhitespaceToggle
-                hideWhitespace={changesPreferences.hideWhitespace}
-                isMobile={isMobile}
-                toggleStyle={hideWhitespaceToggleStyle}
-                onToggle={handleToggleHideWhitespace}
-              />
               {files.length > 0 ? (
                 <DiffFilesToolbar
-                  wrapLines={wrapLines}
-                  allExpanded={allExpanded}
+                  allFileDiffsExpanded={allFileDiffsExpanded}
                   isMobile={isMobile}
-                  wrapLinesToggleStyle={wrapLinesToggleStyle}
                   expandAllToggleStyle={expandAllToggleStyle}
-                  onToggleWrapLines={handleToggleWrapLines}
                   onToggleExpandAll={handleToggleExpandAll}
                 />
               ) : null}
-              {refreshSupported ? (
-                <DiffRefreshButton
-                  isRefreshing={isRefreshing}
-                  toggleStyle={refreshToggleStyle}
-                  onPress={handleRefresh}
-                />
-              ) : null}
+              <DiffOptionsMenu
+                hideWhitespace={changesPreferences.hideWhitespace}
+                isMobile={isMobile}
+                isRefreshing={isRefreshing}
+                overflowToggleStyle={overflowToggleStyle}
+                refreshSupported={refreshSupported}
+                wrapLines={wrapLines}
+                onRefresh={handleRefresh}
+                onToggleHideWhitespace={handleToggleHideWhitespace}
+                onToggleWrapLines={handleToggleWrapLines}
+              />
             </View>
           </View>
         </View>
@@ -2414,46 +2553,9 @@ const styles = StyleSheet.create((theme) => ({
     gap: theme.spacing[1],
     flexWrap: "wrap",
   },
-  toggleButtonGroup: {
-    flexDirection: "row",
-    alignItems: "center",
-  },
-  toggleButton: {
-    alignItems: "center",
-    justifyContent: "center",
-    minWidth: {
-      xs: 32,
-      sm: 32,
-      md: 24,
-    },
-    height: {
-      xs: 32,
-      sm: 32,
-      md: 24,
-    },
-    paddingHorizontal: {
-      xs: theme.spacing[2],
-      sm: theme.spacing[2],
-      md: theme.spacing[1],
-    },
-  },
-  toggleButtonGroupStart: {
-    borderTopLeftRadius: theme.borderRadius.base,
-    borderBottomLeftRadius: theme.borderRadius.base,
-  },
-  toggleButtonGroupEnd: {
-    borderTopRightRadius: theme.borderRadius.base,
-    borderBottomRightRadius: theme.borderRadius.base,
-  },
   toggleButtonSelected: {
     backgroundColor: theme.colors.surface2,
   },
-  refreshIcon: {
-    width: ICON_SIZE.md,
-    height: ICON_SIZE.md,
-    alignItems: "center",
-    justifyContent: "center",
-  },
   expandAllButton: {
     flexDirection: "row",
     alignItems: "center",
@@ -2574,6 +2676,11 @@ const styles = StyleSheet.create((theme) => ({
     gap: theme.spacing[1],
     flexShrink: 0,
   },
+  fileIcon: {
+    flexShrink: 0,
+    alignItems: "center",
+    justifyContent: "center",
+  },
   fileName: {
     fontSize: theme.fontSize.sm,
     fontWeight: theme.fontWeight.normal,
@@ -2588,6 +2695,10 @@ const styles = StyleSheet.create((theme) => ({
     flex: 1,
     minWidth: 0,
   },
+  fileDirSpacer: {
+    flex: 1,
+    minWidth: 0,
+  },
   newBadge: {
     backgroundColor: "rgba(46, 160, 67, 0.2)",
     paddingHorizontal: theme.spacing[2],

packages/app/src/git/diff-tree.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildDiffTree,
+  collectDirPaths,
+  compressSingleChildChains,
+  flattenDiffTree,
+  type DiffTreeRow,
+} from "./diff-tree";
+import type { ParsedDiffFile } from "@/git/use-diff-query";
+
+function createFile(path: string, additions = 1, deletions = 0): ParsedDiffFile {
+  return {
+    path,
+    isNew: false,
+    isDeleted: false,
+    additions,
+    deletions,
+    hunks: [],
+  };
+}
+
+// The Changes tree is fed the already-path-sorted diff files; build against that.
+function tree(paths: Array<string | ParsedDiffFile>) {
+  return buildDiffTree(paths.map((p) => (typeof p === "string" ? createFile(p) : p)));
+}
+
+function compressed(paths: Array<string | ParsedDiffFile>) {
+  return compressSingleChildChains(tree(paths));
+}
+
+function rowLabels(rows: DiffTreeRow[]): string[] {
+  return rows.map((row) =>
+    row.kind === "folder"
+      ? `${"  ".repeat(row.depth)}[${row.displayName}]`
+      : `${"  ".repeat(row.depth)}${row.file.path.split("/").pop()}`,
+  );
+}
+
+describe("buildDiffTree", () => {
+  it("returns an empty root for no files", () => {
+    const root = tree([]);
+    expect(root.dirPath).toBe("");
+    expect(root.children).toEqual([]);
+  });
+
+  it("places root-level files directly under the root with no folder", () => {
+    const root = tree(["README.md", "package.json"]);
+    expect(root.children.every((c) => c.kind === "file")).toBe(true);
+    expect(root.children.map((c) => (c.kind === "file" ? c.name : c.dirPath))).toEqual([
+      "README.md",
+      "package.json",
+    ]);
+  });
+
+  it("nests files under their directory, keyed by full path", () => {
+    const root = tree(["src/a.ts", "src/nested/b.ts"]);
+    expect(root.children).toHaveLength(1);
+    const src = root.children[0];
+    expect(src.kind).toBe("dir");
+    if (src.kind !== "dir") return;
+    expect(src.dirPath).toBe("src");
+    const nested = src.children.find((c) => c.kind === "dir");
+    expect(nested?.kind === "dir" && nested.dirPath).toBe("src/nested");
+  });
+
+  it("orders directories before files within a level, each alphabetically", () => {
+    // Input alpha-by-full-path puts the file 'src/a.ts' before dir 'src/z/...',
+    // but rendering wants dirs first.
+    const root = tree(["src/a.ts", "src/z/deep.ts", "src/m/mid.ts"]);
+    const src = root.children[0];
+    if (src.kind !== "dir") throw new Error("expected dir");
+    expect(
+      src.children.map((c) => (c.kind === "dir" ? `dir:${c.name}` : `file:${c.name}`)),
+    ).toEqual(["dir:m", "dir:z", "file:a.ts"]);
+  });
+});
+
+describe("compressSingleChildChains", () => {
+  it("collapses a single-child chain into one row keyed by the deepest dir", () => {
+    const rows = flattenDiffTree(compressed(["packages/app/src/git/diff-pane.tsx"]), new Set());
+    expect(rowLabels(rows)).toEqual(["[packages/app/src/git]", "  diff-pane.tsx"]);
+    const folder = rows[0];
+    expect(folder.kind === "folder" && folder.dirPath).toBe("packages/app/src/git");
+  });
+
+  it("stops compressing where a directory has multiple children", () => {
+    const rows = flattenDiffTree(
+      compressed(["packages/app/a.ts", "packages/server/b.ts"]),
+      new Set(),
+    );
+    // "packages" has two dir children, so it stays its own row.
+    expect(rowLabels(rows)).toEqual([
+      "[packages]",
+      "  [app]",
+      "    a.ts",
+      "  [server]",
+      "    b.ts",
+    ]);
+  });
+
+  it("compresses a chain that ends in a file-bearing directory", () => {
+    const rows = flattenDiffTree(compressed(["a/b/c/one.ts", "a/b/c/two.ts"]), new Set());
+    expect(rowLabels(rows)).toEqual(["[a/b/c]", "  one.ts", "  two.ts"]);
+  });
+
+  it("does not merge the virtual root with a single top-level dir's siblings", () => {
+    const rows = flattenDiffTree(compressed(["only/deep/file.ts"]), new Set());
+    expect(rows[0].kind === "folder" && rows[0].displayName).toBe("only/deep");
+  });
+});
+
+describe("flattenDiffTree", () => {
+  it("expands everything when the collapsed set is empty", () => {
+    const rows = flattenDiffTree(compressed(["src/a.ts", "src/b.ts"]), new Set());
+    expect(rowLabels(rows)).toEqual(["[src]", "  a.ts", "  b.ts"]);
+  });
+
+  it("omits descendants of a collapsed directory but keeps the folder row", () => {
+    const root = compressed(["src/a.ts", "src/b.ts"]);
+    const rows = flattenDiffTree(root, new Set(["src"]));
+    expect(rowLabels(rows)).toEqual(["[src]"]);
+  });
+
+  it("collapsing a parent hides nested folders and files", () => {
+    const root = compressed(["src/deep/a.ts", "src/top.ts"]);
+    const rows = flattenDiffTree(root, new Set(["src"]));
+    expect(rowLabels(rows)).toEqual(["[src]"]);
+  });
+
+  it("sums descendant additions/deletions onto the folder row", () => {
+    const root = compressed([createFile("src/a.ts", 3, 1), createFile("src/nested/b.ts", 5, 2)]);
+    const rows = flattenDiffTree(root, new Set());
+    const srcFolder = rows.find((r) => r.kind === "folder" && r.dirPath === "src");
+    expect(srcFolder).toMatchObject({ additions: 8, deletions: 3 });
+  });
+
+  it("reports full aggregate stats even when the folder is collapsed", () => {
+    const root = compressed([createFile("src/a.ts", 3, 1), createFile("src/b.ts", 4, 0)]);
+    const rows = flattenDiffTree(root, new Set(["src"]));
+    expect(rows[0]).toMatchObject({ kind: "folder", additions: 7, deletions: 1 });
+  });
+});
+
+describe("collectDirPaths", () => {
+  it("returns every logical directory path in the compressed tree", () => {
+    const root = compressed(["packages/app/a.ts", "packages/server/b.ts"]);
+    expect(collectDirPaths(root).sort()).toEqual(["packages", "packages/app", "packages/server"]);
+  });
+});

packages/app/src/git/diff-tree.ts

@@ -0,0 +1,207 @@
+import type { ParsedDiffFile } from "@/git/use-diff-query";
+
+// Builds a directory hierarchy from the flat, path-sorted `ParsedDiffFile[]` the
+// Changes view renders. The tree renders on every form factor, consistent with
+// the Files explorer.
+//
+// Directory nodes are keyed by their FULL uncompressed path (e.g. "packages/app/src").
+// That path is the stable identity used to persist folder-collapse state, so the
+// state survives path-compression changes as the diff mutates: if a compressed
+// row later splits because a sibling appears, the logical directories keep the
+// same keys.
+
+export interface DiffTreeFileNode {
+  kind: "file";
+  file: ParsedDiffFile;
+  /** basename, e.g. "diff-pane.tsx" */
+  name: string;
+}
+
+export interface DiffTreeDirNode {
+  kind: "dir";
+  /** full uncompressed directory path, e.g. "packages/app/src"; "" for the virtual root */
+  dirPath: string;
+  /** display label; a compressed chain joins segments, e.g. "packages/app/src" */
+  name: string;
+  children: DiffTreeNode[];
+}
+
+export type DiffTreeNode = DiffTreeFileNode | DiffTreeDirNode;
+
+export interface DiffTreeFolderRow {
+  kind: "folder";
+  /** full uncompressed path of the DEEPEST directory this row represents */
+  dirPath: string;
+  /** compressed display label, e.g. "packages/app/src" */
+  displayName: string;
+  depth: number;
+  additions: number;
+  deletions: number;
+}
+
+export interface DiffTreeFileRow {
+  kind: "file";
+  file: ParsedDiffFile;
+  depth: number;
+}
+
+export type DiffTreeRow = DiffTreeFolderRow | DiffTreeFileRow;
+
+function sortTree(node: DiffTreeDirNode): void {
+  node.children.sort((a, b) => {
+    if (a.kind !== b.kind) {
+      // directories before files within a level
+      return a.kind === "dir" ? -1 : 1;
+    }
+    // Plain ASCII comparison, matching compareCheckoutDiffPaths (diff-order.ts)
+    // so the tree order is consistent with the rest of the Changes view.
+    if (a.name === b.name) return 0;
+    return a.name < b.name ? -1 : 1;
+  });
+  for (const child of node.children) {
+    if (child.kind === "dir") {
+      sortTree(child);
+    }
+  }
+}
+
+/** Build the (uncompressed) directory tree. Returns the virtual root (dirPath ""). */
+export function buildDiffTree(files: ParsedDiffFile[]): DiffTreeDirNode {
+  const root: DiffTreeDirNode = { kind: "dir", dirPath: "", name: "", children: [] };
+  const dirByPath = new Map<string, DiffTreeDirNode>([["", root]]);
+
+  function ensureDir(dirPath: string): DiffTreeDirNode {
+    const existing = dirByPath.get(dirPath);
+    if (existing) {
+      return existing;
+    }
+    const parts = dirPath.split("/");
+    const name = parts[parts.length - 1];
+    const parentPath = parts.slice(0, -1).join("/");
+    const parent = ensureDir(parentPath);
+    const node: DiffTreeDirNode = { kind: "dir", dirPath, name, children: [] };
+    parent.children.push(node);
+    dirByPath.set(dirPath, node);
+    return node;
+  }
+
+  for (const file of files) {
+    const parts = file.path.split("/");
+    const name = parts[parts.length - 1];
+    const dirPath = parts.slice(0, -1).join("/");
+    ensureDir(dirPath).children.push({ kind: "file", file, name });
+  }
+
+  sortTree(root);
+  return root;
+}
+
+// Collapse runs of single-child directories into one row, like VS Code / GitHub:
+// a directory whose only child is another directory absorbs it. The merged row
+// displays the joined segments ("packages/app/src") but keeps the DEEPEST
+// directory's full path as its identity.
+function compressNode(node: DiffTreeDirNode): DiffTreeDirNode {
+  let name = node.name;
+  let dirPath = node.dirPath;
+  let children = node.children.map((child) => (child.kind === "dir" ? compressNode(child) : child));
+  while (children.length === 1 && children[0].kind === "dir") {
+    const only = children[0];
+    name = name ? `${name}/${only.name}` : only.name;
+    dirPath = only.dirPath;
+    children = only.children;
+  }
+  return { kind: "dir", dirPath, name, children };
+}
+
+/**
+ * Compress single-child directory chains. The virtual root is never merged
+ * (it isn't rendered); only its subtrees are compressed.
+ */
+export function compressSingleChildChains(root: DiffTreeDirNode): DiffTreeDirNode {
+  return {
+    ...root,
+    children: root.children.map((child) => (child.kind === "dir" ? compressNode(child) : child)),
+  };
+}
+
+interface DirStats {
+  additions: number;
+  deletions: number;
+}
+
+const EMPTY_DIR_STATS: DirStats = { additions: 0, deletions: 0 };
+
+// Single post-order pass computing every directory node's aggregate stats from
+// its already-summed children — O(n), vs. re-walking each subtree per folder row.
+function computeDirStats(root: DiffTreeDirNode): Map<DiffTreeDirNode, DirStats> {
+  const statsByNode = new Map<DiffTreeDirNode, DirStats>();
+  function visit(node: DiffTreeDirNode): DirStats {
+    const stats: DirStats = { additions: 0, deletions: 0 };
+    for (const child of node.children) {
+      if (child.kind === "file") {
+        stats.additions += child.file.additions;
+        stats.deletions += child.file.deletions;
+      } else {
+        const childStats = visit(child);
+        stats.additions += childStats.additions;
+        stats.deletions += childStats.deletions;
+      }
+    }
+    statsByNode.set(node, stats);
+    return stats;
+  }
+  visit(root);
+  return statsByNode;
+}
+
+/**
+ * Flatten the (compressed) tree into depth-tagged rows for the list. Descendants
+ * of any directory whose `dirPath` is in `collapsed` are omitted; folder rows
+ * always carry the FULL aggregate stats of their subtree, collapsed or not.
+ */
+export function flattenDiffTree(
+  root: DiffTreeDirNode,
+  collapsed: ReadonlySet<string>,
+): DiffTreeRow[] {
+  const statsByNode = computeDirStats(root);
+  const rows: DiffTreeRow[] = [];
+
+  function walk(node: DiffTreeDirNode, depth: number): void {
+    for (const child of node.children) {
+      if (child.kind === "file") {
+        rows.push({ kind: "file", file: child.file, depth });
+        continue;
+      }
+      const stats = statsByNode.get(child) ?? EMPTY_DIR_STATS;
+      rows.push({
+        kind: "folder",
+        dirPath: child.dirPath,
+        displayName: child.name,
+        depth,
+        additions: stats.additions,
+        deletions: stats.deletions,
+      });
+      if (!collapsed.has(child.dirPath)) {
+        walk(child, depth + 1);
+      }
+    }
+  }
+
+  walk(root, 0);
+  return rows;
+}
+
+/** Every directory path in the (compressed) tree — used for "collapse all folders". */
+export function collectDirPaths(root: DiffTreeDirNode): string[] {
+  const paths: string[] = [];
+  function walk(node: DiffTreeDirNode): void {
+    for (const child of node.children) {
+      if (child.kind === "dir") {
+        paths.push(child.dirPath);
+        walk(child);
+      }
+    }
+  }
+  walk(root);
+  return paths;
+}

packages/app/src/hooks/use-changes-preferences/storage.test.ts

@@ -28,6 +28,7 @@ describe("loadChangesPreferencesFromStorage", () => {
 
     expect(result).toEqual({
       layout: "unified",
+      viewMode: "flat",
       wrapLines: true,
       hideWhitespace: false,
     });
@@ -37,6 +38,7 @@ describe("loadChangesPreferencesFromStorage", () => {
   it("loads persisted layout and whitespace preferences without rewriting storage", async () => {
     const persisted = JSON.stringify({
       layout: "split",
+      viewMode: "tree",
       hideWhitespace: true,
       wrapLines: false,
     });
@@ -48,6 +50,7 @@ describe("loadChangesPreferencesFromStorage", () => {
 
     expect(result).toEqual({
       layout: "split",
+      viewMode: "tree",
       hideWhitespace: true,
       wrapLines: false,
     });
@@ -64,11 +67,16 @@ describe("saveChangesPreferences", () => {
 
     await saveChangesPreferences({
       queryClient,
-      updates: { layout: "split", hideWhitespace: true },
+      updates: { layout: "split", viewMode: "tree", hideWhitespace: true },
       storage,
     });
 
-    const expected = { ...DEFAULT_CHANGES_PREFERENCES, layout: "split", hideWhitespace: true };
+    const expected = {
+      ...DEFAULT_CHANGES_PREFERENCES,
+      layout: "split",
+      viewMode: "tree",
+      hideWhitespace: true,
+    };
     expect(queryClient.getQueryData(CHANGES_PREFERENCES_QUERY_KEY)).toEqual(expected);
     expect(storage.entries.get(CHANGES_PREFERENCES_STORAGE_KEY)).toBe(JSON.stringify(expected));
   });

packages/app/src/hooks/use-changes-preferences/storage.ts

@@ -7,18 +7,21 @@ export const CHANGES_PREFERENCES_QUERY_KEY = ["changes-preferences"];
 
 const changesPreferencesSchema = z.object({
   layout: z.enum(["unified", "split"]).optional(),
+  viewMode: z.enum(["flat", "tree"]).optional(),
   wrapLines: z.boolean().optional(),
   hideWhitespace: z.boolean().optional(),
 });
 
 export interface ChangesPreferences {
   layout: "unified" | "split";
+  viewMode: "flat" | "tree";
   wrapLines: boolean;
   hideWhitespace: boolean;
 }
 
 export const DEFAULT_CHANGES_PREFERENCES: ChangesPreferences = {
   layout: "unified",
+  viewMode: "flat",
   wrapLines: false,
   hideWhitespace: false,
 };

packages/app/src/hooks/use-dictation-audio-source.native.ts

@@ -12,6 +12,7 @@ import type {
 export function useDictationAudioSource(config: DictationAudioSourceConfig): DictationAudioSource {
   const onPcmSegmentRef = useRef(config.onPcmSegment);
   const onErrorRef = useRef(config.onError);
+  const onInterruptionRef = useRef(config.onInterruption);
   const [volume, setVolume] = useState(0);
   const engineRef = useRef<ReturnType<typeof createAudioEngine> | null>(null);
 
@@ -30,6 +31,9 @@ export function useDictationAudioSource(config: DictationAudioSourceConfig): Dic
       onError: (error) => {
         onErrorRef.current?.(error);
       },
+      onInterruption: () => {
+        onInterruptionRef.current?.();
+      },
     });
     return engineRef.current;
   }, []);
@@ -37,7 +41,8 @@ export function useDictationAudioSource(config: DictationAudioSourceConfig): Dic
   useEffect(() => {
     onPcmSegmentRef.current = config.onPcmSegment;
     onErrorRef.current = config.onError;
-  }, [config.onPcmSegment, config.onError]);
+    onInterruptionRef.current = config.onInterruption;
+  }, [config.onPcmSegment, config.onError, config.onInterruption]);
 
   const start = useCallback(async () => {
     const engine = getOrCreateEngine();

packages/app/src/hooks/use-dictation-audio-source.types.ts

@@ -1,6 +1,7 @@
 export interface DictationAudioSourceConfig {
   onPcmSegment: (pcm16Base64: string) => void;
   onError?: (error: Error) => void;
+  onInterruption?: () => void;
 }
 
 export interface DictationAudioSource {

packages/app/src/hooks/use-dictation.ts

@@ -184,19 +184,6 @@ export function useDictation(options: UseDictationOptions): UseDictationResult {
     });
   }, [client]);
 
-  const audio = useDictationAudioSource({
-    onPcmSegment: (audioData) => {
-      senderRef.current?.enqueueSegment(audioData);
-    },
-    onError: (err) => {
-      onErrorRef.current?.(err);
-    },
-  });
-  const audioStopRef = useRef(audio.stop);
-  useEffect(() => {
-    audioStopRef.current = audio.stop;
-  }, [audio.stop]);
-
   const handleStreamingTranscriptionSuccess = useCallback(
     (text: string, requestId: string) => {
       setIsProcessing(false);
@@ -220,6 +207,7 @@ export function useDictation(options: UseDictationOptions): UseDictationResult {
     (failure: unknown) => {
       const normalized = toError(failure);
       const failureId = generateMessageId();
+      stopDurationTracking();
       setIsProcessing(false);
       isProcessingRef.current = false;
       isRecordingRef.current = false;
@@ -234,9 +222,30 @@ export function useDictation(options: UseDictationOptions): UseDictationResult {
 
       reportError(normalized, "Failed to complete dictation");
     },
-    [reportError],
+    [reportError, stopDurationTracking],
   );
 
+  const audio = useDictationAudioSource({
+    onPcmSegment: (audioData) => {
+      senderRef.current?.enqueueSegment(audioData);
+    },
+    onError: (err) => {
+      onErrorRef.current?.(err);
+    },
+    onInterruption: () => {
+      try {
+        senderRef.current?.cancel();
+      } catch {
+        // no-op
+      }
+      handleDictationFailure(new Error("Dictation was interrupted by another audio source."));
+    },
+  });
+  const audioStopRef = useRef(audio.stop);
+  useEffect(() => {
+    audioStopRef.current = audio.stop;
+  }, [audio.stop]);
+
   const startDictation = useCallback(async () => {
     if (
       actionGateRef.current.starting ||

packages/app/src/hooks/use-settings/index.ts

@@ -96,6 +96,8 @@ export interface UseSettingsReturn {
   resetSettings: () => Promise<void>;
 }
 
+type SettingsSelector<TSelected> = (settings: Settings) => TSelected;
+
 export function useAppSettings(): UseAppSettingsReturn {
   const queryClient = useQueryClient();
   const { data, isPending, error } = useQuery({
@@ -137,7 +139,11 @@ export function useAppSettings(): UseAppSettingsReturn {
   };
 }
 
-export function useSettings(): UseSettingsReturn {
+export function useSettings(): UseSettingsReturn;
+export function useSettings<TSelected>(selector: SettingsSelector<TSelected>): TSelected;
+export function useSettings<TSelected>(
+  selector?: SettingsSelector<TSelected>,
+): UseSettingsReturn | TSelected {
   const appSettings = useAppSettings();
   const desktopSettings = useDesktopSettings();
 
@@ -177,6 +183,9 @@ export function useSettings(): UseSettingsReturn {
       if (updates.workspaceTitleSource !== undefined) {
         appUpdates.workspaceTitleSource = updates.workspaceTitleSource;
       }
+      if (updates.autoExpandReasoning !== undefined) {
+        appUpdates.autoExpandReasoning = updates.autoExpandReasoning;
+      }
       const promises: Promise<void>[] = [];
       if (Object.keys(appUpdates).length > 0) {
         promises.push(appSettings.updateSettings(appUpdates));
@@ -210,13 +219,19 @@ export function useSettings(): UseSettingsReturn {
     await Promise.all(resets);
   }, [appSettings, desktopSettings]);
 
+  const settings = {
+    ...DEFAULT_APP_SETTINGS,
+    ...appSettings.settings,
+    manageBuiltInDaemon: desktopSettings.settings.daemon.manageBuiltInDaemon,
+    releaseChannel: desktopSettings.settings.releaseChannel,
+  };
+
+  if (selector) {
+    return selector(settings);
+  }
+
   return {
-    settings: {
-      ...DEFAULT_APP_SETTINGS,
-      ...appSettings.settings,
-      manageBuiltInDaemon: desktopSettings.settings.daemon.manageBuiltInDaemon,
-      releaseChannel: desktopSettings.settings.releaseChannel,
-    },
+    settings,
     isLoading: appSettings.isLoading || desktopSettings.isLoading,
     error: appSettings.error ?? desktopSettings.error,
     updateSettings,

packages/app/src/hooks/use-settings/storage.ts

@@ -39,6 +39,7 @@ export interface AppSettings {
   codeFontSize: number; // clamped px, default 12
   syntaxTheme: SyntaxThemeId; // default "one"
   workspaceTitleSource: WorkspaceTitleSource;
+  autoExpandReasoning: boolean;
 }
 
 export interface Settings extends AppSettings {
@@ -58,6 +59,7 @@ export const DEFAULT_CLIENT_SETTINGS: AppSettings = {
   codeFontSize: DEFAULT_CODE_FONT_SIZE,
   syntaxTheme: "one",
   workspaceTitleSource: "title",
+  autoExpandReasoning: false,
 };
 
 export const DEFAULT_APP_SETTINGS: Settings = {
@@ -204,6 +206,9 @@ function pickAppSettings(stored: Partial<AppSettings>): Partial<AppSettings> {
   ) {
     result.workspaceTitleSource = stored.workspaceTitleSource;
   }
+  if (typeof stored.autoExpandReasoning === "boolean") {
+    result.autoExpandReasoning = stored.autoExpandReasoning;
+  }
   return result;
 }
 

packages/app/src/i18n/resources/ar.ts

@@ -707,11 +707,19 @@ export const ar: TranslationResources = {
         tooLarge: "الفرق كبير جدًا بحيث لا يمكن عرضه",
         unified: "الفرق الموحدة",
         split: "فرق جنبًا إلى جنب",
+        switchToUnified: "التبديل إلى الفرق الموحد",
+        switchToSplit: "التبديل إلى الفرق جنبًا إلى جنب",
+        showTreeView: "إظهار شجرة المجلدات",
+        showFlatView: "إظهار قائمة الملفات المسطحة",
+        options: "خيارات الفرق",
         hideWhitespace: "إخفاء المسافة البيضاء",
+        showWhitespace: "إظهار المسافة البيضاء",
         scrollLongLines: "قم بتمرير الخطوط الطويلة",
         wrapLongLines: "لف الخطوط الطويلة",
         collapseAll: "طي كافة الملفات",
         expandAll: "قم بتوسيع كافة الملفات",
+        collapseAllFolders: "طي كافة المجلدات",
+        expandAllFolders: "توسيع كافة المجلدات",
         refreshing: "منعش",
         refresh: "ينعش",
         refreshState: "تحديث بوابة وحالة GitHub",
@@ -1048,6 +1056,12 @@ export const ar: TranslationResources = {
       },
     },
   },
+  rootError: {
+    kicker: "حدث خطأ",
+    title: "واجه Paseo مشكلة.",
+    body: "جرّب مرة أخرى لإعادة تحميل التطبيق. إذا استمر حدوث ذلك، فأرفق التفاصيل أدناه عند الإبلاغ عنه.",
+    details: "التفاصيل",
+  },
   startup: {
     errorTitle: "حدث خطأ ما",
     errorDescription:
@@ -1457,6 +1471,10 @@ export const ar: TranslationResources = {
         description: "يتم الاحتفاظ بالخطوط في المخزن المؤقت الطرفي المدمج",
         accessibilityLabel: "خطوط التمرير Terminal",
       },
+      autoExpandReasoning: {
+        label: "عرض التفكير دائماً",
+        description: "إظهار تفكير الوكيل وخطوات الاستدلال بشكل كامل بشكل افتراضي",
+      },
       language: {
         label: "لغة",
         description: "لغة التطبيق",
@@ -1538,6 +1556,9 @@ export const ar: TranslationResources = {
           auto: "نظام",
         },
       },
+      detailLevel: {
+        title: "مستوى التفاصيل",
+      },
       fonts: {
         title: "الخطوط",
         systemDefault: "الافتراضي للنظام",

packages/app/src/i18n/resources/en.ts

@@ -714,11 +714,19 @@ export const en = {
         tooLarge: "Diff too large to display",
         unified: "Unified diff",
         split: "Side-by-side diff",
+        switchToUnified: "Switch to unified diff",
+        switchToSplit: "Switch to side-by-side diff",
+        showTreeView: "Show folder tree",
+        showFlatView: "Show flat file list",
+        options: "Diff options",
         hideWhitespace: "Hide whitespace",
+        showWhitespace: "Show whitespace",
         scrollLongLines: "Scroll long lines",
         wrapLongLines: "Wrap long lines",
         collapseAll: "Collapse all files",
         expandAll: "Expand all files",
+        collapseAllFolders: "Collapse all folders",
+        expandAllFolders: "Expand all folders",
         refreshing: "Refreshing",
         refresh: "Refresh",
         refreshState: "Refresh git and GitHub state",
@@ -1055,6 +1063,12 @@ export const en = {
       },
     },
   },
+  rootError: {
+    kicker: "Something went wrong",
+    title: "Paseo ran into a problem.",
+    body: "Try again to reload the app. If this keeps happening, include the details below when you report it.",
+    details: "Details",
+  },
   startup: {
     errorTitle: "Something went wrong",
     errorDescription:
@@ -1464,6 +1478,10 @@ export const en = {
         description: "Lines kept in the built-in terminal buffer",
         accessibilityLabel: "Terminal scrollback lines",
       },
+      autoExpandReasoning: {
+        label: "Always expand reasoning",
+        description: "Show agent thinking and chain-of-thought blocks fully expanded by default",
+      },
       language: {
         label: "Language",
         description: "App language",
@@ -1545,6 +1563,9 @@ export const en = {
           auto: "System",
         },
       },
+      detailLevel: {
+        title: "Detail level",
+      },
       fonts: {
         title: "Fonts",
         systemDefault: "System default",

packages/app/src/i18n/resources/es.ts

@@ -734,11 +734,19 @@ export const es: TranslationResources = {
         tooLarge: "La diferencia es demasiado grande para mostrarse",
         unified: "Diferencia unificada",
         split: "Diferencia de lado a lado",
+        switchToUnified: "Cambiar a diferencia unificada",
+        switchToSplit: "Cambiar a diferencia lado a lado",
+        showTreeView: "Mostrar árbol de carpetas",
+        showFlatView: "Mostrar lista plana de archivos",
+        options: "Opciones de diferencia",
         hideWhitespace: "Ocultar espacios en blanco",
+        showWhitespace: "Mostrar espacios en blanco",
         scrollLongLines: "Desplazarse por largas filas",
         wrapLongLines: "Envolver largas filas",
         collapseAll: "Contraer todos los archivos",
         expandAll: "Expandir todos los archivos",
+        collapseAllFolders: "Contraer todas las carpetas",
+        expandAllFolders: "Expandir todas las carpetas",
         refreshing: "Refrescante",
         refresh: "Refrescar",
         refreshState: "Actualizar el estado de git yGitHub",
@@ -1084,6 +1092,12 @@ export const es: TranslationResources = {
       },
     },
   },
+  rootError: {
+    kicker: "Algo salió mal",
+    title: "Paseo tuvo un problema.",
+    body: "Vuelve a intentarlo para recargar la app. Si sigue ocurriendo, incluye los detalles de abajo al reportarlo.",
+    details: "Detalles",
+  },
   startup: {
     errorTitle: "algo salió mal",
     errorDescription:
@@ -1497,6 +1511,11 @@ export const es: TranslationResources = {
         description: "Líneas mantenidas en el búfer de terminal incorporado",
         accessibilityLabel: "Líneas del historial de terminal",
       },
+      autoExpandReasoning: {
+        label: "Siempre expandir razonamiento",
+        description:
+          "Mostrar los bloques de pensamiento y razonamiento del agente totalmente expandidos de forma predeterminada",
+      },
       language: {
         label: "Idioma",
         description: "Idioma de la aplicación",
@@ -1578,6 +1597,9 @@ export const es: TranslationResources = {
           auto: "Sistema",
         },
       },
+      detailLevel: {
+        title: "Nivel de detalle",
+      },
       fonts: {
         title: "Fuentes",
         systemDefault: "Valor predeterminado del sistema",

packages/app/src/i18n/resources/fr.ts

@@ -733,11 +733,19 @@ export const fr: TranslationResources = {
         tooLarge: "Diff trop grand pour être affiché",
         unified: "Différentiel unifié",
         split: "Différent côte à côte",
+        switchToUnified: "Passer au diff unifié",
+        switchToSplit: "Passer au diff côte à côte",
+        showTreeView: "Afficher l'arborescence des dossiers",
+        showFlatView: "Afficher la liste de fichiers à plat",
+        options: "Options du diff",
         hideWhitespace: "Masquer les espaces",
+        showWhitespace: "Afficher les espaces",
         scrollLongLines: "Faire défiler les longues lignes",
         wrapLongLines: "Enroulez les longues lignes",
         collapseAll: "Réduire tous les fichiers",
         expandAll: "Développer tous les fichiers",
+        collapseAllFolders: "Réduire tous les dossiers",
+        expandAllFolders: "Développer tous les dossiers",
         refreshing: "Rafraîchissant",
         refresh: "Rafraîchir",
         refreshState: "Actualiser l'état de git etGitHub",
@@ -1086,6 +1094,12 @@ export const fr: TranslationResources = {
       },
     },
   },
+  rootError: {
+    kicker: "Une erreur s'est produite",
+    title: "Paseo a rencontré un problème.",
+    body: "Réessayez pour recharger l'application. Si cela continue, joignez les détails ci-dessous au signalement.",
+    details: "Détails",
+  },
   startup: {
     errorTitle: "Quelque chose s'est mal passé",
     errorDescription:
@@ -1500,6 +1514,10 @@ export const fr: TranslationResources = {
         description: "Lignes conservées dans le tampon du terminal intégré",
         accessibilityLabel: "Lignes de défilementTerminal",
       },
+      autoExpandReasoning: {
+        label: "Toujours afficher le raisonnement",
+        description: "Afficher le raisonnement de l'agent entièrement développé par défaut",
+      },
       language: {
         label: "Langue",
         description: "Langue de l'application",
@@ -1582,6 +1600,9 @@ export const fr: TranslationResources = {
           auto: "Système",
         },
       },
+      detailLevel: {
+        title: "Niveau de détail",
+      },
       fonts: {
         title: "Polices",
         systemDefault: "Valeur par défaut du système",

packages/app/src/i18n/resources/ja.ts

@@ -719,11 +719,19 @@ export const ja: TranslationResources = {
         tooLarge: "差分が大きすぎて表示できません",
         unified: "ユニファイド差分",
         split: "左右比較",
+        switchToUnified: "ユニファイド差分に切り替え",
+        switchToSplit: "左右比較差分に切り替え",
+        showTreeView: "フォルダツリーを表示",
+        showFlatView: "フラットなファイル一覧を表示",
+        options: "差分オプション",
         hideWhitespace: "空白を非表示",
+        showWhitespace: "空白を表示",
         scrollLongLines: "長い行をスクロール",
         wrapLongLines: "長い行を折り返す",
         collapseAll: "すべて折りたたむ",
         expandAll: "すべて展開",
+        collapseAllFolders: "すべてのフォルダを折りたたむ",
+        expandAllFolders: "すべてのフォルダを展開",
         refreshing: "更新中",
         refresh: "更新",
         refreshState: "gitとGitHubの状態を更新",
@@ -1062,6 +1070,12 @@ export const ja: TranslationResources = {
       },
     },
   },
+  rootError: {
+    kicker: "問題が発生しました",
+    title: "Paseo で問題が発生しました。",
+    body: "アプリを再読み込みするにはもう一度お試しください。繰り返し発生する場合は、以下の詳細を添えて報告してください。",
+    details: "詳細",
+  },
   startup: {
     errorTitle: "問題が発生しました",
     errorDescription:
@@ -1473,6 +1487,10 @@ export const ja: TranslationResources = {
         description: "組み込みターミナルバッファに保持する行数",
         accessibilityLabel: "ターミナルスクロールバック行数",
       },
+      autoExpandReasoning: {
+        label: "常に思考プロセスを展開",
+        description: "デフォルトでAIのエージェント思考・推論ブロックを完全に展開して表示します",
+      },
       language: {
         label: "言語",
         description: "アプリの言語",
@@ -1554,6 +1572,9 @@ export const ja: TranslationResources = {
           auto: "システム",
         },
       },
+      detailLevel: {
+        title: "詳細レベル",
+      },
       fonts: {
         title: "フォント",
         systemDefault: "システムデフォルト",

packages/app/src/i18n/resources/pt-BR.ts

@@ -725,11 +725,19 @@ export const ptBR: TranslationResources = {
         tooLarge: "Diff grande demais para exibir",
         unified: "Diff unificado",
         split: "Diff lado a lado",
+        switchToUnified: "Alternar para diff unificado",
+        switchToSplit: "Alternar para diff lado a lado",
+        showTreeView: "Mostrar árvore de pastas",
+        showFlatView: "Mostrar lista plana de arquivos",
+        options: "Opções do diff",
         hideWhitespace: "Ocultar espaços em branco",
+        showWhitespace: "Mostrar espaços em branco",
         scrollLongLines: "Rolar linhas longas",
         wrapLongLines: "Quebrar linhas longas",
         collapseAll: "Recolher todos os arquivos",
         expandAll: "Expandir todos os arquivos",
+        collapseAllFolders: "Recolher todas as pastas",
+        expandAllFolders: "Expandir todas as pastas",
         refreshing: "Atualizando",
         refresh: "Atualizar",
         refreshState: "Atualizar estado do git e do GitHub",
@@ -1070,6 +1078,12 @@ export const ptBR: TranslationResources = {
       },
     },
   },
+  rootError: {
+    kicker: "Algo deu errado",
+    title: "O Paseo encontrou um problema.",
+    body: "Tente novamente para recarregar o app. Se isso continuar acontecendo, inclua os detalhes abaixo ao relatar o problema.",
+    details: "Detalhes",
+  },
   startup: {
     errorTitle: "Algo deu errado",
     errorDescription:
@@ -1482,6 +1496,11 @@ export const ptBR: TranslationResources = {
         description: "Linhas mantidas no buffer do terminal integrado",
         accessibilityLabel: "Linhas do scrollback do terminal",
       },
+      autoExpandReasoning: {
+        label: "Sempre expandir raciocínio",
+        description:
+          "Mostrar os blocos de pensamento e raciocínio do agente totalmente expandidos por padrão",
+      },
       language: {
         label: "Idioma",
         description: "Idioma do app",
@@ -1563,6 +1582,9 @@ export const ptBR: TranslationResources = {
           auto: "Sistema",
         },
       },
+      detailLevel: {
+        title: "Nível de detalhe",
+      },
       fonts: {
         title: "Fontes",
         systemDefault: "Sistema padrão",

packages/app/src/i18n/resources/ru.ts

@@ -726,11 +726,19 @@ export const ru: TranslationResources = {
         tooLarge: "Разница слишком велика для отображения",
         unified: "Единый дифференциал",
         split: "Параллельная разница",
+        switchToUnified: "Переключить на объединенный diff",
+        switchToSplit: "Переключить на diff рядом",
+        showTreeView: "Показать дерево папок",
+        showFlatView: "Показать плоский список файлов",
+        options: "Параметры diff",
         hideWhitespace: "Скрыть пробелы",
+        showWhitespace: "Показать пробелы",
         scrollLongLines: "Прокручивать длинные строки",
         wrapLongLines: "Перенос длинных строк",
         collapseAll: "Свернуть все файлы",
         expandAll: "Развернуть все файлы",
+        collapseAllFolders: "Свернуть все папки",
+        expandAllFolders: "Развернуть все папки",
         refreshing: "Освежающий",
         refresh: "Обновить",
         refreshState: "Обновить состояние git и GitHub.",
@@ -1074,6 +1082,12 @@ export const ru: TranslationResources = {
       },
     },
   },
+  rootError: {
+    kicker: "Что-то пошло не так",
+    title: "В Paseo возникла проблема.",
+    body: "Попробуйте снова перезагрузить приложение. Если это повторяется, приложите приведенные ниже подробности к отчету.",
+    details: "Подробности",
+  },
   startup: {
     errorTitle: "Что- то пошло не так",
     errorDescription:
@@ -1487,6 +1501,11 @@ export const ru: TranslationResources = {
         description: "Строки, хранящиеся во встроенном буфере терминала.",
         accessibilityLabel: "Линии прокрутки Terminal",
       },
+      autoExpandReasoning: {
+        label: "Всегда разворачивать размышления",
+        description:
+          "По умолчанию показывать блоки размышлений и логики агента полностью развернутыми",
+      },
       language: {
         label: "Язык",
         description: "Язык приложения",
@@ -1569,6 +1588,9 @@ export const ru: TranslationResources = {
           auto: "Система",
         },
       },
+      detailLevel: {
+        title: "Уровень детализации",
+      },
       fonts: {
         title: "Шрифты",
         systemDefault: "Система по умолчанию",

packages/app/src/i18n/resources/zh-CN.ts

@@ -701,11 +701,19 @@ export const zhCN: TranslationResources = {
         tooLarge: "Diff 过大，无法显示",
         unified: "Unified diff",
         split: "Side-by-side diff",
+        switchToUnified: "切换到统一差异视图",
+        switchToSplit: "切换到并排差异视图",
+        showTreeView: "显示文件夹树",
+        showFlatView: "显示平铺文件列表",
+        options: "Diff 选项",
         hideWhitespace: "隐藏空白差异",
+        showWhitespace: "显示空白差异",
         scrollLongLines: "滚动长行",
         wrapLongLines: "自动换行长行",
         collapseAll: "折叠所有文件",
         expandAll: "展开所有文件",
+        collapseAllFolders: "折叠所有文件夹",
+        expandAllFolders: "展开所有文件夹",
         refreshing: "正在刷新",
         refresh: "刷新",
         refreshState: "刷新 git 和 GitHub 状态",
@@ -1034,6 +1042,12 @@ export const zhCN: TranslationResources = {
       },
     },
   },
+  rootError: {
+    kicker: "出现问题",
+    title: "Paseo 遇到了问题。",
+    body: "请重试以重新加载应用。如果问题持续发生，请在报告时附上下面的详细信息。",
+    details: "详情",
+  },
   startup: {
     errorTitle: "出现问题",
     errorDescription: "本地服务器启动失败。如果持续发生，请在 GitHub 报告问题并附上下方日志。",
@@ -1439,6 +1453,10 @@ export const zhCN: TranslationResources = {
         description: "内置终端缓冲区保留的行数",
         accessibilityLabel: "终端回滚行数",
       },
+      autoExpandReasoning: {
+        label: "始终展开推理过程",
+        description: "默认情况下完全展开 AI 的思考和推理过程",
+      },
       language: {
         label: "语言",
         description: "应用语言",
@@ -1520,6 +1538,9 @@ export const zhCN: TranslationResources = {
           auto: "系统",
         },
       },
+      detailLevel: {
+        title: "详细程度",
+      },
       fonts: {
         title: "字体",
         systemDefault: "系统默认",

packages/app/src/provider-usage/use-provider-usage.ts

@@ -58,10 +58,8 @@ export function useProviderUsage(
   });
 
   const refresh = useCallback(async () => {
+    if (!canFetch) return;
     await queryClient.invalidateQueries({ queryKey });
-    if (!canFetch) {
-      return;
-    }
     await queryClient.fetchQuery({
       queryKey,
       queryFn,

packages/app/src/screens/settings/appearance/appearance-section.tsx

@@ -16,6 +16,7 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
+import { Switch } from "@/components/ui/switch";
 import { SettingsSection } from "@/screens/settings/settings-section";
 import {
   MAX_CODE_FONT_SIZE,
@@ -189,6 +190,28 @@ function ThemeRow({ value, onChange }: ThemeRowProps) {
   );
 }
 
+interface AutoExpandReasoningRowProps {
+  value: boolean;
+  onChange: (value: boolean) => void;
+}
+
+function AutoExpandReasoningRow({ value, onChange }: AutoExpandReasoningRowProps) {
+  const { t } = useTranslation();
+  return (
+    <View style={settingsStyles.row}>
+      <View style={settingsStyles.rowContent}>
+        <Text style={settingsStyles.rowTitle}>
+          {t("settings.general.autoExpandReasoning.label")}
+        </Text>
+        <Text style={settingsStyles.rowHint}>
+          {t("settings.general.autoExpandReasoning.description")}
+        </Text>
+      </View>
+      <Switch value={value} onValueChange={onChange} />
+    </View>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Fonts: family text fields + numeric size fields (commit on blur/submit)
 // ---------------------------------------------------------------------------
@@ -397,6 +420,13 @@ export function AppearanceSection() {
     [updateSettings],
   );
 
+  const handleAutoExpandReasoningChange = useCallback(
+    (autoExpandReasoning: boolean) => {
+      void updateSettings({ autoExpandReasoning });
+    },
+    [updateSettings],
+  );
+
   const commitUiFontFamily = useCallback(
     (value: string) => {
       const sanitized = sanitizeFontFamily(value);
@@ -477,6 +507,14 @@ export function AppearanceSection() {
           <ThemeRow value={settings.theme} onChange={handleThemeChange} />
         </View>
       </SettingsSection>
+      <SettingsSection title={t("settings.appearance.detailLevel.title")}>
+        <View style={settingsStyles.card}>
+          <AutoExpandReasoningRow
+            value={settings.autoExpandReasoning}
+            onChange={handleAutoExpandReasoningChange}
+          />
+        </View>
+      </SettingsSection>
       <SettingsSection title={t("settings.appearance.fonts.title")}>
         <View style={settingsStyles.card}>
           {showFontFamilyRows ? (

packages/app/src/stores/panel-store/index.ts

@@ -72,6 +72,11 @@ export interface PanelState {
   explorerTabByCheckout: Record<string, ExplorerTab>;
   expandedPathsByWorkspace: Record<string, string[]>;
   diffExpandedPathsByWorkspace: Record<string, string[]>;
+  // Changes-view folder tree. Inverted semantics vs the fields above:
+  // this stores COLLAPSED directory paths (empty = all folders expanded), keyed
+  // by full uncompressed dir path, so folders default to expanded and new
+  // folders stay expanded as the diff changes.
+  diffCollapsedFoldersByWorkspace: Record<string, string[]>;
   sidebarWidth: number;
   explorerWidth: number;
   explorerSortOption: SortOption;
@@ -98,6 +103,7 @@ export interface PanelState {
   setExplorerTabForCheckout: (params: ExplorerCheckoutContext & { tab: ExplorerTab }) => void;
   setExpandedPathsForWorkspace: (workspaceKey: string, paths: string[]) => void;
   setDiffExpandedPathsForWorkspace: (workspaceKey: string, paths: string[]) => void;
+  setDiffCollapsedFoldersForWorkspace: (workspaceKey: string, dirPaths: string[]) => void;
   activateExplorerTabForCheckout: (checkout: ExplorerCheckoutContext) => void;
   setSidebarWidth: (width: number) => void;
   setExplorerWidth: (width: number) => void;
@@ -126,6 +132,7 @@ export const usePanelStore = create<PanelState>()(
       explorerTabByCheckout: {},
       expandedPathsByWorkspace: {},
       diffExpandedPathsByWorkspace: {},
+      diffCollapsedFoldersByWorkspace: {},
       sidebarWidth: DEFAULT_SIDEBAR_WIDTH,
       explorerWidth: DEFAULT_EXPLORER_SIDEBAR_WIDTH,
       explorerSortOption: "name",
@@ -253,6 +260,13 @@ export const usePanelStore = create<PanelState>()(
             [workspaceKey]: paths,
           },
         })),
+      setDiffCollapsedFoldersForWorkspace: (workspaceKey, dirPaths) =>
+        set((state) => ({
+          diffCollapsedFoldersByWorkspace: {
+            ...state.diffCollapsedFoldersByWorkspace,
+            [workspaceKey]: dirPaths,
+          },
+        })),
       activateExplorerTabForCheckout: (checkout) =>
         set((state) => ({
           explorerTab: resolveExplorerTabForCheckout({
@@ -276,7 +290,7 @@ export const usePanelStore = create<PanelState>()(
     }),
     {
       name: "panel-state",
-      version: 11,
+      version: 12,
       storage: createJSONStorage(() => AsyncStorage),
       migrate: (persistedState, version) =>
         migratePanelState(persistedState, version, { isWeb }) as unknown as PanelState,
@@ -287,6 +301,7 @@ export const usePanelStore = create<PanelState>()(
         explorerTabByCheckout: state.explorerTabByCheckout,
         expandedPathsByWorkspace: state.expandedPathsByWorkspace,
         diffExpandedPathsByWorkspace: state.diffExpandedPathsByWorkspace,
+        diffCollapsedFoldersByWorkspace: state.diffCollapsedFoldersByWorkspace,
         sidebarWidth: state.sidebarWidth,
         explorerWidth: state.explorerWidth,
         explorerSortOption: state.explorerSortOption,

packages/app/src/stores/panel-store/state.test.ts

@@ -103,6 +103,20 @@ describe("panel-store migration", () => {
 
     expect(state.explorerShowHiddenFiles).toBe(true);
   });
+
+  it("initializes diffCollapsedFoldersByWorkspace for pre-v12 state", () => {
+    const state = migratePanelState({}, 11, { isWeb: false });
+
+    expect(state.diffCollapsedFoldersByWorkspace).toEqual({});
+  });
+
+  it("preserves an existing diffCollapsedFoldersByWorkspace map", () => {
+    const state = migratePanelState({ diffCollapsedFoldersByWorkspace: { ws: ["src/app"] } }, 12, {
+      isWeb: false,
+    });
+
+    expect(state.diffCollapsedFoldersByWorkspace).toEqual({ ws: ["src/app"] });
+  });
 });
 
 describe("panel-store visibility selectors", () => {

packages/app/src/stores/panel-store/state.ts

@@ -245,6 +245,13 @@ export function migratePanelState(
   ) {
     state.diffExpandedPathsByWorkspace = {};
   }
+  if (
+    version < 12 ||
+    typeof state.diffCollapsedFoldersByWorkspace !== "object" ||
+    !state.diffCollapsedFoldersByWorkspace
+  ) {
+    state.diffCollapsedFoldersByWorkspace = {};
+  }
   if (typeof state.explorerShowHiddenFiles !== "boolean") {
     state.explorerShowHiddenFiles = true;
   }

packages/app/src/voice/audio-engine-types.ts

@@ -1,6 +1,7 @@
 export interface AudioEngineCallbacks {
   onCaptureData(pcm: Uint8Array): void;
   onVolumeLevel(level: number): void;
+  onInterruption?(): void;
   onError?(error: Error): void;
 }
 

packages/app/src/voice/audio-engine.native.ts

@@ -116,6 +116,21 @@ export function createAudioEngine(
       callbacks.onVolumeLevel(level);
     },
   );
+  const interruptionSubscription = native.addExpoTwoWayAudioEventListener(
+    "onAudioInterruption",
+    (event: { data: string }) => {
+      if (event.data !== "blocked") {
+        return;
+      }
+      const wasCaptureActive = refs.captureActive;
+      refs.captureActive = false;
+      refs.muted = false;
+      callbacks.onVolumeLevel(0);
+      if (wasCaptureActive) {
+        callbacks.onInterruption?.();
+      }
+    },
+  );
 
   async function ensureInitialized(): Promise<void> {
     if (refs.initialized) {
@@ -234,6 +249,7 @@ export function createAudioEngine(
       }
       microphoneSubscription.remove();
       volumeSubscription.remove();
+      interruptionSubscription.remove();
     },
 
     async startCapture() {
@@ -244,7 +260,12 @@ export function createAudioEngine(
       try {
         await ensureMicrophonePermission();
         await ensureInitialized();
-        native.toggleRecording(true);
+        const isRecording = native.toggleRecording(true);
+        if (!isRecording) {
+          throw new Error(
+            "Microphone capture could not start because Android audio focus is unavailable.",
+          );
+        }
         refs.captureActive = true;
       } catch (error) {
         const wrapped = error instanceof Error ? error : new Error(String(error));

packages/app/src/voice/voice-runtime.test.ts

@@ -423,6 +423,22 @@ describe("voice runtime", () => {
     expect(runtime.shouldPlayVoiceAudio("server-1")).toBe(false);
   });
 
+  it("rolls daemon voice mode back when capture fails after enabling it", async () => {
+    const adapter = createSessionAdapter();
+    const engine = createAudioEngineMock();
+    vi.mocked(engine.startCapture).mockRejectedValue(new Error("audio focus unavailable"));
+    const { runtime } = createRuntime({ engine });
+    runtime.registerSession(adapter);
+
+    await expect(runtime.startVoice("server-1", "agent-1")).rejects.toThrow(
+      "audio focus unavailable",
+    );
+
+    expect(adapter.setVoiceMode).toHaveBeenNthCalledWith(1, true, "agent-1");
+    expect(adapter.setVoiceMode).toHaveBeenNthCalledWith(2, false);
+    expect(runtime.getSnapshot().phase).toBe("disabled");
+  });
+
   it("returns an explicit not-ready error when the adapter is missing", async () => {
     const { runtime } = createRuntime();
     await expect(runtime.startVoice("server-1", "agent-1")).rejects.toThrow(

packages/app/src/voice/voice-runtime.ts

@@ -730,6 +730,7 @@ export function createVoiceRuntime(deps: VoiceRuntimeDeps): VoiceRuntime {
       const previousServerId = state.snapshot.activeServerId;
       const previousAgentId = state.snapshot.activeAgentId;
       const generation = state.generation + 1;
+      let enabledCurrentVoiceMode = false;
       state.generation = generation;
       state.transportReady = false;
       patchSnapshot((prev) => ({
@@ -759,6 +760,7 @@ export function createVoiceRuntime(deps: VoiceRuntimeDeps): VoiceRuntime {
 
         await deps.engine.initialize();
         await session.adapter.setVoiceMode(true, agentId);
+        enabledCurrentVoiceMode = true;
         await deps.engine.startCapture();
         if (state.generation !== generation) {
           return;
@@ -776,6 +778,9 @@ export function createVoiceRuntime(deps: VoiceRuntimeDeps): VoiceRuntime {
           isMuted: deps.engine.isMuted(),
         }));
       } catch (error) {
+        if (enabledCurrentVoiceMode) {
+          await session.adapter.setVoiceMode(false).catch(() => undefined);
+        }
         await performLocalStop();
         throw error;
       }

packages/expo-two-way-audio/android/src/main/java/expo/modules/twowayaudio/AudioEngine.kt

@@ -83,7 +83,9 @@ class AudioEngine (context: Context) {
     private fun initializeAudio(context:Context) {
         audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
         audioManager.mode = AudioManager.MODE_IN_COMMUNICATION
-        requestAudioFocus()
+        if (!requestAudioFocus()) {
+            handleAudioFocusBlocked()
+        }
 
         // Route audio to external device if connected, otherwise route to speaker
         updateAudioRouting()
@@ -168,7 +170,12 @@ class AudioEngine (context: Context) {
     }
 
     @SuppressLint("NewApi")
-    private fun requestAudioFocus() {
+    private fun requestAudioFocus(): Boolean {
+        audioFocusRequest?.let { request ->
+            audioManager.abandonAudioFocusRequest(request)
+            audioFocusRequest = null
+        }
+
         val focusRequest =
             AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE)
                 .setAudioAttributes(
@@ -180,9 +187,19 @@ class AudioEngine (context: Context) {
                 .setAcceptsDelayedFocusGain(true)
                 .setOnAudioFocusChangeListener { focusChange ->
                     when (focusChange) {
+                        AudioManager.AUDIOFOCUS_GAIN -> {
+                            Log.d("AudioEngine", "Audio focus gained")
+                        }
                         AudioManager.AUDIOFOCUS_LOSS -> {
                             Log.d("AudioEngine", "Audio focus lost")
-                            onAudioInterruptionCallback?.let { it("blocked") }
+                            handleAudioFocusBlocked()
+                        }
+                        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
+                            Log.d("AudioEngine", "Audio focus lost transiently")
+                            handleAudioFocusBlocked()
+                        }
+                        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
+                            Log.d("AudioEngine", "Audio focus duck requested")
                         }
                     }
                 }
@@ -191,14 +208,40 @@ class AudioEngine (context: Context) {
         audioFocusRequest = focusRequest
         val result = audioManager.requestAudioFocus(focusRequest)
 
-        if (result != AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
-            throw RuntimeException("Audio focus request failed")
+        if (result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
+            return true
         }
+
+        Log.w("AudioEngine", "Audio focus request was not granted: $result")
+        return false
+    }
+
+    private fun handleAudioFocusBlocked() {
+        if (isRecording) {
+            stopRecording()
+        }
+        audioFocusRequest?.let { request ->
+            audioManager.abandonAudioFocusRequest(request)
+            audioFocusRequest = null
+        }
+        if (::audioTrack.isInitialized) {
+            audioTrack.pause()
+        }
+        audioSampleQueue.clear()
+        isPlaying = false
+        isRecordingBeforePause = false
+        onOutputVolumeCallback?.invoke(0.0F)
+        onAudioInterruptionCallback?.let { it("blocked") }
     }
 
     @RequiresApi(Build.VERSION_CODES.Q)
     @SuppressLint("MissingPermission")
-    private fun startRecording(){
+    private fun startRecording(): Boolean {
+        if (!requestAudioFocus()) {
+            handleAudioFocusBlocked()
+            return false
+        }
+
         val bufferSize = AudioRecord.getMinBufferSize(SAMPLE_RATE, CHANNEL_CONFIG, AUDIO_FORMAT)
         audioRecord = AudioRecord(
             MediaRecorder.AudioSource.VOICE_COMMUNICATION,
@@ -231,6 +274,7 @@ class AudioEngine (context: Context) {
         audioRecord.startRecording()
         isRecording = true
         startMicSampleTap()
+        return true
     }
 
     private fun startMicSampleTap(){
@@ -274,7 +318,7 @@ class AudioEngine (context: Context) {
         if (value == isRecording) return isRecording
 
         if (value) {
-            startRecording()
+            return startRecording()
         } else {
             stopRecording()
         }
@@ -353,8 +397,15 @@ class AudioEngine (context: Context) {
 
     @RequiresApi(Build.VERSION_CODES.Q)
     fun resumeRecordingAndPlayer() {
-        requestAudioFocus()
-        isRecording = toggleRecording(isRecordingBeforePause)
+        if (!requestAudioFocus()) {
+            handleAudioFocusBlocked()
+            return
+        }
+        val wasRecordingBeforePause = isRecordingBeforePause
+        isRecording = toggleRecording(wasRecordingBeforePause)
+        if (wasRecordingBeforePause && !isRecording) {
+            return
+        }
         audioTrack.play()
     }
 

packages/server/src/server/agent/providers/pi/cli-runtime.test.ts

@@ -61,16 +61,29 @@ function replyToCommands(
       const line = buffer.slice(0, newlineIndex);
       buffer = buffer.slice(newlineIndex + 1);
       const command = JSON.parse(line) as Record<string, unknown>;
-      const result = handler(command);
-      child.stdout.write(
-        `${JSON.stringify({
-          id: command.id,
-          type: "response",
-          command: command.type,
-          success: true,
-          data: result,
-        })}\n`,
-      );
+      try {
+        const result = handler(command);
+        child.stdout.write(
+          `${JSON.stringify({
+            id: command.id,
+            type: "response",
+            command: command.type,
+            success: true,
+            data: result,
+          })}\n`,
+        );
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        child.stdout.write(
+          `${JSON.stringify({
+            id: command.id,
+            type: "response",
+            command: command.type,
+            success: false,
+            error: message,
+          })}\n`,
+        );
+      }
     }
   });
 }
@@ -257,4 +270,102 @@ describe("PiCliRuntime", () => {
 
     expect(child.killedSignals).toContain("SIGTERM");
   });
+
+  test("falls back to get_state when get_session_stats is unsupported", async () => {
+    const child = createPiChild();
+    let commandSequence: string[] = [];
+    replyToCommands(child, (command) => {
+      commandSequence.push(String(command.type));
+      if (command.type === "get_session_stats") {
+        // Simulate older OMP binary that doesn't support this RPC
+        throw new Error(`Unknown command: ${command.type}`);
+      }
+      // get_state returns contextUsage for fallback
+      return {
+        sessionId: "pi-session-1",
+        thinkingLevel: "medium" as const,
+        isStreaming: false,
+        isCompacting: false,
+        steeringMode: "one-at-a-time" as const,
+        followUpMode: "one-at-a-time" as const,
+        interruptMode: "immediate" as const,
+        messageCount: 0,
+        queuedMessageCount: 0,
+        todoPhases: [],
+        contextUsage: { tokens: 1_100, contextWindow: 200_000 },
+      };
+    });
+    const session = await createRuntime(child).startSession({ cwd: "/workspace/project" });
+
+    const stats = await session.getSessionStats();
+
+    expect(stats.contextUsage).toEqual({
+      tokens: 1_100,
+      contextWindow: 200_000,
+    });
+    expect(commandSequence).toEqual(["get_session_stats", "get_state"]);
+  });
+
+  test("returns full stats from get_session_stats without falling back", async () => {
+    const child = createPiChild();
+    let fallbackCalled = false;
+    replyToCommands(child, (command) => {
+      if (command.type === "get_state") {
+        fallbackCalled = true;
+      }
+      return {
+        tokens: { input: 500, output: 300, cacheRead: 100 },
+        cost: 0.02,
+        contextUsage: { tokens: 800, contextWindow: 200_000 },
+      };
+    });
+    const session = await createRuntime(child).startSession({ cwd: "/workspace/project" });
+
+    const stats = await session.getSessionStats();
+
+    expect(stats).toMatchObject({
+      tokens: { input: 500, output: 300, cacheRead: 100 },
+      cost: 0.02,
+      contextUsage: { tokens: 800, contextWindow: 200_000 },
+    });
+    // Should NOT have called get_state as a fallback
+    expect(fallbackCalled).toBe(false);
+  });
+
+  test("does not fall back when get_session_stats returns cost:0", async () => {
+    const child = createPiChild();
+    let fallbackCalled = false;
+    replyToCommands(child, (command) => {
+      if (command.type === "get_state") {
+        fallbackCalled = true;
+      }
+      return {
+        tokens: { input: 200, output: 100 },
+        cost: 0,
+        contextUsage: { tokens: 500, contextWindow: 200_000 },
+      };
+    });
+    const session = await createRuntime(child).startSession({ cwd: "/workspace/project" });
+
+    const stats = await session.getSessionStats();
+
+    expect(stats.tokens).toEqual({ input: 200, output: 100 });
+    expect(stats.cost).toBe(0);
+    expect(stats.contextUsage).toEqual({ tokens: 500, contextWindow: 200_000 });
+    // Should NOT have called get_state as a fallback
+    expect(fallbackCalled).toBe(false);
+  });
+
+  test("returns empty object when both get_session_stats and get_state fail", async () => {
+    const child = createPiChild();
+    replyToCommands(child, (command) => {
+      throw new Error(`Unknown command: ${command.type}`);
+    });
+    const session = await createRuntime(child).startSession({ cwd: "/workspace/project" });
+
+    const stats = await session.getSessionStats();
+
+    // Neither RPC returned usable data — should resolve with empty object
+    expect(stats).toEqual({});
+  });
 });

packages/server/src/server/agent/providers/pi/cli-runtime.ts

@@ -180,7 +180,35 @@ class PiCliRuntimeSession implements PiRuntimeSession {
   }
 
   async getSessionStats(): Promise<PiSessionStats> {
-    return (await this.request({ type: "get_session_stats" })) as PiSessionStats;
+    // COMPAT(piGetStateFallback): added in v0.1.X — older Oh My Pi binaries
+    // lack the `get_session_stats` RPC command; fall back to extracting
+    // context window usage from `get_state`. Drop this gate when the floor
+    // daemon supports get_session_stats (added ~v0.1.97).
+    let stats: PiSessionStats | undefined;
+    try {
+      stats = (await this.request({ type: "get_session_stats" })) as PiSessionStats;
+    } catch {
+      // get_session_stats not supported by this binary — will try get_state below
+    }
+    if (stats?.tokens == null && stats?.cost == null && stats?.contextUsage == null) {
+      try {
+        const state = (await this.request({ type: "get_state" })) as Record<string, unknown>;
+        const ctx = state.contextUsage as
+          | { tokens?: number | null; contextWindow?: number | null }
+          | undefined;
+        if (ctx) {
+          return {
+            contextUsage: {
+              tokens: typeof ctx.tokens === "number" ? ctx.tokens : undefined,
+              contextWindow: typeof ctx.contextWindow === "number" ? ctx.contextWindow : undefined,
+            },
+          };
+        }
+      } catch {
+        // get_state also failed — nothing we can do
+      }
+    }
+    return stats ?? {};
   }
 
   async getCommands(): Promise<PiRpcSlashCommand[]> {

packages/server/src/server/pid-lock.test.ts

@@ -1,4 +1,4 @@
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, test } from "vitest";
@@ -49,4 +49,31 @@ describe("pid-lock ownership", () => {
       await rm(paseoHome, { recursive: true, force: true });
     }
   });
+
+  test("reclaims a stale lock when the recorded pid belongs to a different process", async () => {
+    const paseoHome = await mkdtemp(join(tmpdir(), "paseo-pid-lock-reused-"));
+    const replacementOwnerPid = process.pid + 10_000;
+
+    try {
+      await writeFile(
+        join(paseoHome, "paseo.pid"),
+        JSON.stringify({
+          pid: process.pid,
+          startedAt: "2026-01-01T00:00:00.000Z",
+          hostname: "old-host",
+          uid: process.getuid?.() ?? 0,
+          listen: "127.0.0.1:6767",
+          desktopManaged: true,
+        }),
+      );
+
+      await acquirePidLock(paseoHome, null, { ownerPid: replacementOwnerPid });
+
+      const lock = await getPidLockInfo(paseoHome);
+      expect(lock?.pid).toBe(replacementOwnerPid);
+      expect(lock?.listen).toBeNull();
+    } finally {
+      await rm(paseoHome, { recursive: true, force: true });
+    }
+  });
 });

packages/server/src/server/pid-lock.ts

@@ -1,5 +1,6 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 import { open, readFile, unlink, mkdir } from "node:fs/promises";
-import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { hostname } from "node:os";
 import { z } from "zod";
@@ -34,6 +35,11 @@ export class PidLockError extends Error {
   }
 }
 
+const PROCESS_START_SKEW_TOLERANCE_MS = 60_000;
+const PROCESS_LOCK_ACQUIRE_TOLERANCE_MS = 5 * 60_000;
+const POSIX_PROCESS_TIME_ENV = { ...process.env, LC_ALL: "C", LANG: "C" };
+let cachedClockTicksPerSecond: number | null = null;
+
 function isPidRunning(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -43,6 +49,126 @@ function isPidRunning(pid: number): boolean {
   }
 }
 
+function readClockTicksPerSecond(): number {
+  if (cachedClockTicksPerSecond !== null) {
+    return cachedClockTicksPerSecond;
+  }
+
+  try {
+    const output = execFileSync("getconf", ["CLK_TCK"], {
+      encoding: "utf8",
+      timeout: 1000,
+    }).trim();
+    const value = Number(output);
+    cachedClockTicksPerSecond = Number.isFinite(value) && value > 0 ? value : 100;
+  } catch {
+    cachedClockTicksPerSecond = 100;
+  }
+
+  return cachedClockTicksPerSecond;
+}
+
+function readLinuxProcessStartedAtMs(pid: number): number | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    const closeParen = stat.lastIndexOf(")");
+    if (closeParen === -1) return null;
+
+    const fieldsAfterCommand = stat
+      .slice(closeParen + 2)
+      .trim()
+      .split(/\s+/);
+    const startTicks = Number(fieldsAfterCommand[19]);
+    if (!Number.isFinite(startTicks)) return null;
+
+    const bootTimeLine = readFileSync("/proc/stat", "utf8")
+      .split("\n")
+      .find((line) => line.startsWith("btime "));
+    const bootSeconds = Number(bootTimeLine?.trim().split(/\s+/)[1]);
+    if (!Number.isFinite(bootSeconds)) return null;
+
+    return bootSeconds * 1000 + (startTicks / readClockTicksPerSecond()) * 1000;
+  } catch {
+    return null;
+  }
+}
+
+function readPsProcessStartedAtMs(pid: number): number | null {
+  try {
+    const output = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
+      encoding: "utf8",
+      env: POSIX_PROCESS_TIME_ENV,
+      timeout: 1000,
+    }).trim();
+    const parsed = Date.parse(output);
+    return Number.isFinite(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function readWindowsProcessStartedAtMs(pid: number): number | null {
+  try {
+    const command = [
+      `$p = Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}"`,
+      'if ($p) { $p.CreationDate.ToUniversalTime().ToString("o") }',
+    ].join("; ");
+    const output = execFileSync(
+      "powershell.exe",
+      ["-NoProfile", "-NonInteractive", "-Command", command],
+      {
+        encoding: "utf8",
+        timeout: 3000,
+      },
+    ).trim();
+    const parsed = Date.parse(output);
+    return Number.isFinite(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function readProcessStartedAtMs(pid: number): number | null {
+  if (process.platform === "linux") {
+    return readLinuxProcessStartedAtMs(pid) ?? readPsProcessStartedAtMs(pid);
+  }
+  if (process.platform === "win32") {
+    return readWindowsProcessStartedAtMs(pid);
+  }
+  return readPsProcessStartedAtMs(pid);
+}
+
+function lockMatchesLiveProcessIdentity(lock: PidLockInfo): boolean {
+  const lockStartedAtMs = Date.parse(lock.startedAt);
+  if (!Number.isFinite(lockStartedAtMs)) {
+    return false;
+  }
+
+  const processStartedAtMs = readProcessStartedAtMs(lock.pid);
+  if (processStartedAtMs === null) {
+    return true;
+  }
+
+  if (processStartedAtMs - lockStartedAtMs > PROCESS_START_SKEW_TOLERANCE_MS) {
+    return false;
+  }
+  if (lockStartedAtMs - processStartedAtMs > PROCESS_LOCK_ACQUIRE_TOLERANCE_MS) {
+    return false;
+  }
+
+  return true;
+}
+
+function isPidLockOwnerRunning(lock: PidLockInfo): boolean {
+  if (!isPidRunning(lock.pid)) {
+    return false;
+  }
+
+  // PIDs can be reused after an unclean daemon exit. Treat a live PID as the
+  // lock owner only when its process start time still lines up with the lock.
+  return lockMatchesLiveProcessIdentity(lock);
+}
+
 function getPidFilePath(paseoHome: string): string {
   return join(paseoHome, "paseo.pid");
 }
@@ -78,7 +204,7 @@ export async function acquirePidLock(
   // Check if existing lock is stale
   const lockOwnerPid = resolveOwnerPid(options?.ownerPid);
   if (existingLock) {
-    if (isPidRunning(existingLock.pid)) {
+    if (isPidLockOwnerRunning(existingLock)) {
       if (existingLock.pid === lockOwnerPid) {
         return;
       }
@@ -197,7 +323,7 @@ export async function isLocked(
   if (!info) {
     return { locked: false };
   }
-  if (!isPidRunning(info.pid)) {
+  if (!isPidLockOwnerRunning(info)) {
     return { locked: false, info };
   }
   return { locked: true, info };

public-docs/browser-tools.md

@@ -2,7 +2,7 @@
 title: Browser tools
 description: The browser_* MCP tools agents use to drive Paseo browser tabs.
 nav: Tools reference
-order: 36
+order: 37
 category: Browser
 ---
 

public-docs/browser-when.md

@@ -0,0 +1,21 @@
+---
+title: When to use the Paseo browser
+description: When to reach for Paseo's built-in browser instead of Playwright or agent-browser.
+nav: When to use
+order: 36
+category: Browser
+---
+
+# When to use
+
+Paseo gives agents a [real browser inside Paseo](/docs/browser). Standalone tools like Playwright or agent-browser give an agent its own browser in a separate process. They overlap, so which one?
+
+Use the Paseo browser when:
+
+- **You're running agents remotely and want to watch.** You see the same browser the agent is driving, live in the Paseo desktop app — not a headless browser on a box you can't see.
+- **You want the browser inside Paseo.** It's a tab in the same session, not a separate agent window to manage.
+- **You don't want to set up extra tools.** It's built in — no separate MCP server or CLI to install and wire up.
+
+Reach for Playwright or agent-browser when the browser work stands on its own — headless CI runs, an existing test suite, or automation that isn't tied to an agent session in Paseo.
+
+The Paseo browser is [desktop only for now](/docs/browser).

public-docs/browser.md

@@ -1,7 +1,7 @@
 ---
 title: Browser automation
 description: Give agents a real browser inside Paseo to open pages, click, type, and verify their work.
-nav: Browser automation
+nav: Overview
 order: 35
 category: Browser
 ---

public-docs/cli.md

@@ -91,6 +91,16 @@ paseo wait <id> --timeout 60   # 60 second timeout
 
 Useful in scripts or when one agent needs to wait for another.
 
+## Schedules
+
+Run an agent on an interval or a cron. See [Schedules from the CLI](/docs/schedules-cli) for the full reference.
+
+```bash
+paseo schedule create --every 30m --cwd ~/dev/my-app "Continue the refactor and leave a note."
+paseo schedule ls
+paseo schedule pause <id>
+```
+
 ## Permissions
 
 Agents may request permission for certain actions. Manage these from the CLI:

public-docs/mcp.md

@@ -3,7 +3,7 @@ title: Paseo MCP
 description: Paseo MCP tools injected into agents.
 nav: Paseo MCP
 order: 30
-category: Automation
+category: Orchestration
 ---
 
 # Paseo MCP

public-docs/schedules-chat.md

@@ -0,0 +1,21 @@
+---
+title: Schedules from chat
+description: Ask an agent in chat to set up and manage a schedule for you.
+nav: Chat
+order: 26
+category: Schedules
+---
+
+# Schedules from chat
+
+You don't have to fill in a form. In any agent chat, just ask, and the agent sets up the schedule for you through [Paseo MCP](/docs/mcp).
+
+Example prompts:
+
+- "Every weekday at 9am, triage new GitHub issues and PRs and summarize what needs attention."
+- "Check the release build every 5 minutes until it passes, and fix the cause if it fails."
+- "Keep working on this refactor — wake yourself every 20 minutes and continue where you left off."
+
+The agent picks the cadence, target, and prompt from what you asked, creates the schedule, and reports back. You can manage it the same way — "pause the triage schedule", "make the build check run every 2 minutes instead", "delete it" — or from the [Schedules view](/docs/schedules) and the [CLI](/docs/schedules-cli).
+
+An agent scheduling itself to wake up later is a **heartbeat**. See [Paseo MCP](/docs/mcp) for the underlying tools.

public-docs/schedules-cli.md

@@ -0,0 +1,94 @@
+---
+title: Schedules from the CLI
+description: Create and manage Paseo schedules with paseo schedule.
+nav: CLI
+order: 27
+category: Schedules
+---
+
+# Schedules from the CLI
+
+`paseo schedule` creates and manages [schedules](/docs/schedules) from your terminal, useful for headless boxes and scripts.
+
+## Create
+
+Overnight refactor on Codex:
+
+```bash
+paseo schedule create \
+  --every 30m \
+  --name overnight-refactor \
+  --provider codex/gpt-5.5 \
+  --cwd ~/dev/my-app \
+  --max-runs 16 \
+  --expires-in 10h \
+  "Continue the refactor. Run the focused checks. Leave a short status note."
+```
+
+Long build babysitter on Claude:
+
+```bash
+paseo schedule create \
+  --every 5m \
+  --name build-watch \
+  --provider claude/opus-4.7 \
+  --cwd ~/dev/my-app \
+  --max-runs 24 \
+  "Check the release build. If it failed, inspect logs, fix the cause, and rerun."
+```
+
+Daily GitHub triage on GLM through OpenCode:
+
+```bash
+paseo schedule create \
+  --cron "0 14 * * 1-5" \
+  --timezone UTC \
+  --run-now \
+  --name github-triage \
+  --provider opencode/openrouter/glm-5.1 \
+  --cwd ~/dev/my-app \
+  "Triage GitHub issues, PRs, and failing checks. Summarize what needs attention."
+```
+
+Morning triage at 9 AM in New York, including daylight saving time changes:
+
+```bash
+paseo schedule create \
+  --cron "0 9 * * 1-5" \
+  --timezone America/New_York \
+  --name morning-triage \
+  --provider codex/gpt-5.5 \
+  --cwd ~/dev/my-app \
+  "Review overnight CI failures and summarize anything urgent."
+```
+
+Heartbeat the current agent:
+
+```bash
+paseo schedule create \
+  --every 20m \
+  --target self \
+  --name heartbeat \
+  "Check the current task state and continue with the next useful step."
+```
+
+## Manage
+
+```bash
+paseo schedule ls
+paseo schedule inspect <id>
+paseo schedule logs <id>
+paseo schedule pause <id>
+paseo schedule resume <id>
+paseo schedule run-once <id>
+paseo schedule update <id> --every 10m --max-runs 6
+paseo schedule delete <id>
+```
+
+## Cadence
+
+Use `--every <duration>` for intervals and `--cron "<expr>"` for 5-field cron. Cron schedules default to UTC. Pass `--timezone <IANA>` to interpret cron fields in a local wall-clock time zone, for example `--timezone America/New_York`. The persisted `nextRunAt` is still a UTC instant, but it is computed from that local time zone so recurring jobs stay at the same local time across daylight saving time changes.
+
+Interval schedules run once immediately by default; pass `--no-run-now` to wait for the first interval. Cron schedules wait for the next matching time; pass `--run-now` to fire once immediately.
+
+When targeting a remote daemon with `--host`, pass `--cwd`; your local working directory may not exist on the remote machine.

public-docs/schedules.md

@@ -1,114 +1,34 @@
 ---
 title: Schedules
-description: Run Paseo agents on intervals or cron.
-nav: Schedules
-order: 31
-category: Automation
+description: Run Paseo agents on a schedule — every few minutes or on a cron.
+nav: Overview
+order: 25
+category: Schedules
 ---
 
 # Schedules
 
-Schedules let agents come back later.
-
-Think of a schedule as a standing instruction: at this cadence, run this prompt, in this repo, with this agent target.
+A schedule runs an agent for you on a cadence: at this interval or cron time, run this prompt, in this repo, with this agent.
 
 The target can be:
 
-- A new agent each time, useful for fresh daily jobs and long-running watchers.
-- An existing agent, useful when you want continuity.
-- The same agent that created the schedule, useful for heartbeats from inside an agent.
+- A new agent each run — fresh daily jobs and long-running watchers.
+- An existing agent — when you want continuity.
+- The agent that created the schedule — heartbeats from inside an agent.
 
-Schedules can use interval cadence, like every 30 minutes, or cron cadence, like every weekday morning. Runs are recorded, can be inspected later, and can be paused, resumed, triggered once, updated, or deleted.
+Cadence is either an interval, like every 30 minutes, or a cron expression, like every weekday morning. Every run is recorded, and you can pause, resume, run once, update, or delete a schedule at any time.
 
-## Uses
+## What it's for
 
-- **Overnight refactoring loops:** wake an agent every 30 minutes to continue a scoped refactor, run checks, and leave notes.
-- **Heartbeats:** have the same agent periodically reassess state and keep moving.
-- **Long build babysitting:** check CI, EAS, Docker, or release builds until they pass.
-- **Daily GitHub triage:** scan issues, PRs, notifications, and flaky checks every morning.
-- **Maintenance sweeps:** refresh dependencies, audit docs, clean stale branches, or summarize repo health.
+- **Overnight refactors:** wake an agent every 30 minutes to continue a scoped refactor, run checks, and leave notes.
+- **Heartbeats:** have an agent periodically reassess state and keep moving.
+- **Build babysitting:** check CI, EAS, Docker, or release builds until they pass.
+- **Daily triage:** scan issues, PRs, and failing checks every morning.
+- **Maintenance sweeps:** refresh dependencies, audit docs, or clean stale branches.
 
-## Setup Examples
+## Ways to create one
 
-Overnight refactor on Codex:
-
-```bash
-paseo schedule create \
-  --every 30m \
-  --name overnight-refactor \
-  --provider codex/gpt-5.5 \
-  --cwd ~/dev/my-app \
-  --max-runs 16 \
-  --expires-in 10h \
-  "Continue the refactor. Run the focused checks. Leave a short status note."
-```
-
-Long build babysitter on Claude:
-
-```bash
-paseo schedule create \
-  --every 5m \
-  --name build-watch \
-  --provider claude/opus-4.7 \
-  --cwd ~/dev/my-app \
-  --max-runs 24 \
-  "Check the release build. If it failed, inspect logs, fix the cause, and rerun."
-```
-
-Daily GitHub triage on GLM through OpenCode:
-
-```bash
-paseo schedule create \
-  --cron "0 14 * * 1-5" \
-  --timezone UTC \
-  --run-now \
-  --name github-triage \
-  --provider opencode/openrouter/glm-5.1 \
-  --cwd ~/dev/my-app \
-  "Triage GitHub issues, PRs, and failing checks. Summarize what needs attention."
-```
-
-Morning triage at 9 AM in New York, including daylight saving time changes:
-
-```bash
-paseo schedule create \
-  --cron "0 9 * * 1-5" \
-  --timezone America/New_York \
-  --name morning-triage \
-  --provider codex/gpt-5.5 \
-  --cwd ~/dev/my-app \
-  "Review overnight CI failures and summarize anything urgent."
-```
-
-Heartbeat the current agent:
-
-```bash
-paseo schedule create \
-  --every 20m \
-  --target self \
-  --name heartbeat \
-  "Check the current task state and continue with the next useful step."
-```
-
-## Managing Schedules
-
-```bash
-paseo schedule ls
-paseo schedule inspect <id>
-paseo schedule logs <id>
-paseo schedule pause <id>
-paseo schedule resume <id>
-paseo schedule run-once <id>
-paseo schedule update <id> --every 10m --max-runs 6
-paseo schedule delete <id>
-```
-
-Use `--every <duration>` for intervals and `--cron "<expr>"` for 5-field cron. Cron schedules default to UTC. Pass `--timezone <IANA>` to interpret cron fields in a local wall-clock time zone, for example `--timezone America/New_York`. The persisted `nextRunAt` is still a UTC instant, but it is computed from that local time zone so recurring jobs stay at the same local time across daylight saving time changes.
-
-Interval schedules run once immediately by default; pass `--no-run-now` to wait for the first interval. Cron schedules wait for the next matching time; pass `--run-now` to fire once immediately.
-
-When targeting a remote daemon with `--host`, pass `--cwd`; your local working directory may not exist on the remote machine.
-
-## MCP
-
-Agents can create and manage schedules through [Paseo MCP](/docs/mcp).
+- **In the app** — open the Schedules view and create one with an agent, a cadence, a repo, and a prompt. This is the main way to create and manage schedules.
+- **[From chat](/docs/schedules-chat)** — ask the agent in a chat and it sets the schedule up for you.
+- **[From the CLI](/docs/schedules-cli)** — `paseo schedule create`, for headless boxes and scripts.
+- **[Over MCP](/docs/mcp)** — agents create and manage schedules programmatically.

public-docs/skills.md

@@ -3,7 +3,7 @@ title: Orchestration skills
 description: "Paseo orchestration skills: teach coding agents to spawn, coordinate, and manage other agents using slash commands."
 nav: Skills
 order: 32
-category: Automation
+category: Orchestration
 ---
 
 # Orchestration skills

public-docs/troubleshooting.md

@@ -1,7 +1,7 @@
 ---
 title: Troubleshooting
 description: Why Paseo can't find a provider you've installed, and how to fix the PATH and environment mismatches behind most setup issues.
-nav: Troubleshooting
+nav: Common problems
 order: 50
 category: Troubleshooting
 ---