@hienlh/ppm 0.17.30 → 0.17.32

package/src/web/components/chat/turn-change-tray.tsx

@@ -0,0 +1,140 @@
+/**
+ * Desktop presentation of the change tray: an inline, non-modal two-pane panel
+ * directly below the message's action bar. Left pane lists the turn's files, right
+ * pane shows the selected file's edits.
+ *
+ * Both panes need `min-h-0` or the grid rows refuse to shrink and neither scrolls.
+ */
+import { useEffect, useId, useRef, useState } from "react";
+import { X } from "lucide-react";
+import { copyToClipboard } from "@/lib/clipboard";
+import { ownsGlobalShortcut } from "@/lib/owns-global-shortcut";
+import type { TurnFileChange } from "@/lib/aggregate-turn-file-changes";
+import { ChangeCounts, ChangeFileRow } from "./change-file-row";
+import { ChangeEditList } from "./change-edit-list";
+
+function splitPath(path: string): { base: string; dir: string } {
+  const i = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return i < 0 ? { base: path, dir: "" } : { base: path.slice(i + 1), dir: path.slice(0, i) };
+}
+
+/**
+ * Several messages in one chat can have a tray open at once, and `ownsGlobalShortcut`
+ * only narrows to the focused *tab*. The most recently opened tray claims the keys.
+ */
+let activeTrayId: string | null = null;
+
+/** `ownsGlobalShortcut` resolves the owning tab; it says nothing about text entry. */
+function isTextEntry(el: Element | null): boolean {
+  if (!(el instanceof HTMLElement)) return false;
+  return el.tagName === "INPUT" || el.tagName === "TEXTAREA" || el.isContentEditable;
+}
+
+export function TurnChangeTray({ changes, onJump, onClose }: {
+  changes: TurnFileChange[];
+  onJump: (editRef: string) => void;
+  onClose: () => void;
+}) {
+  // The desktop tray never shows a bare list — a file is always selected.
+  const [selected, setSelected] = useState(0);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+  const trayId = useId();
+
+  // Inline and non-modal: focus moves in, but is deliberately not trapped.
+  useEffect(() => {
+    activeTrayId = trayId;
+    listRef.current?.querySelector<HTMLElement>("button")?.focus();
+    return () => {
+      if (activeTrayId === trayId) activeTrayId = null;
+    };
+  }, [trayId]);
+
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (activeTrayId !== trayId) return;
+      if (!ownsGlobalShortcut(containerRef.current)) return;
+      if (isTextEntry(document.activeElement)) return;
+
+      if (e.key === "Escape") {
+        e.preventDefault();
+        onClose();
+      } else if (e.key === "j") {
+        e.preventDefault();
+        setSelected((i) => Math.min(i + 1, changes.length - 1));
+      } else if (e.key === "k") {
+        e.preventDefault();
+        setSelected((i) => Math.max(i - 1, 0));
+      } else if (e.key === "Enter") {
+        const editRef = changes[selected]?.edits[0]?.editRef;
+        if (editRef) {
+          e.preventDefault();
+          onJump(editRef);
+        }
+      }
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [trayId, changes, selected, onJump, onClose]);
+
+  const active = changes[Math.min(selected, changes.length - 1)];
+  if (!active) return null;
+  const { base, dir } = splitPath(active.filePath);
+
+  return (
+    <div ref={containerRef} className="mt-0.5 overflow-hidden rounded-[10px] border border-border-soft bg-bg">
+      <div className="grid h-[356px] grid-cols-[294px_1fr] grid-rows-[minmax(0,1fr)] bg-surface-elevated">
+        <div ref={listRef} className="min-h-0 overflow-y-auto border-r border-border-soft">
+          {changes.map((change, i) => (
+            <ChangeFileRow
+              key={change.filePath}
+              change={change}
+              dense
+              selected={i === selected}
+              onClick={() => setSelected(i)}
+            />
+          ))}
+          <p className="px-2.5 pt-2 pb-2.5 font-mono text-[10px] text-text-subtle">
+            j / k to move · enter to jump
+          </p>
+        </div>
+
+        <div className="min-h-0 overflow-y-auto">
+          <div className="sticky top-0 z-10 flex items-center gap-2 border-b border-border-soft bg-surface-elevated py-[5px] pl-2.5 pr-2">
+            <span className="shrink-0 font-mono text-xs font-medium text-text-primary">{base}</span>
+            {dir && (
+              <span
+                title={active.filePath}
+                className="min-w-0 flex-1 overflow-hidden text-ellipsis whitespace-nowrap font-mono text-[10.5px] text-text-subtle [direction:rtl] text-left"
+              >
+                {dir}
+              </span>
+            )}
+            <ChangeCounts
+              added={active.linesAdded}
+              removed={active.linesRemoved}
+              className="shrink-0 font-mono text-[11px]"
+            />
+            <button
+              type="button"
+              onClick={() => void copyToClipboard(active.filePath)}
+              className="shrink-0 rounded-md px-1.5 py-1 font-mono text-[10px] text-text-subtle transition-colors hover:bg-surface hover:text-text-primary"
+            >
+              copy path
+            </button>
+            <button
+              type="button"
+              onClick={onClose}
+              aria-label="Close change tray"
+              className="inline-flex size-8 shrink-0 items-center justify-center rounded-lg text-text-subtle transition-colors hover:bg-surface hover:text-text-primary"
+            >
+              <X className="size-3.5" />
+            </button>
+          </div>
+
+          <ChangeEditList change={active} onJump={onJump} />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/web/components/layout/cloud-alias-row.tsx

@@ -0,0 +1,163 @@
+import { useState, useEffect, useCallback } from "react";
+import { Loader2, Pencil, ExternalLink, Check, X } from "lucide-react";
+import { api } from "@/lib/api-client";
+
+/** Cloud's slug rules — mirrored here so a bad name fails before a round-trip. */
+const SLUG_REGEX = /^[a-z0-9][a-z0-9-]{1,31}$/;
+const SLUG_HINT = "2–32 characters: lowercase letters, numbers, hyphens.";
+
+interface Props {
+  /** Base URL of the cloud instance, e.g. https://cloud.ppm.sh */
+  cloudUrl: string;
+  /** Machine name — seeds the input with a sensible default slug. */
+  deviceName: string | null;
+}
+
+/** Strip the scheme so the permanent link reads like an address, not a URL. */
+function displayHost(cloudUrl: string): string {
+  return cloudUrl.replace(/^https?:\/\//, "").replace(/\/$/, "");
+}
+
+function suggestSlug(deviceName: string | null): string {
+  if (!deviceName) return "";
+  const slug = deviceName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
+  return SLUG_REGEX.test(slug) ? slug : "";
+}
+
+/**
+ * Permanent link for this machine. The tunnel URL rotates on every restart;
+ * the alias is the stable address that always resolves to the current one.
+ */
+export function CloudAliasRow({ cloudUrl, deviceName }: Props) {
+  const [slug, setSlug] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [unreadable, setUnreadable] = useState(false);
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState("");
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    (async () => {
+      try {
+        const res = await api.get<{ slug: string | null }>("/api/cloud/alias");
+        setSlug(res.slug);
+      } catch {
+        // A failed read must not look like "no link yet": saving uses the device
+        // secret, so it would succeed and silently replace a link already in use.
+        setUnreadable(true);
+      }
+      setLoading(false);
+    })();
+  }, []);
+
+  const startEdit = useCallback(() => {
+    setDraft(slug ?? suggestSlug(deviceName));
+    setError(null);
+    setEditing(true);
+  }, [slug, deviceName]);
+
+  const handleSave = useCallback(async () => {
+    const next = draft.trim().toLowerCase();
+    if (!SLUG_REGEX.test(next)) {
+      setError(SLUG_HINT);
+      return;
+    }
+    setSaving(true);
+    setError(null);
+    try {
+      const res = await api.patch<{ slug: string }>("/api/cloud/alias", { slug: next });
+      setSlug(res.slug);
+      setEditing(false);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Could not save that name");
+    } finally {
+      setSaving(false);
+    }
+  }, [draft]);
+
+  if (loading) return null;
+
+  if (unreadable) {
+    return (
+      <p className="text-[11px] text-muted-foreground leading-relaxed">
+        Couldn't check this machine's permanent link. Open the cloud dashboard, or sign in again.
+      </p>
+    );
+  }
+
+  if (editing) {
+    return (
+      <div className="space-y-1.5">
+        <span className="text-[10px] font-medium text-muted-foreground uppercase tracking-wide">Permanent link</span>
+        <div className="flex items-center gap-1">
+          <span className="text-xs font-mono text-muted-foreground shrink-0">{displayHost(cloudUrl)}/</span>
+          <input
+            autoFocus
+            value={draft}
+            onChange={(e) => setDraft(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") handleSave();
+              if (e.key === "Escape") setEditing(false);
+            }}
+            placeholder="my-mac"
+            // 16px font on mobile — anything smaller makes iOS zoom on focus.
+            className="flex-1 min-w-0 text-base md:text-xs font-mono text-foreground bg-muted px-2 min-h-11 md:min-h-0 md:py-1.5 rounded border border-border outline-none focus:border-primary"
+          />
+          <button
+            onClick={handleSave}
+            disabled={saving}
+            title="Save"
+            className="flex items-center justify-center size-11 md:size-8 rounded border border-border text-primary bg-muted hover:bg-accent transition-colors shrink-0 disabled:opacity-50"
+          >
+            {saving ? <Loader2 className="size-3.5 animate-spin" /> : <Check className="size-3.5" />}
+          </button>
+          <button
+            onClick={() => setEditing(false)}
+            title="Cancel"
+            className="flex items-center justify-center size-11 md:size-8 rounded border border-border text-muted-foreground bg-muted hover:bg-accent transition-colors shrink-0"
+          >
+            <X className="size-3.5" />
+          </button>
+        </div>
+        <p className="text-[10px] text-muted-foreground">{error ?? SLUG_HINT}</p>
+      </div>
+    );
+  }
+
+  if (!slug) {
+    return (
+      <button
+        onClick={startEdit}
+        className="w-full flex items-center justify-center gap-1.5 px-3 min-h-11 md:min-h-0 md:py-2 text-xs font-medium rounded-md border border-border hover:bg-muted transition-colors"
+      >
+        <Pencil className="size-3.5" />
+        Set a permanent link
+      </button>
+    );
+  }
+
+  return (
+    <div className="space-y-1">
+      <span className="text-[10px] font-medium text-muted-foreground uppercase tracking-wide">Permanent link</span>
+      <div className="flex items-center gap-1">
+        <a
+          href={`${cloudUrl}/${slug}`}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="flex-1 min-w-0 flex items-center gap-1 text-xs font-mono text-primary hover:underline truncate"
+        >
+          <span className="truncate">{displayHost(cloudUrl)}/{slug}</span>
+          <ExternalLink className="size-3 shrink-0" />
+        </a>
+        <button
+          onClick={startEdit}
+          title="Change permanent link"
+          className="flex items-center justify-center size-11 md:size-8 rounded border border-border text-muted-foreground bg-muted hover:bg-accent hover:text-foreground transition-colors shrink-0"
+        >
+          <Pencil className="size-3.5" />
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/web/components/layout/cloud-share-popover.tsx

@@ -3,6 +3,7 @@ import { Cloud, Share2, Loader2, Copy, Check, X, LogOut, Link, Unlink, ExternalL
 import { QRCodeSVG } from "qrcode.react";
 import { api } from "@/lib/api-client";
 import { copyToClipboard } from "@/lib/clipboard";
+import { CloudAliasRow } from "./cloud-alias-row";
 
 interface CloudStatus {
   logged_in: boolean;
@@ -250,13 +251,21 @@ export function CloudSharePopover({ onClose, variant = "popover" }: Props) {
                 )}
               </div>
             ) : (
-              <button
-                onClick={handleCloudLogin}
-                className="w-full flex items-center justify-center gap-1.5 px-3 py-2 text-xs font-medium rounded-md border border-border hover:bg-muted transition-colors"
-              >
-                <Cloud className="size-3.5" />
-                Sign in to PPM Cloud
-              </button>
+              <>
+                {shareUrl && (
+                  <p className="text-[11px] text-muted-foreground leading-relaxed">
+                    This link changes every time PPM restarts. Sign in to get a permanent one
+                    that always points here — private to your account.
+                  </p>
+                )}
+                <button
+                  onClick={handleCloudLogin}
+                  className="w-full flex items-center justify-center gap-1.5 px-3 py-2 text-xs font-medium rounded-md border border-border hover:bg-muted transition-colors"
+                >
+                  <Cloud className="size-3.5" />
+                  {shareUrl ? "Get a permanent link" : "Sign in to PPM Cloud"}
+                </button>
+              </>
             )}
           </div>
 
@@ -264,20 +273,23 @@ export function CloudSharePopover({ onClose, variant = "popover" }: Props) {
           {cloud?.logged_in && (
             <div className="space-y-1.5">
               {cloud.linked ? (
-                <div className="flex items-center justify-between text-xs">
-                  <div className="flex items-center gap-1.5 min-w-0">
-                    <Link className="size-3 text-primary shrink-0" />
-                    <span className="text-foreground truncate">{cloud.device_name}</span>
+                <>
+                  <div className="flex items-center justify-between text-xs">
+                    <div className="flex items-center gap-1.5 min-w-0">
+                      <Link className="size-3 text-primary shrink-0" />
+                      <span className="text-foreground truncate">{cloud.device_name}</span>
+                    </div>
+                    <button
+                      onClick={handleUnlink}
+                      disabled={unlinking}
+                      className="text-text-subtle hover:text-destructive p-1 rounded hover:bg-muted transition-colors shrink-0"
+                      title="Unlink device"
+                    >
+                      {unlinking ? <Loader2 className="size-3 animate-spin" /> : <Unlink className="size-3" />}
+                    </button>
                   </div>
-                  <button
-                    onClick={handleUnlink}
-                    disabled={unlinking}
-                    className="text-text-subtle hover:text-destructive p-1 rounded hover:bg-muted transition-colors shrink-0"
-                    title="Unlink device"
-                  >
-                    {unlinking ? <Loader2 className="size-3 animate-spin" /> : <Unlink className="size-3" />}
-                  </button>
-                </div>
+                  <CloudAliasRow cloudUrl={cloud.cloud_url} deviceName={cloud.device_name} />
+                </>
               ) : (
                 <button
                   onClick={handleLink}

package/src/web/components/layout/command-palette.tsx

@@ -17,6 +17,7 @@ import {
   RefreshCw,
   Plus,
   Columns2,
+  Cloud,
 } from "lucide-react";
 import { useTabStore, type TabType } from "@/stores/tab-store";
 import { useProjectStore } from "@/stores/project-store";
@@ -193,6 +194,7 @@ export function CommandPalette({ open, onClose, initialQuery = "" }: { open: boo
       { id: "new-db-query", label: "New DB Query", icon: Database, action: () => { useTabStore.getState().openNewFile({ language: "sql", title: "SQL Query" }); onClose(); }, keywords: "sql database query scratchpad new", group: "action" },
       { id: "terminal", label: "New Terminal", icon: Terminal, action: openNewTab("terminal", "Terminal"), keywords: "bash shell console", group: "action", shortcut: formatShortcut(getBinding("open-terminal")) },
       { id: "tunnels", label: "Cloudflare Tunnels", icon: Globe, action: () => { if (sidebarCollapsed) toggleSidebar(); setSidebarActiveTab("tunnels"); onClose(); }, keywords: "web preview localhost port forward tunnel cloudflare url", group: "action" },
+      { id: "cloud-share", label: "PPM Cloud & Share", icon: Cloud, action: () => { window.dispatchEvent(new CustomEvent("open-cloud-share")); onClose(); }, keywords: "cloud permanent link alias share phone remote device qr sign in login", group: "action" },
       { id: "postgres", label: "PostgreSQL", icon: Database, action: openNewTab("postgres", "PostgreSQL"), keywords: "database pg sql query", group: "action" },
       { id: "voice-input", label: "Voice Input", icon: Mic, action: () => { window.dispatchEvent(new CustomEvent("toggle-voice-input")); onClose(); }, keywords: "speech microphone dictate voice", group: "action", shortcut: formatShortcut(getBinding("voice-input")) },
       { id: "git-status", label: "Git Status", icon: GitCommitHorizontal, action: () => { setSidebarActiveTab("git"); onClose(); }, keywords: "changes diff staged", group: "action", shortcut: formatShortcut(getBinding("open-git-status")) },

package/src/web/components/layout/mobile-drawer.tsx

@@ -21,6 +21,7 @@ import { openBugReportPopup } from "@/lib/report-bug";
 import { UpgradeButton } from "@/components/layout/upgrade-button";
 import { CloudSharePopover } from "@/components/layout/cloud-share-popover";
 import { BottomSheet } from "@/components/ui/mobile-bottom-sheet";
+import { isMobileDevice } from "@/hooks/use-is-mobile";
 import { cn } from "@/lib/utils";
 
 // Tab ids the mobile drawer can render content for. `search` is desktop-only for now;
@@ -62,6 +63,15 @@ export function MobileDrawer({ isOpen, onClose, initialTab }: MobileDrawerProps)
     if (tabs.length > 0 && !tabs.some((t) => t.id === activeTab)) setActiveTab(tabs[0]!.id);
   }, [tabs, activeTab]);
 
+  // Command palette request — the desktop rail is hidden on mobile, so the
+  // sheet here is what opens. The sheet portals to body, so it shows even while
+  // the drawer itself is closed.
+  useEffect(() => {
+    const open = () => { if (isMobileDevice()) setCloudOpen(true); };
+    window.addEventListener("open-cloud-share", open);
+    return () => window.removeEventListener("open-cloud-share", open);
+  }, []);
+
   const handleReportBug = useCallback(() => openBugReportPopup(version), [version]);
 
   const noProject = (

package/src/web/components/layout/nav-section-rail.tsx

@@ -13,6 +13,7 @@ import { useNotificationStore, selectProjectUnread } from "@/stores/notification
 import { NotificationBellPopover } from "./notification-bell-popover";
 import { CloudSharePopover } from "./cloud-share-popover";
 import { openBugReportPopup } from "@/lib/report-bug";
+import { isMobileDevice } from "@/hooks/use-is-mobile";
 import { cn } from "@/lib/utils";
 
 function Badge({ count }: { count: number }) {
@@ -135,6 +136,14 @@ export const NavSectionRail = memo(function NavSectionRail({ className }: { clas
     setPopoverPos({ left: rect.right + 6, bottom: window.innerHeight - rect.bottom });
   }, [cloudOpen]);
 
+  // Command palette can't reach the popover's local state, so it asks via event.
+  // The rail is `hidden md:flex`, so on mobile the drawer's bottom sheet answers.
+  useEffect(() => {
+    const open = () => { if (!isMobileDevice()) setCloudOpen(true); };
+    window.addEventListener("open-cloud-share", open);
+    return () => window.removeEventListener("open-cloud-share", open);
+  }, []);
+
   const handleReportBug = () => openBugReportPopup(version);
 
   // Rail tab click: collapsed → open on any tab; open → clicking the active tab closes it.

package/src/web/components/settings/settings-tab.tsx

@@ -279,16 +279,16 @@ export function SettingsTab() {
 function NotificationsContent() {
   return (
     <div className="space-y-4">
-      {/* Cloud Push */}
+      {/* Browser push */}
       <section className="space-y-2">
         <h3 className="text-xs font-medium text-muted-foreground">Push Notifications</h3>
         <div className="flex items-center gap-1.5">
           <Bell className="size-3.5 text-muted-foreground" />
-          <span className="text-xs">Managed via PPM Cloud</span>
+          <span className="text-xs">Not available yet</span>
         </div>
         <p className="text-[11px] text-muted-foreground">
-          Push notifications are now dispatched through PPM Cloud.
-          Visit your Cloud dashboard to manage subscriptions.
+          Browser push does not deliver right now.
+          Use Telegram below to get alerted when a session finishes or needs approval.
         </p>
       </section>
 

package/src/web/lib/aggregate-turn-file-changes.ts

@@ -0,0 +1,193 @@
+/**
+ * Aggregate the file mutations of a single assistant turn.
+ *
+ * Feeds the change tray (see turn-change-pill.tsx). Pure — no I/O, no React — so it
+ * works identically on live-streamed events and on messages parsed back from a JSONL
+ * transcript.
+ *
+ * Note on diffs: Edit's `old_string`/`new_string` are disjoint *fragments* at unknown
+ * offsets, so per-file edits cannot be composed into one whole-file diff. Each
+ * fragment is kept separate and rendered on its own.
+ */
+import { diffLines } from "diff";
+import type { ChatEvent, ChatMessage } from "../../types/chat";
+
+export type FileChangeOp = "create" | "write" | "edit" | "notebook";
+
+/** Tools whose input mutates a file. Kept in one place so it stays greppable. */
+export const FILE_MUTATION_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+
+/** Rank for resolving `op` when several tools touch the same file in one turn. */
+const OP_RANK: Record<FileChangeOp, number> = { create: 3, write: 2, notebook: 2, edit: 1 };
+
+export interface FileEditFragment {
+  /** "" for Write/NotebookEdit — the prior content is not in the tool input. */
+  oldStr: string;
+  newStr: string;
+  toolUseId?: string;
+  /** Index within this tool call's edits (always 0 except MultiEdit). */
+  editIndex: number;
+  /** Anchor key matching `data-edit-ref` on the tool card. */
+  editRef?: string;
+  viaSubagent: boolean;
+}
+
+export interface TurnFileChange {
+  filePath: string;
+  op: FileChangeOp;
+  editCount: number;
+  linesAdded: number;
+  linesRemoved: number;
+  edits: FileEditFragment[];
+  /** True when *any* edit to this file came from a spawned sub-agent. */
+  viaSubagent: boolean;
+}
+
+function str(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}
+
+function countLines(oldStr: string, newStr: string): { added: number; removed: number } {
+  let added = 0;
+  let removed = 0;
+  for (const part of diffLines(oldStr, newStr)) {
+    if (part.added) added += part.count ?? 0;
+    else if (part.removed) removed += part.count ?? 0;
+  }
+  return { added, removed };
+}
+
+/**
+ * Write's input looks identical whether the file existed or not — only the tool
+ * result distinguishes them. Absent during streaming, hence the "write" default.
+ */
+function writeOp(output: string | undefined): FileChangeOp {
+  return output && /created successfully/i.test(output) ? "create" : "write";
+}
+
+type RawChange = { filePath: string; op: FileChangeOp; fragments: Array<{ oldStr: string; newStr: string }> };
+
+function extractChange(tool: string, input: Record<string, unknown>, result?: string): RawChange | null {
+  switch (tool) {
+    case "Write": {
+      const filePath = str(input.file_path);
+      if (!filePath) return null;
+      return { filePath, op: writeOp(result), fragments: [{ oldStr: "", newStr: str(input.content) }] };
+    }
+    case "Edit": {
+      const filePath = str(input.file_path);
+      if (!filePath) return null;
+      return {
+        filePath,
+        op: "edit",
+        fragments: [{ oldStr: str(input.old_string), newStr: str(input.new_string) }],
+      };
+    }
+    case "MultiEdit": {
+      const filePath = str(input.file_path);
+      if (!filePath || !Array.isArray(input.edits)) return null;
+      const fragments = (input.edits as unknown[])
+        .filter((e): e is Record<string, unknown> => !!e && typeof e === "object")
+        .map((e) => ({ oldStr: str(e.old_string), newStr: str(e.new_string) }));
+      if (fragments.length === 0) return null;
+      return { filePath, op: "edit", fragments };
+    }
+    case "NotebookEdit": {
+      // Real param is `notebook_path`; file_path accepted because callers vary.
+      const filePath = str(input.notebook_path) || str(input.file_path);
+      if (!filePath) return null;
+      return { filePath, op: "notebook", fragments: [{ oldStr: "", newStr: str(input.new_source) }] };
+    }
+    default:
+      return null;
+  }
+}
+
+/** Index tool_result output by toolUseId, recursing into sub-agent children. */
+function collectResults(events: ChatEvent[] | undefined, out: Map<string, string>): void {
+  if (!events) return;
+  for (const ev of events) {
+    if (ev.type === "tool_result" && ev.toolUseId) out.set(ev.toolUseId, ev.output ?? "");
+    if (ev.type === "tool_use") {
+      // The WS layer also embeds the result onto the tool_use for reconnect replay.
+      const embedded = (ev as { result?: { output?: string } }).result;
+      if (ev.toolUseId && embedded?.output != null && !out.has(ev.toolUseId)) {
+        out.set(ev.toolUseId, embedded.output);
+      }
+      collectResults(ev.children, out);
+    }
+  }
+}
+
+function walk(
+  events: ChatEvent[] | undefined,
+  viaSubagent: boolean,
+  files: Map<string, TurnFileChange>,
+  results: Map<string, string>,
+): void {
+  if (!events) return;
+  for (const ev of events) {
+    if (ev.type !== "tool_use") continue;
+    // Agent/Task wrap their own event stream — everything inside is sub-agent work.
+    if (ev.children?.length) walk(ev.children, true, files, results);
+    if (!FILE_MUTATION_TOOLS.has(ev.tool)) continue;
+
+    const input = ev.input && typeof ev.input === "object" ? (ev.input as Record<string, unknown>) : null;
+    if (!input) continue;
+    const raw = extractChange(ev.tool, input, ev.toolUseId ? results.get(ev.toolUseId) : undefined);
+    if (!raw) continue;
+
+    let entry = files.get(raw.filePath);
+    if (!entry) {
+      // Map insertion order gives first-touched ordering for free.
+      entry = {
+        filePath: raw.filePath,
+        op: raw.op,
+        editCount: 0,
+        linesAdded: 0,
+        linesRemoved: 0,
+        edits: [],
+        viaSubagent: false,
+      };
+      files.set(raw.filePath, entry);
+    }
+    if (OP_RANK[raw.op] > OP_RANK[entry.op]) entry.op = raw.op;
+    if (viaSubagent) entry.viaSubagent = true;
+
+    raw.fragments.forEach((frag, editIndex) => {
+      const { added, removed } = countLines(frag.oldStr, frag.newStr);
+      entry!.linesAdded += added;
+      entry!.linesRemoved += removed;
+      entry!.editCount += 1;
+      entry!.edits.push({
+        ...frag,
+        toolUseId: ev.toolUseId,
+        editIndex,
+        editRef: ev.toolUseId ? `${ev.toolUseId}-${editIndex}` : undefined,
+        viaSubagent,
+      });
+    });
+  }
+}
+
+/** Files mutated by one turn, in the order the turn first touched them. */
+export function aggregateTurnFileChanges(messages: ChatMessage[]): TurnFileChange[] {
+  const results = new Map<string, string>();
+  for (const msg of messages) collectResults(msg.events, results);
+
+  const files = new Map<string, TurnFileChange>();
+  for (const msg of messages) walk(msg.events, false, files, results);
+  return [...files.values()];
+}
+
+/**
+ * A turn spans every consecutive assistant message ending at `lastAssistantIndex`
+ * (text and tool segments arrive as separate messages).
+ */
+export function collectTurnMessages(messages: ChatMessage[], lastAssistantIndex: number): ChatMessage[] {
+  const out: ChatMessage[] = [];
+  for (let i = lastAssistantIndex; i >= 0 && messages[i]?.role === "assistant"; i--) {
+    out.unshift(messages[i]!);
+  }
+  return out;
+}