@stevecastaneda/paseo-progress 1.1.0 → 1.2.0

package/OVERVIEW.md

@@ -1,6 +1,6 @@
 Progress gives each worktree a live dashboard for long agent jobs. The agent records its tickets or steps with a `paseo-progress` command, along with what's stuck, questions for you and finished work. The Progress panel in Explorer shows all of it. Needs Paseo 0.11 or later, and Node.js 22.18 or later on the computer running the Paseo daemon.
 
-The panel shows how much of the estimated work is done, what the agent is doing right now, and where each ticket stands. A ticket turns stuck when it's blocked or runs past its estimate without an update. Press a ticket to see its timeline, activity, questions and deliverables. Images, videos and text files the agent records open in a preview inside Paseo. Videos play only in the desktop app. Any other file opens in an app on the computer running the Paseo daemon, and so does a previewed file when you press Open. That's true from your phone too. The app opens on that computer, not on the phone.
+The panel shows how much of the estimated work is done, what the agent is doing right now, and where each ticket stands. A ticket turns stuck when it's blocked or runs past its estimate without an update. Press a ticket to see its timeline, activity, questions and deliverables. Images, videos and text files the agent records open in a preview inside Paseo, and a folder opens as a list of its files. Videos play only in the desktop app. Any other file opens in an app on the computer running the Paseo daemon, and so does a previewed file when you press Open. Open is hidden when that computer can't open files, like a Linux server with no desktop. That's true from your phone too. The app opens on that computer, not on the phone.
 
 When the agent needs a decision, it asks a numbered question with lettered options and says which one it recommends. A pill above the message box counts open questions and stuck work. Each option has a Copy button. Paste the answer into the chat and the agent records it.
 

package/README.md

@@ -13,7 +13,7 @@ The dashboard shows:
 - percent of estimated work done, time done of time estimated (like "1h 30m of 2h"; once everything is done, how long it really took), and a bar with one segment per ticket
 - **Stuck:** blocked tickets, working tickets with no update for longer than their estimate, and blockers the agent flags
 - **Tickets:** estimate, status, and the working ticket's stage. A ticket that waits for another (`--waits-for T03`) shows "Waits for Ticket 03" under its title until that one is done; waiting is the order of work, so it never counts as stuck, even if the agent also marked it blocked. Press a ticket for its story in a dialog. A summary on top shows its status and stage, time worked against the estimate as a bar that turns red past it, the agent's latest status line while it's working, and the agent on it. Tabs below hold the rest, each only when it has something: the ticket's write-up when it has a `--source` file (the start of it, with the rest a press away), a timeline of its stages and statuses with how long each took, and the activity, questions and deliverables that belong to it. The agent on a ticket shows by its chat title; pressing it opens that chat. Items tagged with `--ticket` belong exactly; older, untagged ones are matched by when they happened and marked "by time"
-- **Questions:** each with a permanent reference (Q1, Q2, ...), lettered options, and the option the agent recommends. The agent builds nothing a question affects until you answer; it works on other things meanwhile, and stops when nothing else is left. Press a question to open it in a dialog, then press **Copy Q2 B** to copy `Q2 (title): B` for your reply. Files and links the agent attached (`--file`) open like deliverables: images, videos and text files preview in Paseo (with **Back** to the question), links open in Paseo's browser, and other files open in their default app. From the pill's popover, the preview opens over the popover, which stays open so you can go back to it. Answers stay listed under the same reference.
+- **Questions:** each with a permanent reference (Q1, Q2, ...), lettered options, and the option the agent recommends. The agent builds nothing a question affects until you answer; it works on other things meanwhile, and stops when nothing else is left. Press a question to open it in a dialog, then press **Copy Q2 B** to copy `Q2 (title): B` for your reply. Files and links the agent attached (`--file`) open like deliverables: images, videos and text files preview in Paseo (with **Back** to the question), a folder lists its files there, links open in Paseo's browser, and other files open in their default app. From the pill's popover, the preview opens over the popover, which stays open so you can go back to it. Answers stay listed under the same reference.
 - **Activity**, **Answered** questions and **Deliverables** (press one to open it), sharing one card with a tab for each; the panel remembers the tab you picked. Each shows the newest 10, with **Show 10 older** below
 
 <img src="images/2-ticket.png" alt="A ticket's story: its status, time against the estimate, the agent on it, and its timeline" width="400"> <img src="images/3-question.png" alt="A question waiting for an answer, with lettered options, the agent's recommendation and Copy buttons" width="400">
@@ -100,7 +100,7 @@ paseo-progress finish "Snapshots ship for all four tables"
 - `ticket add` and `ticket update` take an optional `--source <path or link>[=<label>]`: where the ticket is written up, like its spec file or issue. It shows under the ticket's status in its dialog and opens like a deliverable. `--source ""` clears it. Tickets without one are fine.
 - A working ticket is stuck once it goes longer than its estimate without an update, timed from its last status, stage or note change, or activity tagged to it. The ticket's dialog still shows total time worked against the estimate.
 - `question ask` needs `--recommend`, the agent's pick. The question dialog tags that option "Recommended".
-- Deliverable paths are stored relative to the worktree root. Web links open in Paseo's browser. Pressing an image (PNG, JPEG, GIF, WebP, up to 10 MB) or text deliverable (Markdown, text, logs, JSON, YAML, CSV; the first 256 KB) previews it in a dialog inside Paseo, which also works from a phone; **Open** there opens the file in its default app. A video (MP4, MOV, WebM, up to 200 MB) plays in the same dialog in the desktop app. When there are several files, **Previous** and **Next** step through them, and so do the left and right arrow keys. Pressing any other local deliverable opens it with its default app on the machine running the Paseo daemon (for example HTML in your browser and folders in the file manager). On macOS, **Open** sends text files to your default browser. Only recorded deliverables inside the worktree open this way; otherwise the path is copied. The copy icon on each row copies the path.
+- Deliverable paths are stored relative to the worktree root. Web links open in Paseo's browser. Pressing an image (PNG, JPEG, GIF, WebP, up to 10 MB) or text deliverable (Markdown, text, logs, JSON, YAML, CSV; the first 256 KB) previews it in a dialog inside Paseo, which also works from a phone; **Open** there opens the file in its default app. **Open** shows only when the computer running Paseo can open files. A Linux server with no desktop can't, so there a file Paseo can't preview copies its path and says why. A video (MP4, MOV, WebM, up to 200 MB) plays in the same dialog in the desktop app. When there are several files, **Previous** and **Next** step through them, and so do the left and right arrow keys. Pressing a folder lists its files in the same dialog. Press a file to preview it, or a folder inside to list that one, and **Back** returns to the list. Pressing any other local deliverable opens it with its default app on the machine running the Paseo daemon (for example HTML in your browser). On macOS, **Open** sends text files to your default browser. Only recorded deliverables inside the worktree open this way; otherwise the path is copied. The copy icon on each row copies the path.
 - Several agents can share one run. When another session adds a ticket, each agent sees it at the end of its next command's output (and in `show`), and the skill has it work that ticket in order after its current one. An agent only hears about tickets added since its own last update in the run, and only once.
 - Subagents record their own progress. Since Paseo 0.11, an agent waiting on background subagents shows as idle, so only the subagents' updates show the work is still going. The skill has the agent give each subagent the worktree path and ticket id, and the subagent records its stages and a ticker line on that worktree's dashboard.
 - `start` begins a fresh dashboard. Earlier runs stay in the file. Question references stay unique across runs.
@@ -120,11 +120,19 @@ The progress file, `progress.jsonl`, holds one JSON event per line, each with a
 - Progress folders outside the repo stay behind when a worktree is deleted. They're small, and you can delete them from `~/.local/state/paseo-progress/`.
 - Paseo can't open a panel without switching you to its workspace. So a new run shows a "Progress" pill, and you open the panel yourself.
 - Pills check busy worktrees every 5 seconds and quiet ones every 30. In a quiet worktree, a new question can take up to half a minute to show.
-- Previews cover images up to 10 MB, videos up to 200 MB (desktop app only), and the first 256 KB of a text file. Other files open in their default app. A video the app can't decode shows the player's error, and **Open** still works.
+- Previews cover images up to 10 MB, videos up to 200 MB (desktop app only), the first 256 KB of a text file, and the first 500 items in a folder. The folder list leaves out hidden files. Other files open in their default app. A video the app can't decode shows the player's error, and **Open** still works.
 - Stale warnings and overdue times use the daemon host's clock.
 
 ## Changelog
 
+### 1.2.0
+
+- A folder deliverable opens in Paseo as a list of its files. Press a file to preview it, or a folder inside to list that one; **Back** returns to the list. This works from a phone and when the worktree is on another computer. Before, Progress asked the computer running Paseo to open the folder. On a Linux server with no desktop, that failed with `spawn xdg-open ENOENT`.
+- A folder attached to a question lists its files the same way.
+- Every **Back** button says just **Back**. Before, it named where it went, like **Back to Q3**.
+- The preview hides **Open** when the computer running Paseo can't open files, like a Linux server you reach over ssh. There, a file Paseo can't preview copies its path and says why: `Can't open files on my-server. Copied path`.
+- Error messages in the panel no longer end in Paseo's `requestType=… code=…` text.
+
 ### 1.1.0
 
 - Videos play in the preview. MP4, MOV and WebM files up to 200 MB play in Paseo's desktop app, with a loading percentage while they arrive. On a phone, a video opens on the computer running the Paseo daemon, as before.

package/client/attachments.tsx

@@ -3,6 +3,7 @@ import { copyText, Icon, useToast } from "@getpaseo/plugin/client/react-native";
 import React from "react";
 import { Platform, Text, View } from "react-native";
 import { type Attachment, attachmentIcon, canPreview, shortName } from "../shared/attachments";
+import { errorText } from "./errors";
 import { PressableRow } from "./row";
 import { openDeliverable } from "../shared/rpc";
 
@@ -24,10 +25,6 @@ export function absolutePath(path: string, root: string): string {
   return path === "./" ? `${base}/` : `${base}/${path}`;
 }
 
-// Opens attachments the same way everywhere. Web links go to Paseo's browser
-// (the system browser where there is none); images, videos and text go to `onPreview` when the
-// caller can show the preview dialog; every other local file opens with its
-// default app on the daemon host.
 export function useAttachmentOpener({ workspaceId, workspaceDirectory, navigation, onPreview }: {
   workspaceId: string;
   workspaceDirectory: string;
@@ -49,7 +46,7 @@ export function useAttachmentOpener({ workspaceId, workspaceDirectory, navigatio
       await openOnHostRpc({ workspaceId, workspaceDirectory, ref: attachment.ref });
       toast.show(`Opened ${attachment.title}`, { variant: "success" });
     } catch (error) {
-      await copyPath(attachment, `${error instanceof Error ? error.message : "Could not open it"}. `);
+      await copyPath(attachment, `${errorText(error, "Could not open it")}. `);
     }
   }
   async function open(attachment: Attachment) {
@@ -71,21 +68,23 @@ export function useAttachmentOpener({ workspaceId, workspaceDirectory, navigatio
   return { open, openOnHost, copyPath };
 }
 
+export const ATTACHMENT_ROW = { gap: 2, paddingVertical: 3, lineHeight: 17 };
+
 // A question's attachments as pressable rows.
 // Drawn in dialogs and the popover (surface1) unless `onSurface1` is false.
 // `onOpen` also gets the whole list, so a preview can step through its siblings.
 export function AttachmentList({ colors, attachments, onOpen, onSurface1 = true }: { colors: Colors; attachments: Attachment[]; onOpen(attachment: Attachment, group: Attachment[]): void; onSurface1?: boolean }) {
   if (!attachments.length) return null;
   return (
-    <View style={{ gap: 2 }}>
+    <View style={{ gap: ATTACHMENT_ROW.gap }}>
       {attachments.map((attachment) => (
         <PressableRow key={attachment.ref} colors={colors} onSurface1={onSurface1} accessibilityRole={attachment.url ? "link" : "button"} accessibilityLabel={`Open ${attachment.title}`}
           onPress={() => onOpen(attachment, attachments)}
-          style={{ flexDirection: "row", gap: 6, alignItems: "center", paddingVertical: 3, paddingHorizontal: 4, marginHorizontal: -4, borderRadius: 4 }}>
+          style={{ flexDirection: "row", gap: 6, alignItems: "center", paddingVertical: ATTACHMENT_ROW.paddingVertical, paddingHorizontal: 4, marginHorizontal: -4, borderRadius: 4 }}>
           {/* A 14px slot, like a section icon, so the title lines up with the heading above. */}
           <View style={{ width: 14, alignItems: "center" }}><Icon name={attachmentIcon(attachment)} size={12} color={colors.foregroundMuted} /></View>
           {/* The row is the target, so nothing in it is styled as a link. */}
-          <Text numberOfLines={1} style={{ flexShrink: 1, color: colors.foreground, fontSize: 12, lineHeight: 17 }}>{attachment.title}</Text>
+          <Text numberOfLines={1} style={{ flexShrink: 1, color: colors.foreground, fontSize: 12, lineHeight: ATTACHMENT_ROW.lineHeight }}>{attachment.title}</Text>
           {shortName(attachment) !== attachment.title ? (
             <Text numberOfLines={1} style={{ flex: 1, minWidth: 0, color: colors.foregroundMuted, fontSize: 11, lineHeight: 16 }}>{shortName(attachment)}</Text>
           ) : <View style={{ flex: 1 }} />}

package/client/deliverables.tsx

@@ -6,7 +6,8 @@ import type { Deliverable } from "../shared/dashboard";
 import { type Attachment, attachmentIcon, deliverableAttachment, shortName, useAttachmentOpener } from "./attachments";
 import { formatAgo } from "../shared/format";
 import { PressScale } from "./motion";
-import { PreviewDialog, previewable } from "./preview";
+import { StackedDialog } from "./dialog-stack";
+import { galleryFiles } from "./preview";
 import { PressableRow } from "./row";
 import { ShowMoreRow, usePaged } from "./show-more";
 
@@ -25,8 +26,7 @@ export function DeliverablesList({ colors, deliverables, now, workspaceId, works
   navigation: Navigation;
 }) {
   const [previewing, setPreviewing] = useState<Attachment | null>(null);
-  // Screenshots preview inside Paseo; links open in its browser; the rest open in their own app.
-  const { open, openOnHost, copyPath } = useAttachmentOpener({ workspaceId, workspaceDirectory, navigation, onPreview: setPreviewing });
+  const { open, copyPath } = useAttachmentOpener({ workspaceId, workspaceDirectory, navigation, onPreview: setPreviewing });
   const paged = usePaged(deliverables);
   return (
     <View>
@@ -59,9 +59,8 @@ export function DeliverablesList({ colors, deliverables, now, workspaceId, works
         </PressableRow>
       ))}
       <ShowMoreRow colors={colors} total={deliverables.length} paged={paged} />
-      <PreviewDialog colors={colors} attachment={previewing} workspaceId={workspaceId} workspaceDirectory={workspaceDirectory}
-        onClose={() => setPreviewing(null)} onOpenOnHost={(attachment) => void openOnHost(attachment)}
-        gallery={{ items: previewable(deliverables.map(deliverableAttachment)), onSelect: setPreviewing }} />
+      <StackedDialog colors={colors} now={now} onClose={() => setPreviewing(null)} context={{ workspaceId, workspaceDirectory, navigation }}
+        root={previewing ? { kind: "preview", attachment: previewing, group: galleryFiles(deliverables.map(deliverableAttachment)) } : null} />
     </View>
   );
 }

package/client/dialog-stack.tsx

@@ -3,9 +3,8 @@ import { Icon, Modal } from "@getpaseo/plugin/client/react-native";
 import React, { useEffect, useRef, useState } from "react";
 import type { Dashboard, Question } from "../shared/dashboard";
 import { type Attachment, attachmentIcon, useAttachmentOpener } from "./attachments";
-import { useLastPresent } from "./motion";
 import { NarrowProvider } from "./narrow";
-import { BackButton, PreviewContent, previewable } from "./preview";
+import { BackButton, galleryFiles, PreviewContent } from "./preview";
 import { QuestionView, useCopy } from "./questions";
 import { TicketStoryView } from "./ticket-dialog";
 
@@ -18,35 +17,32 @@ export type Step =
   | { kind: "question"; id: string }
   | { kind: "preview"; attachment: Attachment; group: Attachment[] };
 
-// One dialog for a ticket or a question and everything opened from it. Paseo
-// gives each dialog its own backdrop, so opening a second one darkens the screen
-// while the first fades out; instead the content changes in place, and Back
-// returns to the step before.
-export function StackedDialog({ colors, root, onClose, questions, dashboard, now, live = true, context }: {
+// Paseo gives each dialog its own backdrop, so opening a second one darkens
+// the screen while the first fades out; steps swap content inside this one instead.
+export function StackedDialog({ colors, root, onClose, questions = [], dashboard, now, live = true, context }: {
   colors: Colors;
-  // The ticket or question it opens on; null closes it.
   root: Step | null;
   onClose(): void;
-  questions: Question[];
+  questions?: Question[];
   // Needed only when it opens on a ticket.
   dashboard?: Dashboard;
   now: number;
   live?: boolean;
   context: AttachmentContext;
 }) {
-  // What was opened on top of the root, oldest first. Cleared when a new root opens.
-  const [trail, setTrail] = useState<Step[]>([]);
-  const rootKey = root && root.kind !== "preview" ? `${root.kind}:${root.id}` : null;
-  const [trailFor, setTrailFor] = useState(rootKey);
-  if (trailFor !== rootKey) {
-    setTrailFor(rootKey);
-    if (rootKey) setTrail([]);
+  // Paseo's Modal keeps drawing its content while it fades out, so closing keeps the steps.
+  const [steps, setSteps] = useState<Step[]>(root ? [root] : []);
+  const rootKey = root ? stepKey(root) : null;
+  const [stepsFor, setStepsFor] = useState(rootKey);
+  if (stepsFor !== rootKey) {
+    setStepsFor(rootKey);
+    if (root) setSteps([root]);
   }
   // The list an attachment was opened from, so its preview can step through the rest.
   const group = useRef<Attachment[]>([]);
-  const push = (step: Step) => setTrail((current) => [...current, step]);
-  const replaceTop = (step: Step) => setTrail((current) => [...current.slice(0, -1), step]);
-  const opener = useAttachmentOpener({ ...context, onPreview: (attachment) => push({ kind: "preview", attachment, group: previewable(group.current) }) });
+  const push = (step: Step) => setSteps((current) => [...current, step]);
+  const replaceTop = (step: Step) => setSteps((current) => [...current.slice(0, -1), step]);
+  const opener = useAttachmentOpener({ ...context, onPreview: (attachment) => push({ kind: "preview", attachment, group: galleryFiles(group.current) }) });
   const openAttachment = (attachment: Attachment, from: Attachment[]) => {
     group.current = from;
     // A link opens elsewhere in Paseo; close first so it isn't left behind the dialog.
@@ -59,12 +55,9 @@ export function StackedDialog({ colors, root, onClose, questions, dashboard, now
     context.navigation!.openAgent({ agentId });
   } : undefined;
   const copy = useCopy();
-  const steps: Step[] = root ? [root, ...trail] : [];
-  // Keep drawing the last step while the dialog fades out.
-  const shown = useLastPresent(steps.length ? { top: steps[steps.length - 1], previous: steps[steps.length - 2] } : null);
-  const back = shown?.previous ? { label: `Back to ${stepName(shown.previous)}`, onPress: () => setTrail((current) => current.slice(0, -1)) } : null;
+  const top = steps.at(-1);
+  const back = steps.length > 1 ? () => setSteps((current) => current.slice(0, -1)) : undefined;
 
-  const top = shown?.top;
   const ticket = top?.kind === "ticket" ? dashboard?.tickets.find((candidate) => candidate.id === top.id) : undefined;
   const question = top?.kind === "question" ? questions.find((candidate) => candidate.id === top.id) : undefined;
   const preview = top?.kind === "preview" ? top : undefined;
@@ -87,8 +80,9 @@ export function StackedDialog({ colors, root, onClose, questions, dashboard, now
       <NarrowProvider value={false}>
       {preview ? (
         <PreviewContent colors={colors} attachment={preview.attachment} workspaceId={context.workspaceId} workspaceDirectory={context.workspaceDirectory}
-          onOpenOnHost={() => { onClose(); void opener.openOnHost(preview.attachment); }} backLabel={back?.label} onBack={back?.onPress}
-          gallery={{ items: preview.group, onSelect: (attachment) => replaceTop({ ...preview, attachment }) }} onLong={setPreviewLong} />
+          onOpenOnHost={() => { onClose(); void opener.openOnHost(preview.attachment); }} onBack={back}
+          gallery={{ items: preview.group, onSelect: (attachment) => replaceTop({ ...preview, attachment }) }} onLong={setPreviewLong}
+          onOpenEntry={openAttachment} />
       ) : (
         <>
           {ticket && dashboard ? (
@@ -99,7 +93,7 @@ export function StackedDialog({ colors, root, onClose, questions, dashboard, now
             <QuestionView colors={colors} question={question} now={now}
               onCopy={(letter) => { void copy(question, letter); onClose(); }}
               onOpenAttachment={openAttachment}>
-              {back ? <BackButton colors={colors} label={back.label} onPress={back.onPress} /> : null}
+              {back ? <BackButton colors={colors} onPress={back} /> : null}
             </QuestionView>
           ) : null}
         </>
@@ -110,6 +104,7 @@ export function StackedDialog({ colors, root, onClose, questions, dashboard, now
   );
 }
 
-function stepName(step: Step): string {
-  return step.kind === "preview" ? step.attachment.title : step.id;
+function stepKey(step: Step): string {
+  return step.kind === "preview" ? `preview:${step.attachment.ref}` : `${step.kind}:${step.id}`;
 }
+

package/client/errors.ts

@@ -0,0 +1,6 @@
+// Paseo wraps a handler's error as "Request failed: <message> requestType=… code=…".
+export function errorText(error: unknown, fallback: string): string {
+  const message = (error as { message?: unknown } | null)?.message;
+  if (typeof message !== "string") return fallback;
+  return message.replace(/^Request failed: /, "").replace(/ requestType=\S+(?: code=\S+)?$/, "").trim() || fallback;
+}

package/client/history.tsx

@@ -6,6 +6,7 @@ import { ActivityIndicator, ScrollView, Text, TextInput, View } from "react-nati
 import { PressScale } from "./motion";
 import { PressableRow } from "./row";
 import { listFolders, setHistoryFolder } from "../shared/rpc";
+import { errorText } from "./errors";
 
 type Colors = PluginWorkspacePanelProps["theme"]["colors"];
 
@@ -27,7 +28,7 @@ export function HistoryRow({ colors, workspaceId, directory, savedTo }: {
       queryClient.invalidateQueries({ queryKey: ["progress", "dashboard"] });
       toast.show(next ? `Each run will be saved to ${next}.` : "Runs will stay on this computer. Files already saved stay in the repo.", { variant: "success" });
     },
-    onError: (error) => toast.error(error instanceof Error ? error.message : "Could not change where runs are saved."),
+    onError: (error) => toast.error(errorText(error, "Could not change where runs are saved.")),
   });
   // While saving, the button that started it says so.
   const busy = mutation.isPending ? (mutation.variables === null ? "stop" : "pick") : null;
@@ -119,7 +120,7 @@ function FolderPicker({ colors, workspaceId, directory, open, start, onClose, on
           {listed.data && !listed.data.folders.length ? (
             <Text style={{ color: colors.foregroundMuted, fontSize: 12, lineHeight: 16, paddingHorizontal: 8, paddingVertical: 6 }}>No folders in here.</Text>
           ) : null}
-          {listed.error ? <Text accessibilityRole="alert" style={{ color: colors.statusDanger, fontSize: 12, lineHeight: 17, paddingHorizontal: 8 }}>{listed.error.message}</Text> : null}
+          {listed.error ? <Text accessibilityRole="alert" style={{ color: colors.statusDanger, fontSize: 12, lineHeight: 17, paddingHorizontal: 8 }}>{errorText(listed.error, "Could not list the folders.")}</Text> : null}
         </ScrollView>
 
         {naming === null ? (

package/client/launcher.tsx

@@ -6,6 +6,7 @@ import { Text, View } from "react-native";
 import { PressScale, Presence } from "./motion";
 import { raised } from "./surfaces";
 import { getLauncherStatus, getSkillStatus, installLauncher, installSkill, type LauncherStatus, type SkillStatus } from "../shared/rpc";
+import { errorText } from "./errors";
 
 type Colors = PluginWorkspacePanelProps["theme"]["colors"];
 
@@ -60,7 +61,7 @@ export function LauncherBanner({ colors, host }: { colors: Colors; host: PluginW
       queryClient.setQueryData(launcherQueryKey(host.id), next);
       toast.show(`Installed paseo-progress at ${next.path}`, { variant: "success" });
     },
-    onError: (error) => toast.error(error instanceof Error ? error.message : "Could not install the command."),
+    onError: (error) => toast.error(errorText(error, "Could not install the command.")),
   });
   const notice = status.data ? launcherNotice(status.data) : null;
   return <SetupBanner colors={colors} icon="Terminal" notice={notice} pending={mutation.isPending} onPress={() => mutation.mutate()} />;
@@ -78,7 +79,7 @@ export function SkillBanner({ colors, host }: { colors: Colors; host: PluginWork
       queryClient.setQueryData(skillQueryKey(host.id), next);
       toast.show("Installed the paseo-progress skill. New agent sessions will use it.", { variant: "success" });
     },
-    onError: (error) => toast.error(error instanceof Error ? error.message : "Could not install the skill."),
+    onError: (error) => toast.error(errorText(error, "Could not install the skill.")),
   });
   const notice = status.data ? skillNotice(status.data) : null;
   return <SetupBanner colors={colors} icon="Sparkles" notice={notice} pending={mutation.isPending} onPress={() => mutation.mutate()} />;

package/client/motion.tsx

@@ -24,14 +24,6 @@ export function useReducedMotion(): boolean {
   return reduced;
 }
 
-// The last non-null value, so a dialog keeps its content while it animates
-// closed instead of collapsing mid-exit.
-export function useLastPresent<T>(value: T | null): T | null {
-  const last = useRef(value);
-  if (value !== null) last.current = value;
-  return value ?? last.current;
-}
-
 // A button that scales to 0.96 while pressed. `static` turns the scale off.
 export function PressScale({ static: isStatic, style, outerStyle, children, ...props }: Omit<PressableProps, "style" | "children"> & {
   static?: boolean;

package/client/panel.tsx

@@ -23,6 +23,7 @@ import { TabStrip } from "./tabs";
 import { ShowMoreRow, usePaged } from "./show-more";
 import { notePanelOpened } from "./panel-opened";
 import { NARROW_MAX, NarrowProvider, useNarrow } from "./narrow";
+import { errorText } from "./errors";
 
 type Colors = PluginWorkspacePanelProps["theme"]["colors"];
 
@@ -52,7 +53,7 @@ function WorkspaceProgress({ theme, workspaceId, host, layout, navigation }: Plu
       {query.isPending ? <ActivityIndicator color={colors.foregroundMuted} accessibilityLabel="Loading progress" style={{ padding: 12 }} /> : null}
       {query.error ? (
         <Text accessibilityRole="alert" selectable style={{ color: colors.statusDanger, fontSize: 12, lineHeight: 18, padding: 12 }}>
-          Could not read progress: {query.error.message}
+          Could not read progress: {errorText(query.error, "something went wrong")}
         </Text>
       ) : null}
       <LauncherBanner colors={colors} host={host} />

package/client/pill-popover.tsx

@@ -7,8 +7,10 @@ import { useDashboard } from "./dashboard-query";
 import { progressPanel } from "./pills";
 import { PressScale } from "./motion";
 import { type Attachment, isPreviewable, useAttachmentOpener } from "./attachments";
-import { PreviewDialog, previewable } from "./preview";
+import { StackedDialog } from "./dialog-stack";
+import { galleryFiles } from "./preview";
 import { QuestionDetail, QuestionState, useCopy } from "./questions";
+import { errorText } from "./errors";
 import { raised } from "./surfaces";
 
 type Colors = PluginButtonContentProps["theme"]["colors"];
@@ -35,7 +37,7 @@ export function AttentionPopover({ theme, host, layout, workspaceId, close, open
   // Links and other files leave Paseo, so the popover closes for those.
   const [previewing, setPreviewing] = useState<{ attachment: Attachment; group: Attachment[] } | null>(null);
   const group = useRef<Attachment[]>([]);
-  const opener = useAttachmentOpener({ workspaceId, workspaceDirectory: root, onPreview: (attachment) => setPreviewing({ attachment, group: previewable(group.current) }) });
+  const opener = useAttachmentOpener({ workspaceId, workspaceDirectory: root, onPreview: (attachment) => setPreviewing({ attachment, group: galleryFiles(group.current) }) });
   return (
     <View style={{ width: 360, maxWidth: "100%", gap: 8 }}>
       {dashboard ? (
@@ -51,12 +53,11 @@ export function AttentionPopover({ theme, host, layout, workspaceId, close, open
         </List>
       ) : (
         <Text style={{ color: colors.foregroundMuted, fontSize: 12, lineHeight: 18 }}>
-          {query.error ? `Could not read progress: ${query.error.message}` : "Loading…"}
+          {query.error ? `Could not read progress: ${errorText(query.error, "something went wrong")}` : "Loading…"}
         </Text>
       )}
-      <PreviewDialog colors={colors} attachment={previewing?.attachment ?? null} workspaceId={workspaceId} workspaceDirectory={root}
-        onClose={() => setPreviewing(null)} onOpenOnHost={(attachment) => void opener.openOnHost(attachment)}
-        gallery={previewing ? { items: previewing.group, onSelect: (attachment) => setPreviewing({ ...previewing, attachment }) } : undefined} />
+      <StackedDialog colors={colors} now={Date.now()} onClose={() => setPreviewing(null)} context={{ workspaceId, workspaceDirectory: root }}
+        root={previewing ? { kind: "preview", ...previewing } : null} />
       <View style={{ paddingTop: touch ? 12 : 8, borderTopWidth: 1, borderTopColor: colors.border }}>
         {/* A full 44pt touch target on phones; desktop keeps the compact button. */}
         <PressScale accessibilityRole="button" onPress={() => { close(); openPanel(); }}

package/client/preview.tsx

@@ -1,43 +1,18 @@
 import { type PluginWorkspacePanelProps, useRpc } from "@getpaseo/plugin/client";
-import { Icon, Modal, ScrollView } from "@getpaseo/plugin/client/react-native";
+import { Icon, ScrollView } from "@getpaseo/plugin/client/react-native";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
-import React, { useEffect, useRef, useState } from "react";
+import React, { useEffect, useRef } from "react";
 import { ActivityIndicator, Image, Platform, Text, useWindowDimensions, View, type ViewStyle } from "react-native";
-import { type Attachment, attachmentIcon, isPreviewable } from "./attachments";
-import { previewKind } from "../shared/attachments";
-import { previewDeliverable, readDeliverablePiece } from "../shared/rpc";
-import { PressScale, useLastPresent } from "./motion";
+import { ATTACHMENT_ROW, type Attachment, AttachmentList, isPreviewable } from "./attachments";
+import { errorText } from "./errors";
+import { folderAttachments, isFolder, previewKind } from "../shared/attachments";
+import { canOpenOnHost, previewDeliverable, readDeliverablePiece } from "../shared/rpc";
+import { PressScale } from "./motion";
 import { imageOutline, raised } from "./surfaces";
 import { loadVideo, VideoPlayer } from "./video";
 
 type Colors = PluginWorkspacePanelProps["theme"]["colors"];
 
-// An image or text attachment shown in a dialog, with a way out to the host's own app.
-// `onBack` returns to where the preview was opened from, e.g. a question's dialog.
-export function PreviewDialog({ colors, attachment, workspaceId, workspaceDirectory, onClose, onOpenOnHost, backLabel, onBack, gallery }: {
-  colors: Colors;
-  attachment: Attachment | null;
-  workspaceId: string;
-  workspaceDirectory: string;
-  onClose(): void;
-  onOpenOnHost(attachment: Attachment): void;
-  backLabel?: string;
-  onBack?(): void;
-  gallery?: Gallery;
-}) {
-  const open = Boolean(attachment);
-  attachment = useLastPresent(attachment);
-  return (
-    <Modal title={attachment?.title ?? "Preview"} icon={<Icon name={attachment ? attachmentIcon(attachment) : "FileText"} size={16} color={colors.foregroundMuted} />}
-      open={open} onOpenChange={(next) => { if (!next) onClose(); }}>
-      {attachment ? (
-        <PreviewBody colors={colors} attachment={attachment} workspaceId={workspaceId} workspaceDirectory={workspaceDirectory}
-          onOpenOnHost={() => { onClose(); onOpenOnHost(attachment); }} backLabel={backLabel} onBack={onBack} gallery={gallery} />
-      ) : <Modal.Content>{null}</Modal.Content>}
-    </Modal>
-  );
-}
-
 // The other previewable files beside this one (a question's images, a ticket's
 // screenshots), for Previous and Next. Only shown when there's more than one.
 export interface Gallery {
@@ -45,9 +20,8 @@ export interface Gallery {
   onSelect(attachment: Attachment): void;
 }
 
-// Keeps only what the preview can show, for a Gallery's items.
-export function previewable(group: Attachment[]): Attachment[] {
-  return group.filter(isPreviewable);
+export function galleryFiles(group: Attachment[]): Attachment[] {
+  return group.filter((attachment) => isPreviewable(attachment) && !isFolder(attachment));
 }
 
 type PreviewProps = {
@@ -56,25 +30,23 @@ type PreviewProps = {
   workspaceId: string;
   workspaceDirectory: string;
   onOpenOnHost(): void;
-  backLabel?: string;
   onBack?(): void;
   gallery?: Gallery;
+  onOpenEntry(attachment: Attachment, group: Attachment[]): void;
 };
 
-// The preview dialog's body in its own Modal.Content.
-export function PreviewBody(props: PreviewProps) {
-  const [long, setLong] = useState(false);
-  return <Modal.Content scrollable={!long}><PreviewContent {...props} onLong={setLong} /></Modal.Content>;
-}
-
-// The preview without its Modal.Content, for a dialog that already has one (see
-// StackedDialog): swapping Modal.Content itself would re-present the sheet on phones.
 // `onLong` says when the file is too tall for the dialog, so the host turns off
 // its own scrolling and the file scrolls with the actions pinned below.
-export function PreviewContent({ colors, attachment, workspaceId, workspaceDirectory, onOpenOnHost, backLabel, onBack, gallery, onLong }: PreviewProps & { onLong(long: boolean): void }) {
+export function PreviewContent({ colors, attachment, workspaceId, workspaceDirectory, onOpenOnHost, onBack, gallery, onOpenEntry, onLong }: PreviewProps & { onLong(long: boolean): void }) {
   const fetchPreview = useRpc(previewDeliverable);
   const readPiece = useRpc(readDeliverablePiece);
+  const checkHost = useRpc(canOpenOnHost);
   const queryClient = useQueryClient();
+  const canOpen = useQuery({
+    queryKey: ["progress", "can-open", workspaceId],
+    queryFn: () => checkHost({ workspaceId, workspaceDirectory }),
+    staleTime: Infinity,
+  }).data?.canOpen === true;
   // How much of a video has arrived, for the line under the spinner.
   const loadingKey = (target: Attachment) => ["progress", "preview-loading", workspaceId, target.ref, target.path];
   const previewQuery = (target: Attachment) => ({
@@ -121,8 +93,10 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
     if (previewKind(next.path ?? "") !== "video") void queryClient.prefetchQuery(previewQuery(next));
   }, [attachment.ref, items.length]);
   // Previous and Next, wrapping at the ends. Left and right arrows do the same.
-  const step = (offset: number) => gallery?.onSelect(items[(Math.max(0, index) + offset + items.length) % items.length]);
-  useArrowKeys(items.length > 1 ? step : null);
+  const step = (offset: number) => gallery?.onSelect(items[(index + offset + items.length) % items.length]);
+  const inGallery = index >= 0;
+  const canStep = inGallery && items.length > 1;
+  useArrowKeys(canStep ? step : null);
   // Next has focus when the preview opens, so Enter or Space moves on too.
   const nextButton = useRef<View>(null);
   useEffect(() => {
@@ -155,7 +129,7 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
       ) : null}
       {preview.error ? (
         <Text accessibilityRole="alert" selectable style={{ color: colors.statusDanger, fontSize: 12, lineHeight: 18 }}>
-          Could not preview it: {preview.error.message}
+          Could not preview it: {errorText(preview.error, "something went wrong")}
         </Text>
       ) : null}
       {preview.data?.kind === "text" ? (
@@ -165,11 +139,15 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
           </Text>
           {preview.data.truncated ? (
             <Text style={{ color: colors.foregroundMuted, fontSize: 11, lineHeight: 16, paddingTop: 8 }}>
-              Showing the first 256 KB. Press Open to see the rest in its default app.
+              Showing the first 256 KB.{canOpen ? " Press Open to see the rest in its default app." : ""}
             </Text>
           ) : null}
         </View>
       ) : null}
+      {preview.data?.kind === "folder" ? (
+        <FolderList colors={colors} folder={attachment} entries={folderAttachments(attachment, preview.data.entries)} truncated={preview.data.truncated}
+          dimmed={stepping} onOpen={onOpenEntry} />
+      ) : null}
       {preview.data?.kind === "image" ? (
         <Image accessibilityLabel={attachment.title} source={{ uri: preview.data.dataUri }} resizeMode="contain" style={mediaStyle} />
       ) : null}
@@ -188,11 +166,11 @@ export function PreviewContent({ colors, attachment, workspaceId, workspaceDirec
   const actions = (
     <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
       <View style={{ flex: 1, alignItems: "flex-start" }}>
-        {onBack ? <BackButton colors={colors} label={backLabel ?? "Back"} onPress={onBack} /> : null}
+        {onBack ? <BackButton colors={colors} onPress={onBack} /> : null}
       </View>
-      {items.length > 1 ? <Stepper colors={colors} index={Math.max(0, index)} count={items.length} onStep={step} nextRef={nextButton} /> : null}
+      {canStep ? <Stepper colors={colors} index={index} count={items.length} onStep={step} nextRef={nextButton} /> : null}
       <View style={{ flex: 1, alignItems: "flex-end" }}>
-        <DialogButton colors={colors} icon="ExternalLink" label="Open" accessibilityLabel="Open in its default app" onPress={onOpenOnHost} />
+        {canOpen ? <DialogButton colors={colors} icon="ExternalLink" label="Open" accessibilityLabel="Open in its default app" onPress={onOpenOnHost} /> : null}
       </View>
     </View>
   );
@@ -214,14 +192,28 @@ const CONTENT_WIDTH = 472;
 // Characters of 12px monospace per line of the text box (10px padding each side).
 const CHARS_PER_LINE = Math.floor((CONTENT_WIDTH - 20) / 7.2);
 
+const FOLDER_ROW_HEIGHT = ATTACHMENT_ROW.lineHeight + ATTACHMENT_ROW.paddingVertical * 2 + ATTACHMENT_ROW.gap;
+
 // Roughly how tall the preview draws, including wrapped lines.
-function estimatedHeight(data: { kind: "image" | "video" } | { kind: "text"; text: string } | undefined, aspectRatio: number, maxMediaHeight: number): number {
+function estimatedHeight(data: { kind: "image" | "video" } | { kind: "text"; text: string } | { kind: "folder"; entries: unknown[]; truncated: boolean } | undefined, aspectRatio: number, maxMediaHeight: number): number {
   if (!data) return 0;
+  if (data.kind === "folder") return Math.max(1, data.entries.length + (data.truncated ? 1 : 0)) * FOLDER_ROW_HEIGHT;
   if (data.kind !== "text") return Math.min(CONTENT_WIDTH / aspectRatio, maxMediaHeight);
   const lines = data.text.split("\n").reduce((sum, line) => sum + Math.max(1, Math.ceil(line.length / CHARS_PER_LINE)), 0);
   return lines * 18 + 20;
 }
 
+function FolderList({ colors, folder, entries, truncated, dimmed, onOpen }: { colors: Colors; folder: Attachment; entries: Attachment[]; truncated: boolean; dimmed: boolean; onOpen(attachment: Attachment, group: Attachment[]): void }) {
+  const caption = { color: colors.foregroundMuted, fontSize: 12, lineHeight: 17 } as const;
+  if (!entries.length) return <Text style={caption}>Nothing in {folder.title} yet.</Text>;
+  return (
+    <View style={{ gap: 8, opacity: dimmed ? 0.6 : 1 }}>
+      <AttachmentList colors={colors} attachments={entries} onOpen={onOpen} />
+      {truncated ? <Text style={caption}>Showing the first {entries.length}.</Text> : null}
+    </View>
+  );
+}
+
 // An image's width over its height, or null if it can't be read. Read from the data
 // because onLoad doesn't report a size for data URIs on every platform.
 function imageRatio(uri: string): Promise<number | null> {
@@ -253,8 +245,8 @@ export function DialogButton({ colors, icon, label, accessibilityLabel, onPress,
 }
 
 // Returns to the dialog this one was opened from. For surface1 dialogs.
-export function BackButton({ colors, label, onPress }: { colors: Colors; label: string; onPress(): void }) {
-  return <DialogButton colors={colors} icon="ChevronLeft" label={label} onPress={onPress} outerStyle={{ alignSelf: "flex-start" }} />;
+export function BackButton({ colors, onPress }: { colors: Colors; onPress(): void }) {
+  return <DialogButton colors={colors} icon="ChevronLeft" label="Back" onPress={onPress} outerStyle={{ alignSelf: "flex-start" }} />;
 }
 
 // Previous and next through a gallery, with "2 of 3" between.

package/client/write-up.tsx

@@ -8,6 +8,7 @@ import { previewDeliverable } from "../shared/rpc";
 import { type Block, parseWriteUp, type Span, withoutTitle, writeUpExcerpt } from "../shared/write-up";
 import { type Attachment, attachmentIcon } from "./attachments";
 import { PressableRow } from "./row";
+import { errorText } from "./errors";
 
 type Colors = PluginWorkspacePanelProps["theme"]["colors"];
 const MONO = Platform.OS === "ios" ? "Menlo" : "monospace";
@@ -37,7 +38,7 @@ export function WriteUp({ colors, source, workspaceId, workspaceDirectory, onOpe
   return (
     <View style={{ gap: 12, padding: 14, borderRadius: 8, backgroundColor: colors.surface0 }}>
       {shown.length ? <View style={{ gap: 8 }}>{shown.map((block, index) => <BlockView key={index} colors={colors} block={block} first={index === 0} />)}</View> : null}
-      {preview.error ? <Text style={{ color: colors.foregroundMuted, fontSize: 12, lineHeight: 18 }}>Couldn't read it here: {preview.error.message}</Text> : null}
+      {preview.error ? <Text style={{ color: colors.foregroundMuted, fontSize: 12, lineHeight: 18 }}>Couldn't read it here: {errorText(preview.error, "something went wrong")}</Text> : null}
       {/* The file on the left, opening it whole; expanding in place on the right. */}
       <View style={{ flexDirection: "row", alignItems: "center", gap: 12 }}>
         <TextButton colors={colors} icon={attachmentIcon(source)} label={source.title} accessibilityLabel={`Open ${source.title}`} onPress={() => onOpen(source, [source])} grow />

package/dist/server/cli.js

@@ -20928,7 +20928,7 @@ var commands = {
 function rootRelative(target, cwd, root) {
   const absolute = resolve3(cwd, target);
   const inside = relative(root, absolute);
-  const suffix = /[\/]$/.test(target) ? "/" : "";
+  const suffix = /[\/]$/.test(target) || statSync(absolute, { throwIfNoEntry: false })?.isDirectory() ? "/" : "";
   if (!inside) return "./";
   return outside(inside) ? absolute + suffix : inside + suffix;
 }

package/index.server.ts

@@ -1,9 +1,9 @@
 import type { PluginServerContext } from "@getpaseo/plugin/server";
 import { handleGetAttention, handleGetDashboard, handleListFolders, handleMarkPanelOpened, handleSetHistoryFolder } from "./server/dashboard";
 import { handleInstallLauncher, handleLauncherStatus } from "./server/launcher";
-import { handleOpenDeliverable, handlePreviewDeliverable, handleReadDeliverablePiece } from "./server/open";
+import { handleCanOpenOnHost, handleOpenDeliverable, handlePreviewDeliverable, handleReadDeliverablePiece } from "./server/open";
 import { handleInstallSkill, handleSkillStatus } from "./server/skill";
-import { getAttention, getDashboard, getLauncherStatus, getSkillStatus, installLauncher, installSkill, listFolders, markPanelOpened, openDeliverable, previewDeliverable, readDeliverablePiece, setHistoryFolder } from "./shared/rpc";
+import { canOpenOnHost, getAttention, getDashboard, getLauncherStatus, getSkillStatus, installLauncher, installSkill, listFolders, markPanelOpened, openDeliverable, previewDeliverable, readDeliverablePiece, setHistoryFolder } from "./shared/rpc";
 
 export default function contribute(server: PluginServerContext) {
   server.handle(getDashboard, handleGetDashboard);
@@ -12,6 +12,7 @@ export default function contribute(server: PluginServerContext) {
   server.handle(getLauncherStatus, handleLauncherStatus);
   server.handle(installLauncher, handleInstallLauncher);
   server.handle(openDeliverable, handleOpenDeliverable);
+  server.handle(canOpenOnHost, handleCanOpenOnHost);
   server.handle(previewDeliverable, handlePreviewDeliverable);
   server.handle(readDeliverablePiece, handleReadDeliverablePiece);
   server.handle(getSkillStatus, handleSkillStatus);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stevecastaneda/paseo-progress",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A live progress dashboard per worktree for Paseo, drawn from a file agents write with the paseo-progress command.",
   "license": "MIT",
   "author": "Steve Castaneda",

package/server/cli.ts

@@ -447,7 +447,7 @@ const commands: Record<string, Command> = {
 function rootRelative(target: string, cwd: string, root: string): string {
   const absolute = resolve(cwd, target);
   const inside = relative(root, absolute);
-  const suffix = /[\/]$/.test(target) ? "/" : "";
+  const suffix = /[\/]$/.test(target) || statSync(absolute, { throwIfNoEntry: false })?.isDirectory() ? "/" : "";
   if (!inside) return "./";
   return outside(inside) ? absolute + suffix : inside + suffix;
 }

package/server/open.ts

@@ -1,10 +1,11 @@
 import type { PluginHandlerContext } from "@getpaseo/plugin/server";
 import { execFile } from "node:child_process";
-import { open, readFile, realpath, stat } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, relative, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { open, readdir, readFile, realpath, stat } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
+import { delimiter, join, relative, resolve } from "node:path";
 import { promisify } from "node:util";
-import { findAttachment, imageMimeType, previewKind, videoMimeType } from "../shared/attachments.ts";
+import { findAttachment, type FolderEntry, imageMimeType, previewKind, splitRef, videoMimeType } from "../shared/attachments.ts";
 import { readProgress } from "./progress-file.ts";
 import { findRoot, outside } from "./paths.ts";
 import { findStore } from "./store.ts";
@@ -34,20 +35,32 @@ async function defaultBrowser(): Promise<string | null> {
   }
 }
 
-export const systemOpener: Opener = async (path) => {
-  const browser = process.platform === "darwin" ? await defaultBrowser() : null;
-  const [command, args] = openCommand(path, process.platform, browser);
-  await promisify(execFile)(command, args);
-};
+export function canOpenFiles(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): boolean {
+  if (platform === "darwin" || platform === "win32") return true;
+  if (!env.DISPLAY && !env.WAYLAND_DISPLAY) return false;
+  return (env.PATH ?? "").split(delimiter).some((directory) => directory && existsSync(join(directory, "xdg-open")));
+}
+
+export function hostOpener(platform: NodeJS.Platform, env: NodeJS.ProcessEnv): Opener {
+  return async (path) => {
+    if (!canOpenFiles(platform, env)) throw new Error(`Can't open files on ${hostname()}`);
+    const browser = platform === "darwin" ? await defaultBrowser() : null;
+    const [command, args] = openCommand(path, platform, browser);
+    await promisify(execFile)(command, args);
+  };
+}
 
 // A deliverable or question attachment the agent recorded, found by reference,
 // so the panel can never reach an arbitrary path. Only files inside the
 // worktree resolve.
 async function resolveAttachment(directory: string, ref: string, verb: string): Promise<{ path: string; target: string }> {
+  const { base, inner } = splitRef(ref);
   const worktree = findRoot(directory);
   const { dashboard } = await readProgress((await findStore(worktree)).directory);
-  const path = findAttachment(dashboard, ref)?.path;
-  if (!path) throw new Error(`No local ${ref.startsWith("Q") ? "attachment" : "deliverable"} ${ref} in this worktree.`);
+  const folder = findAttachment(dashboard, base)?.path;
+  if (!folder) throw new Error(`No local ${base.startsWith("Q") ? "attachment" : "deliverable"} ${base} in this worktree.`);
+  const path = inner ? join(folder, inner) : folder;
+  if (outside(relative(resolve(worktree, folder), resolve(worktree, path)))) throw new Error(`${path} is outside ${folder}, so it was not ${verb}.`);
   const root = await realpath(worktree);
   const target = await realpath(resolve(root, path)).catch(() => null);
   if (!target) throw new Error(`${path} no longer exists.`);
@@ -74,18 +87,21 @@ export const MAX_PREVIEW_VIDEO_BYTES = 200 * 1024 * 1024;
 // Small enough that one piece doesn't hold up the agent output sharing the socket.
 export const VIDEO_PIECE_BYTES = 4 * 1024 * 1024;
 
+export const MAX_FOLDER_ENTRIES = 500;
+
 export type Preview =
   | { kind: "image"; dataUri: string; bytes: number }
   | { kind: "video"; mimeType: string; bytes: number }
-  | { kind: "text"; text: string; bytes: number; truncated: boolean };
+  | { kind: "text"; text: string; bytes: number; truncated: boolean }
+  | { kind: "folder"; entries: FolderEntry[]; truncated: boolean };
 
-// An image (as a data URI) or a text file's contents, so any client (desktop
-// or phone) can show it without reaching the daemon host's disk.
 export async function previewDeliverable(directory: string, id: string): Promise<Preview> {
   const { path, target } = await resolveAttachment(directory, id, "previewed");
+  const stats = await stat(target);
+  if (stats.isDirectory()) return { kind: "folder", ...(await listFolder(target)) };
   const kind = previewKind(target);
   if (!kind) throw new Error(`${path} isn't an image, video or text file, so it can't be previewed.`);
-  const { size } = await stat(target);
+  const { size } = stats;
   if (kind === "video") {
     if (size > MAX_PREVIEW_VIDEO_BYTES) throw new Error(tooLarge(path, size));
     return { kind, mimeType: videoMimeType(target)!, bytes: size };
@@ -105,6 +121,17 @@ export async function previewDeliverable(directory: string, id: string): Promise
   return { kind, dataUri: `data:${imageMimeType(target)};base64,${data.toString("base64")}`, bytes: size };
 }
 
+async function listFolder(target: string): Promise<{ entries: FolderEntry[]; truncated: boolean }> {
+  const entries: FolderEntry[] = [];
+  for (const entry of await readdir(target, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const linkedFolder = entry.isSymbolicLink() && (await stat(join(target, entry.name)).catch(() => null))?.isDirectory();
+    entries.push({ name: entry.name, folder: entry.isDirectory() || Boolean(linkedFolder) });
+  }
+  entries.sort((a, b) => Number(b.folder) - Number(a.folder) || a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" }));
+  return { entries: entries.slice(0, MAX_FOLDER_ENTRIES), truncated: entries.length > MAX_FOLDER_ENTRIES };
+}
+
 function tooLarge(path: string, size: number): string {
   return `${path} is ${Math.round(size / 1024 / 1024)} MB, too large to preview.`;
 }
@@ -145,5 +172,9 @@ export async function handleOpenDeliverable(
   input: { workspaceId: string; workspaceDirectory: string; ref: string },
   _context: PluginHandlerContext,
 ) {
-  return openDeliverable(input.workspaceDirectory, input.ref, systemOpener);
+  return openDeliverable(input.workspaceDirectory, input.ref, hostOpener(process.platform, process.env));
+}
+
+export async function handleCanOpenOnHost(_input: { workspaceId: string; workspaceDirectory: string }, _context: PluginHandlerContext) {
+  return { canOpen: canOpenFiles(process.platform, process.env) };
 }

package/shared/attachments.ts

@@ -88,11 +88,35 @@ export function previewKind(path: string): "image" | "video" | "text" | null {
   return TEXT_EXTENSIONS.has(extension(path) ?? "") ? "text" : null;
 }
 
+export function isFolder(attachment: Attachment): boolean {
+  return attachment.kind === "folder" || /[\\/]$/.test(attachment.path ?? "");
+}
+
+export interface FolderEntry {
+  name: string;
+  folder: boolean;
+}
+
+export function entryRef(folderRef: string, path: string): string {
+  return `${folderRef}/${path}`;
+}
+
+export function splitRef(ref: string): { base: string; inner: string } {
+  const [base, ...rest] = ref.split("/");
+  return { base, inner: rest.join("/") };
+}
+
+export function folderAttachments(folder: Attachment, entries: FolderEntry[]): Attachment[] {
+  const base = folder.path === "./" ? "" : (folder.path ?? "").replace(/[\\/]*$/, "/");
+  return entries.map((entry) => ({ ref: entryRef(folder.ref, entry.name), title: entry.name, path: `${base}${entry.name}${entry.folder ? "/" : ""}` }));
+}
+
 // Whether the preview dialog can show it. Only a browser draws SVG and plays
 // video: Paseo's desktop app can, the phone apps can't, so there they open on
 // the host like any other file.
 export function canPreview(attachment: Attachment, where: { browser: boolean }): boolean {
   if (!attachment.path) return false;
+  if (isFolder(attachment)) return true;
   const kind = previewKind(attachment.path);
   if (kind === "video" || (kind === "image" && extension(attachment.path) === ".svg")) return where.browser;
   return kind !== null;

package/shared/rpc.ts

@@ -124,6 +124,15 @@ export const openDeliverable = defineRpc({
   output: z.object({ opened: z.string() }),
 });
 
+export const canOpenOnHost = defineRpc({
+  name: "progress.host.can-open",
+  input: z.object({
+    workspaceId: z.string().min(1),
+    workspaceDirectory: z.string().min(1),
+  }),
+  output: z.object({ canOpen: z.boolean() }),
+});
+
 // An image or text file's contents, for the preview dialog. A video comes back
 // as its type and size only; its bytes follow in pieces (readDeliverablePiece).
 export const previewDeliverable = defineRpc({
@@ -138,6 +147,7 @@ export const previewDeliverable = defineRpc({
     z.object({ kind: z.literal("image"), dataUri: z.string(), bytes: z.number() }),
     z.object({ kind: z.literal("video"), mimeType: z.string(), bytes: z.number() }),
     z.object({ kind: z.literal("text"), text: z.string(), bytes: z.number(), truncated: z.boolean() }),
+    z.object({ kind: z.literal("folder"), entries: z.array(z.object({ name: z.string(), folder: z.boolean() })), truncated: z.boolean() }),
   ]),
 });