@stevecastaneda/paseo-progress 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Castaneda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# Progress
+
+A plugin for Paseo 0.9 and later that gives each worktree a live progress dashboard. Agents record progress with the `paseo-progress` command, which adds one line per change to `.scratch/progress.jsonl` in the worktree. The **Progress** panel draws the dashboard from that file and updates by itself.
+
+<img src="images/1-panel.png" alt="The Progress panel in Explorer" width="400">
+
+The dashboard shows:
+
+- the run's title, a headline ("2 of 4 tickets done, 5 questions waiting for you, 1 stuck"), a one-line "now" ticker, and when it was last updated
+- a "possibly stale" warning after 15 minutes with no update while tickets remain, unless Paseo shows an agent in the workspace still running (for example one waiting on its subagents), and never once every ticket is done or skipped or the run is finished; working items swap their spinner for a pulsing amber warning
+- percent of estimated work done, time done of time estimated (like "1 h 30 min of 2 h"; 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 an hourglass and "Waits for Ticket 03" 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 timeline of its stages and statuses with how long each took, notes, time worked against the estimate, and the deliverables, questions and activity that belong to it. 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 default the agent is using. 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 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.
+- **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
+
+The panel lives in Explorer, beside the agent chat, so you can watch both. Open it from Command Center with **Open Progress**. When questions are waiting or something is stuck, a pill above the message box shows it (`3 questions · 1 stuck`). Pressing it opens a popover with each open question, its choices and their Copy buttons, and what is stuck, so you can answer without leaving the chat. **Open Progress** at the bottom opens the panel in Explorer.
+
+On phones, where Paseo has no Explorer pane, Progress opens as a tab of its own, and the pill stays above the message box while a run is open so there's always a way in. SVG files preview on desktop; on phones they open on the daemon host.
+
+The first time a run starts in a worktree whose Progress panel has never been opened, the pill shows a spinner and reads **Progress** instead; pressing it opens the panel. Once the panel has been opened there, the plugin writes an empty `.scratch/progress-panel-opened` and the nudge never comes back, even for later runs. It doesn't open the panel by itself because Paseo switches to a workspace to open its panel, which would pull you away from whatever you're looking at.
+
+## Install
+
+```sh
+paseo plugin add npm:@stevecastaneda/paseo-progress
+```
+
+Or from GitHub: `paseo plugin add stevecastaneda/paseo-plugins --path progress`.
+
+Enable plugins under **Settings → Plugins** on the Paseo host. You need Node.js 22.18 or later on the daemon host.
+
+Then install the `paseo-progress` command agents run. Open **Progress** from Command Center and press **Install command** in the banner. It adds one file, `~/.local/bin/paseo-progress`, on the machine running the Paseo daemon, and the banner disappears once agents can run it. The plugin writes nothing until you press it, and it never replaces a file something else put at that path.
+
+To install from a terminal instead, or to put the command somewhere else:
+
+```sh
+dir="$(paseo plugin ls progress --json | node -pe 'JSON.parse(require("fs").readFileSync(0))[0].path')"
+node "$([ -f "$dir/dist/server/cli.js" ] && echo "$dir/dist/server/cli.js" || echo "$dir/server/cli.ts")" install-launcher [path]
+```
+
+If `paseo` isn't on your `PATH`, use `/Applications/Paseo.app/Contents/Resources/bin/paseo`. The command doesn't name a plugin folder: each run asks Paseo (`paseo plugin ls`) which copy of the plugin it is running and runs that copy, so it keeps working after updates and `npm run dev` switches. The npm package carries the command compiled to JavaScript in `dist/`, because Node won't run TypeScript from `node_modules`.
+
+The plugin keeps each worktree's progress in `.scratch/progress.jsonl`. The first time it creates `.scratch/`, it also writes `.scratch/.gitignore` naming only its own files, so git ignores them without any change to your repository's `.gitignore`. If `.scratch/.gitignore` already exists, the plugin leaves it alone.
+
+## Agent skill
+
+The plugin ships an agent skill, `paseo-progress`, that tells agents when to run each command during a multi-ticket job: set up the run, move tickets through their stages, ask questions without stopping, flag stuck work, and finish. Press **Install skill** in the Progress panel. It links `paseo-progress` into `~/.agents/skills`, `~/.claude/skills`, and `~/.codex/skills` (the folders Paseo installs its own skills into), pointing at the copy of the plugin Paseo runs, so plugin updates reach agents. If Paseo later runs the plugin from somewhere else, the button changes to **Update skill**. It never replaces a skill it didn't link; that folder is skipped.
+
+From a terminal instead:
+
+```sh
+skill="$(paseo plugin ls progress --json | node -pe 'JSON.parse(require("fs").readFileSync(0))[0].path')/skills/paseo-progress"
+for dir in ~/.agents/skills ~/.claude/skills ~/.codex/skills; do mkdir -p "$dir" && ln -s "$skill" "$dir/paseo-progress"; done
+```
+
+## Recording progress
+
+Run `paseo-progress --help` for every command, and `paseo-progress <command> --help` for one. Commands find the worktree root from the current directory.
+
+```sh
+paseo-progress start "Loan Options snapshots" --subtitle "4 tickets"
+paseo-progress ticket add "Ticket 01: Saved table" --estimate 120      # Added T01
+paseo-progress ticket update T01 --status working --stage Build
+paseo-progress ticket update T01 --stage Fixes
+paseo-progress ticket update T01 --status done
+paseo-progress question ask "Row spacing" "Even out the card spacing?" \
+  --option "A=Even it out | Cards look balanced" \
+  --option "B=Leave it | No change" \
+  --default B --raised-by "Ticket 01 design review"                     # Asked Q1
+paseo-progress question answer Q1 A --words "Even it out."
+paseo-progress deliverable add "Browser check screenshots" .scratch/shots/ --ticket T01
+paseo-progress activity add "Saved table matches the design now." --ticket T01
+paseo-progress ticker set "Running the browser check"
+paseo-progress stuck set "Staging is down" --ticket T01                 # Flagged S1
+paseo-progress show
+paseo-progress finish "Snapshots ship for all four tables"
+```
+
+- Statuses are `not_started`, `working`, `blocked`, `done`, and `skipped`. Skipped tickets leave the totals.
+- 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 --waits` marks a question the agent won't act on until you answer. Its default shows in amber.
+- 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. 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.
+- `start` begins a fresh dashboard. Earlier runs stay in the file. Question references stay unique across runs.
+- `finish "<outcome>"` closes the run once every ticket is done or skipped, no question is open, and nothing is flagged stuck; otherwise it says what is left. The run stays on the dashboard, marked Finished with its outcome, and takes no more updates, so the next agent in the worktree starts a new run instead of adding to it.
+
+## The progress file
+
+`.scratch/progress.jsonl` holds one JSON event per line, each with a version (`v`), a UTC timestamp (`ts`) from the real clock, and a `type`. It is only ever appended to, so you can read or diff the history. A half-written last line is ignored. Other bad lines are skipped and listed in a small notice in the panel while the rest still renders. A lock keeps two commands from writing at once or handing out the same id.
+
+## Limitations
+
+- Nothing updates unless the agent runs `paseo-progress`. Agents need the skill, and an agent that skips the command leaves the dashboard behind.
+- The command runs on the machine that hosts the Paseo daemon, and it needs Node.js 22.18 or later there.
+- Each worktree keeps its own dashboard in `.scratch/progress.jsonl`. There's no view across worktrees.
+- 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 and the first 256 KB of a text file. Other files open in their default app.
+- Stale warnings and overdue times use the daemon host's clock.
+
+## Local development
+
+```sh
+cd progress
+npm install
+npm run dev
+```
+
+`npm run dev` type-checks and tests the plugin, then points Paseo at this folder. The tests run the agent's commands in a throwaway worktree and read back the dashboard the panel would get.

package/client/attachments.tsx

@@ -0,0 +1,95 @@
+import { openExternalUrl, type PluginWorkspacePanelProps, useRpc } from "@getpaseo/plugin/client";
+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 { PressableRow } from "./row";
+import { openDeliverable } from "../shared/rpc";
+
+export { type Attachment, attachmentIcon, deliverableAttachment, questionAttachments, shortName } from "../shared/attachments";
+
+type Colors = PluginWorkspacePanelProps["theme"]["colors"];
+type Navigation = PluginWorkspacePanelProps["navigation"];
+
+// Shown in Paseo's preview dialog rather than handed to another app.
+export function isPreviewable(attachment: Attachment): boolean {
+  return canPreview(attachment, { browser: Platform.OS === "web" });
+}
+
+// Full path on the daemon host for a stored path.
+export function absolutePath(path: string, workspaceDirectory: string): string {
+  if (path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path)) return path;
+  const base = workspaceDirectory.replace(/[\\/]+$/, "");
+  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 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;
+  navigation?: Navigation;
+  onPreview?(attachment: Attachment): void;
+}) {
+  const toast = useToast();
+  const openOnHostRpc = useRpc(openDeliverable);
+  async function copyPath(attachment: Attachment, prefix = "") {
+    try {
+      await copyText(absolutePath(attachment.path!, workspaceDirectory));
+      toast.show(`${prefix}Copied path`, { variant: prefix ? "warning" : "success" });
+    } catch {
+      toast.error("Could not copy. Select the path and use Copy.");
+    }
+  }
+  async function openOnHost(attachment: Attachment) {
+    try {
+      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"}. `);
+    }
+  }
+  async function open(attachment: Attachment) {
+    if (attachment.url) {
+      try {
+        if (navigation?.openBrowser) navigation.openBrowser({ url: attachment.url, workspaceId });
+        else await openExternalUrl(attachment.url);
+      } catch {
+        toast.error("Could not open this link.");
+      }
+      return;
+    }
+    if (onPreview && isPreviewable(attachment)) {
+      onPreview(attachment);
+      return;
+    }
+    await openOnHost(attachment);
+  }
+  return { open, openOnHost, copyPath };
+}
+
+// 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 }}>
+      {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 }}>
+          {/* 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>
+          {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 }} />}
+        </PressableRow>
+      ))}
+    </View>
+  );
+}

package/client/dashboard-query.ts

@@ -0,0 +1,32 @@
+import { useRpc } from "@getpaseo/plugin/client";
+import type { RpcOutput } from "@getpaseo/plugin";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { type DashboardResult, getDashboard } from "../shared/rpc";
+
+type FetchDashboard = (input: { workspaceId: string; workspaceDirectory: string; since?: string }) => Promise<RpcOutput<typeof getDashboard>>;
+
+export const POLL_MS = 3_000;
+
+// `previous` is what the cache already holds. Polls send its version, and an
+// "unchanged" reply keeps that same object, so nothing re-renders.
+export function dashboardQueryOptions(fetchDashboard: FetchDashboard, hostId: string, workspaceId: string, directory: string | null, previous?: () => DashboardResult | undefined) {
+  return {
+    queryKey: ["progress", "dashboard", hostId, workspaceId, directory],
+    queryFn: async (): Promise<DashboardResult> => {
+      const last = previous?.();
+      const result = await fetchDashboard({ workspaceId, workspaceDirectory: directory!, ...(last ? { since: last.version } : {}) });
+      return "unchanged" in result && last ? last : result as DashboardResult;
+    },
+    enabled: Boolean(directory),
+    staleTime: POLL_MS,
+    refetchInterval: POLL_MS,
+  };
+}
+
+export function useDashboard(hostId: string, workspaceId: string, directory: string | null) {
+  const fetchDashboard = useRpc(getDashboard);
+  const queryClient = useQueryClient();
+  const options = dashboardQueryOptions(fetchDashboard, hostId, workspaceId, directory,
+    () => queryClient.getQueryData<DashboardResult>(options.queryKey));
+  return useQuery(options);
+}

package/client/deliverables.tsx

@@ -0,0 +1,67 @@
+import type { PluginWorkspacePanelProps } from "@getpaseo/plugin/client";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import React, { useState } from "react";
+import { Text, View } from "react-native";
+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 { PressableRow } from "./row";
+import { ShowMoreRow, usePaged } from "./show-more";
+
+export { absolutePath } from "./attachments";
+
+type Colors = PluginWorkspacePanelProps["theme"]["colors"];
+type Navigation = PluginWorkspacePanelProps["navigation"];
+
+// The Deliverables tab: newest first, 10 at a time (see usePaged).
+export function DeliverablesList({ colors, deliverables, now, workspaceId, workspaceDirectory, navigation }: {
+  colors: Colors;
+  now: number;
+  deliverables: Deliverable[];
+  workspaceId: string;
+  workspaceDirectory: string;
+  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 paged = usePaged(deliverables);
+  return (
+    <View>
+      {paged.shown.map((deliverable, index) => (
+        <PressableRow key={deliverable.id} colors={colors} accessibilityRole={deliverable.url ? "link" : "button"}
+          accessibilityLabel={`Open ${deliverable.title}`}
+          onPress={() => void open(deliverableAttachment(deliverable))}
+          style={{ flexDirection: "row", gap: 8, paddingHorizontal: 10, paddingVertical: 8, borderTopWidth: index ? 1 : 0, borderTopColor: colors.border }}>
+          {/* Optical: centers the 14px icon on the 18px title line. */}
+          <View style={{ paddingTop: 2 }}><Icon name={attachmentIcon(deliverableAttachment(deliverable))} size={14} color={colors.foregroundMuted} /></View>
+          <View style={{ flex: 1, minWidth: 0, gap: 1 }}>
+            {/* What the agent found is the headline; the row itself is what opens. */}
+            <Text numberOfLines={3} style={{ color: colors.foreground, fontSize: 13, lineHeight: 18 }}>{deliverable.title}</Text>
+            {/* Just the name, ticket and age. The full path is one press of Copy away. */}
+            <Text numberOfLines={1} style={{ color: colors.foregroundMuted, fontSize: 12, lineHeight: 17 }}>
+              {[shortName(deliverableAttachment(deliverable)), deliverable.ticketLabel ?? deliverable.ticketId, formatAgo(deliverable.addedAt, now)].filter(Boolean).join(" · ")}
+            </Text>
+          </View>
+          {deliverable.path ? (
+            // Optical: the 22px button centers on the 18px title line.
+            <PressScale accessibilityRole="button" accessibilityLabel={`Copy the path of ${deliverable.title}`} hitSlop={6} outerStyle={{ marginTop: -2 }}
+              onPress={() => void copyPath(deliverableAttachment(deliverable))}
+              // A step above the row's own hover tint (surface1), so it reads as its own target.
+              style={({ pressed, hovered }) => ({ padding: 4, borderRadius: 4, backgroundColor: pressed ? colors.border : hovered ? colors.surface2 : "transparent" })}>
+              <Icon name="Copy" size={14} color={colors.foregroundMuted} />
+            </PressScale>
+          ) : (
+            <View style={{ paddingTop: 2 }}><Icon name="ExternalLink" size={14} color={colors.foregroundMuted} /></View>
+          )}
+        </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 }} />
+    </View>
+  );
+}

package/client/dialog-stack.tsx

@@ -0,0 +1,104 @@
+import type { PluginWorkspacePanelProps } from "@getpaseo/plugin/client";
+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 { BackButton, PreviewContent, previewable } from "./preview";
+import { QuestionView, useCopy } from "./questions";
+import { TicketStoryView } from "./ticket-dialog";
+
+type Colors = PluginWorkspacePanelProps["theme"]["colors"];
+type AttachmentContext = { workspaceId: string; workspaceDirectory: string; navigation?: PluginWorkspacePanelProps["navigation"] };
+
+// What the dialog is showing. A preview keeps the files beside it for Previous and Next.
+export type Step =
+  | { kind: "ticket"; id: string }
+  | { 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 }: {
+  colors: Colors;
+  // The ticket or question it opens on; null closes it.
+  root: Step | null;
+  onClose(): void;
+  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([]);
+  }
+  // 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 openAttachment = (attachment: Attachment, from: Attachment[]) => {
+    group.current = from;
+    void opener.open(attachment);
+  };
+  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 = 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;
+  // The ticket or question it opened on went away (answered elsewhere, or a new run): close rather than show a blank dialog.
+  const rootMissing = root !== null && (root.kind === "ticket" ? !dashboard?.tickets.some((candidate) => candidate.id === root.id)
+    : root.kind === "question" ? !questions.some((candidate) => candidate.id === root.id) : false);
+  useEffect(() => {
+    if (rootMissing) onClose();
+  }, [rootMissing]);
+  const [previewLong, setPreviewLong] = useState(false);
+  const title = ticket ? `${ticket.id} · ${ticket.title}` : question ? `${question.id} · ${question.title}` : preview ? preview.attachment.title : "";
+  const icon = ticket ? "ListChecks" : question ? "MessageCircleQuestion" : preview ? attachmentIcon(preview.attachment) : "ListChecks";
+
+  return (
+    <Modal title={title} icon={<Icon name={icon} size={16} color={colors.foregroundMuted} />}
+      open={Boolean(root)} onOpenChange={(next) => { if (!next) onClose(); }}>
+      {/* One Modal.Content for every step: replacing it would re-present the sheet on phones. */}
+      <Modal.Content scrollable={!(preview && previewLong)}>
+      {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} />
+      ) : (
+        <>
+          {ticket && dashboard ? (
+            <TicketStoryView colors={colors} dashboard={dashboard} ticket={ticket} now={now} live={live}
+              onOpenAttachment={openAttachment} onOpenQuestion={(id) => push({ kind: "question", id })} />
+          ) : null}
+          {question ? (
+            <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}
+            </QuestionView>
+          ) : null}
+        </>
+      )}
+      </Modal.Content>
+    </Modal>
+  );
+}
+
+function stepName(step: Step): string {
+  return step.kind === "preview" ? step.attachment.title : step.id;
+}

package/client/directory.ts

@@ -0,0 +1,90 @@
+import type { OwnedSubscription, SubscriptionObserver } from "@getpaseo/client";
+
+type Page = {
+  entries: unknown[];
+  pageInfo: { hasMore: boolean; nextCursor?: string | null };
+};
+type Message = Parameters<SubscriptionObserver<unknown>["update"]>[0];
+
+// Paseo 0.9 returns an owned subscription from list({ subscribe: {} }). It
+// delivers the first page as a snapshot, again after every reconnect, then the
+// directory updates. Releasing it ends the daemon observation.
+export function observeDirectory<Result extends Page & { subscription?: OwnedSubscription<Result> }, Update>(options: {
+  list(options: { subscribe?: {}; page?: { cursor: string; limit: number } }): Promise<Result>;
+  select(message: Message): Update | undefined;
+  snapshot(entries: Result["entries"]): void;
+  update(update: Update): void;
+}) {
+  let stopped = false;
+  let retry: ReturnType<typeof setTimeout> | undefined;
+  let subscription: OwnedSubscription<Result> | undefined;
+  let generation = 0;
+  let buffered: Update[] | null = null;
+  const release = () => {
+    void subscription?.release().catch(() => undefined);
+    subscription = undefined;
+  };
+  const restart = (error: unknown) => {
+    generation++;
+    buffered = null;
+    release();
+    if (stopped) return;
+    console.error("Directory observation failed; retrying", error);
+    retry = setTimeout(() => void start(), 2_000);
+  };
+  const load = async (first: Result) => {
+    const run = ++generation;
+    buffered = [];
+    const entries = [...first.entries];
+    let page: Page = first;
+    try {
+      while (page.pageInfo.hasMore && page.pageInfo.nextCursor) {
+        page = await options.list({ page: { cursor: page.pageInfo.nextCursor, limit: 100 } });
+        if (stopped || run !== generation) return;
+        entries.push(...page.entries);
+      }
+    } catch (error) {
+      if (run === generation) restart(error);
+      return;
+    }
+    if (stopped || run !== generation) return;
+    // Replay changes received during pagination after the snapshot so late
+    // reads cannot resurrect removed targets or overwrite newer updates.
+    const pending = buffered ?? [];
+    buffered = null;
+    options.snapshot(entries);
+    for (const update of pending) {
+      if (stopped || run !== generation) break;
+      options.update(update);
+    }
+  };
+  const start = async () => {
+    try {
+      const result = await options.list({ subscribe: {} });
+      if (!result.subscription) throw new Error("Paseo did not return a directory subscription");
+      subscription = result.subscription;
+      if (stopped) return release();
+      subscription.subscribe({
+        snapshot: (first) => void load(first),
+        update: (message) => {
+          const update = options.select(message);
+          if (stopped || update === undefined) return;
+          if (buffered) buffered.push(update);
+          else options.update(update);
+        },
+        error: restart,
+      });
+    } catch (error) {
+      restart(error);
+    }
+  };
+  void start();
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    if (retry) clearTimeout(retry);
+    generation++;
+    buffered = null;
+    release();
+  };
+}

package/client/launcher.tsx

@@ -0,0 +1,111 @@
+import { type PluginWorkspacePanelProps, useRpc } from "@getpaseo/plugin/client";
+import { Icon, useToast } from "@getpaseo/plugin/client/react-native";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import React from "react";
+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";
+
+type Colors = PluginWorkspacePanelProps["theme"]["colors"];
+
+export function launcherQueryKey(hostId: string) {
+  return ["progress", "launcher", hostId];
+}
+
+export function skillQueryKey(hostId: string) {
+  return ["progress", "skill", hostId];
+}
+
+// What the banner says, or null when agents can already run the command.
+export function launcherNotice(status: LauncherStatus): { text: string; action?: string } | null {
+  switch (status.state) {
+    case "missing":
+      return { text: `Agents record progress with the paseo-progress command, which isn't installed yet. Installing adds one file: ${status.path}`, action: "Install command" };
+    case "outdated":
+      return { text: `An older paseo-progress command is installed at ${status.path}.`, action: "Update command" };
+    case "foreign":
+      return { text: `Something else already exists at ${status.path}, so the plugin won't install there. The README shows how to install it elsewhere.` };
+    case "current":
+      return status.onPath ? null : { text: `paseo-progress is installed, but its folder isn't on the PATH Paseo uses, so agents need the full path: ${status.path}` };
+  }
+}
+
+// What the skill banner says, or null when every agent folder has the skill.
+export function skillNotice(status: SkillStatus): { text: string; action?: string } | null {
+  const folders = (state: string) => status.targets.filter((target) => target.state === state).map((target) => target.path.replace(/\/paseo-progress$/, ""));
+  const skipped = folders("foreign").length ? ` Something else is already at ${folders("foreign").join(", ")}, so the plugin leaves it alone.` : "";
+  switch (status.state) {
+    case "missing":
+      return { text: `Agents learn when to record progress from the paseo-progress skill, which isn't installed yet. Installing adds a link in ${folders("missing").join(", ")}.${skipped}`, action: "Install skill" };
+    case "outdated":
+      return { text: `The paseo-progress skill in ${folders("outdated").join(", ")} points to a copy of the plugin Paseo no longer runs.${skipped}`, action: "Update skill" };
+    case "foreign":
+      return { text: `Something else already exists at every paseo-progress skill path, so the plugin won't install the skill.` };
+    case "current":
+      return null;
+  }
+}
+
+// Nothing is written until the user presses the button.
+export function LauncherBanner({ colors, host }: { colors: Colors; host: PluginWorkspacePanelProps["host"] }) {
+  const fetchStatus = useRpc(getLauncherStatus);
+  const install = useRpc(installLauncher);
+  const queryClient = useQueryClient();
+  const toast = useToast();
+  const status = useQuery({ queryKey: launcherQueryKey(host.id), queryFn: () => fetchStatus({}), staleTime: 60_000 });
+  const mutation = useMutation({
+    mutationFn: () => install({}),
+    onSuccess: (next) => {
+      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."),
+  });
+  const notice = status.data ? launcherNotice(status.data) : null;
+  return <SetupBanner colors={colors} icon="Terminal" notice={notice} pending={mutation.isPending} onPress={() => mutation.mutate()} />;
+}
+
+export function SkillBanner({ colors, host }: { colors: Colors; host: PluginWorkspacePanelProps["host"] }) {
+  const fetchStatus = useRpc(getSkillStatus);
+  const install = useRpc(installSkill);
+  const queryClient = useQueryClient();
+  const toast = useToast();
+  const status = useQuery({ queryKey: skillQueryKey(host.id), queryFn: () => fetchStatus({}), staleTime: 60_000 });
+  const mutation = useMutation({
+    mutationFn: () => install({}),
+    onSuccess: (next) => {
+      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."),
+  });
+  const notice = status.data ? skillNotice(status.data) : null;
+  return <SetupBanner colors={colors} icon="Sparkles" notice={notice} pending={mutation.isPending} onPress={() => mutation.mutate()} />;
+}
+
+function SetupBanner({ colors, icon, notice, pending, onPress }: {
+  colors: Colors;
+  icon: string;
+  notice: { text: string; action?: string } | null;
+  pending: boolean;
+  onPress(): void;
+}) {
+  return (
+    <Presence show={Boolean(notice)}>{notice ? (
+    <View style={{ flexDirection: "row", alignItems: "center", flexWrap: "wrap", gap: 10, margin: 12, marginBottom: 0, padding: 8, borderRadius: 12, ...raised(colors), backgroundColor: colors.surface1 }}>
+      {/* Held on the first line: the text wraps to several lines in the Explorer pane. */}
+      <View style={{ alignSelf: "flex-start", height: 17, justifyContent: "center" }}><Icon name={icon} size={14} color={colors.foregroundMuted} /></View>
+      <Text selectable style={{ flex: 1, minWidth: 200, color: colors.foregroundMuted, fontSize: 12, lineHeight: 17 }}>{notice.text}</Text>
+      {notice.action ? (
+        <PressScale accessibilityRole="button" disabled={pending} onPress={onPress}
+          style={({ pressed, hovered }) => ({ paddingHorizontal: 10, paddingVertical: 5, borderRadius: 4, backgroundColor: colors.accent, opacity: pressed || pending ? 0.7 : hovered ? 0.85 : 1 })}>
+          <Text style={{ color: colors.accentForeground, fontSize: 12, lineHeight: 16, fontWeight: "600" }}>
+            {pending ? "Installing…" : notice.action}
+          </Text>
+        </PressScale>
+      ) : null}
+    </View>
+    ) : null}</Presence>
+  );
+}