@hienlh/ppm 0.23.13 → 0.23.15

package/src/web/lib/open-ai-tab.ts

@@ -3,15 +3,22 @@ import { useProjectStore } from "@/stores/project-store";
 import { absoluteProjectPath, relativeProjectPath } from "@/stores/file-store";
 import { fsApi } from "@/lib/fs-api";
 import { basename } from "@/lib/utils";
-import { chooseAiTabPlacement, isTabForFile } from "./ai-tab-placement";
+import { previewTitle } from "./web-preview-url";
+import { chooseAiTabPlacement, isTabForFile, type AiTabPlacement, type PlacementTab } from "./ai-tab-placement";
 import { latestPreviewLoad, previewKey, waitForPreviewLoad } from "./html-preview-loads";
-import type { TabOpenRequest, TabOpenResult, TabTool } from "../../shared/tab-open-protocol";
+import { nextQueryNumber, queryTabMetadata, targetFields } from "./db-tabs";
+import {
+  OPEN_URL_TOOL, RUN_IN_TERMINAL_TOOL, type TabOpenRequest, type TabOpenResult, type TabOpenTerminalRequest, type TabOpenUrlRequest,
+  type TabTool,
+} from "../../shared/tab-open-protocol";
+import { OPEN_QUERY_TOOL, type DbQueryTabOpen } from "../../shared/db-ai-tools";
 
 /**
- * Opens the tab the AI asked for with `open_file` or `open_preview`, beside the chat that
- * asked (`ai-tab-placement.ts` decides where), and answers the server's `tab_open`. A tool
- * card's Open button goes through the same {@link openAiTab}, so a tab reopened from the
- * chat's history lands where the AI's own call put it.
+ * Opens the tab the AI asked for with `open_file`, `open_preview`, `open_query` or `open_url`,
+ * beside the chat that asked (`ai-tab-placement.ts` decides where), or the terminal
+ * `run_in_terminal` started, in the dock; and answers the server's `tab_open`. A tool card's
+ * Open button goes through the same {@link openAiTab}, so a tab reopened from the chat's
+ * history lands where the AI's own call put it.
  *
  * The editor reads `aiView` and `aiOpenAt` from the tab's metadata: every call switches the
  * view the tool asked for and reloads a preview, also in a tab that was already open.
@@ -50,11 +57,8 @@ function showChatWorkspace(projectName: string | undefined): void {
   usePanelStore.getState().switchProject(projectName);
 }
 
-/**
- * Opens (or brings back) the file's tab. Returns the preview key the editor will load the
- * page under and the last load already seen there, so a caller can wait for the next one.
- */
-export function openAiTab(target: AiTabTarget, chat: AiTabChat): { tabId: string; previewKey: string; before: number } {
+/** Where a tab goes beside the chat, in the chat's workspace, which is brought up first. */
+function placeBesideChat(chat: AiTabChat, isTarget: (tab: PlacementTab) => boolean): AiTabPlacement {
   showChatWorkspace(chat.projectName);
   const store = usePanelStore.getState();
   const placement = chooseAiTabPlacement({
@@ -63,9 +67,32 @@ export function openAiTab(target: AiTabTarget, chat: AiTabChat): { tabId: string
     focusedPanelId: store.focusedPanelId,
     mobile: store.isMobile(),
     sessionId: chat.sessionId,
-    isTarget: (tab) => isTabForFile(tab, target.filePath, target.projectName),
+    isTarget,
   });
   if (!placement) throw new Error("PPM has no panel to open the tab in");
+  return placement;
+}
+
+/** Brings a tab that is already open to where the placement wants it: in front, moved or split out. */
+function showExistingTab(placement: Exclude<AiTabPlacement, { kind: "open" }>): void {
+  const store = usePanelStore.getState();
+  const fromPanelId = placement.kind === "focus" ? placement.panelId : placement.fromPanelId;
+  if (placement.kind === "focus") {
+    store.setActiveTab(placement.tabId, placement.panelId);
+  } else if (placement.toPanelId) {
+    store.moveTab(placement.tabId, fromPanelId, placement.toPanelId);
+  } else if (!store.splitPanel("right", placement.tabId, fromPanelId)) {
+    store.setActiveTab(placement.tabId, fromPanelId);
+  }
+}
+
+/**
+ * Opens (or brings back) the file's tab. Returns the preview key the editor will load the
+ * page under and the last load already seen there, so a caller can wait for the next one.
+ */
+export function openAiTab(target: AiTabTarget, chat: AiTabChat): { tabId: string; previewKey: string; before: number } {
+  const placement = placeBesideChat(chat, (tab) => isTabForFile(tab, target.filePath, target.projectName));
+  const store = usePanelStore.getState();
 
   const now = Date.now();
   const aiView = target.line ? "code" : target.tool === "open_preview" ? "preview" : undefined;
@@ -93,16 +120,88 @@ export function openAiTab(target: AiTabTarget, chat: AiTabChat): { tabId: string
   const key = previewKey(metadata.projectName as string | undefined, String(metadata.filePath ?? target.filePath));
   const before = latestPreviewLoad(key);
   store.updateTab(placement.tabId, { metadata });
-  if (placement.kind === "focus") {
-    store.setActiveTab(placement.tabId, placement.panelId);
-  } else if (placement.toPanelId) {
-    store.moveTab(placement.tabId, fromPanelId, placement.toPanelId);
-  } else if (!store.splitPanel("right", placement.tabId, fromPanelId)) {
-    store.setActiveTab(placement.tabId, fromPanelId);
-  }
+  showExistingTab(placement);
   return { tabId: placement.tabId, previewKey: key, before };
 }
 
+/**
+ * Opens a Query tab holding the script `open_query` wrote, beside the chat. Nothing runs until
+ * the user presses Run. Every call opens a tab of its own, so a script never replaces SQL the
+ * user is editing in another one.
+ */
+export function openAiQueryTab(query: DbQueryTabOpen, chat: AiTabChat): string {
+  const placement = placeBesideChat(chat, () => false);
+  if (placement.kind !== "open") throw new Error("PPM has no panel to open the tab in");
+  const store = usePanelStore.getState();
+  const queryNumber = nextQueryNumber(Object.values(store.panels).flatMap((p) => p.tabs));
+  const target = { kind: "connection" as const, connectionId: query.connectionId, ...(query.database ? { database: query.database } : {}) };
+  const tabId = store.openTab({
+    type: "db-query",
+    title: `Query ${queryNumber}`,
+    // A saved connection's tab shows in every project's workspace, as one opened from the tree does.
+    projectId: null,
+    closable: true,
+    metadata: {
+      ...targetFields(target),
+      connectionName: query.connectionName,
+      dbType: query.dbType,
+      ...(query.connectionColor ? { connectionColor: query.connectionColor } : {}),
+      ...queryTabMetadata(query.sql, queryNumber),
+    },
+  }, placement.panelId);
+  if (!tabId) throw new Error("PPM could not open the tab");
+  if (placement.split) store.splitPanel("right", tabId, placement.panelId);
+  return tabId;
+}
+
+/** Whether this browser runs on the machine PPM runs on, where `localhost` is the host's own. */
+export function browserOnHost(hostname: string = window.location.hostname): boolean {
+  return hostname === "localhost" || hostname === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(hostname);
+}
+
+/**
+ * Opens the web server `open_url` asked for in a web-preview tab beside the chat, the tab Port
+ * Forwarding opens. A tab already showing that address is reused, and reloaded.
+ */
+export function openAiUrlTab(req: Pick<TabOpenUrlRequest, "url" | "port" | "via">, chat: AiTabChat): string {
+  if (req.via === "local" && !browserOnHost()) {
+    throw new Error(`this device is not the machine PPM runs on, so it cannot reach localhost:${req.port}`);
+  }
+  const placement = placeBesideChat(chat, (tab) => tab.type === "web-preview" && tab.metadata?.url === req.url);
+  const store = usePanelStore.getState();
+  const metadata = { url: req.url, port: req.port, via: req.via, aiOpenAt: Date.now() };
+  if (placement.kind === "open") {
+    const tabId = store.openTab(
+      { type: "web-preview", title: previewTitle(req.port, req.url), projectId: null, closable: true, metadata },
+      placement.panelId,
+    );
+    if (!tabId) throw new Error("PPM could not open the tab");
+    if (placement.split) store.splitPanel("right", tabId, placement.panelId);
+    return tabId;
+  }
+  store.updateTab(placement.tabId, { metadata });
+  showExistingTab(placement);
+  return placement.tabId;
+}
+
+/**
+ * Shows the terminal `run_in_terminal` started, in the dock, with the AI's command already typed
+ * at its prompt by the server. The tab attaches to that terminal rather than starting a shell.
+ */
+export function openAiTerminal(req: Pick<TabOpenTerminalRequest, "terminalId" | "projectName" | "cwd">, chat: AiTabChat): string {
+  showChatWorkspace(chat.projectName);
+  const tabId = usePanelStore.getState().openInDock({
+    type: "terminal",
+    title: basename(req.cwd) || req.cwd,
+    projectId: req.projectName,
+    closable: true,
+    metadata: { sessionId: req.terminalId, cwd: req.cwd, ...(req.projectName ? { projectName: req.projectName } : {}) },
+  });
+  // A terminal tab reattaches to the session its id last had before it reads its metadata.
+  try { localStorage.setItem(`ppm:terminal-session:${tabId}`, req.terminalId); } catch { /* storage blocked */ }
+  return tabId;
+}
+
 /**
  * Answers the server's `tab_open`: opens the tab and, for a page the AI made, waits for it to
  * load and settle and returns the check of how it rendered. Every outcome is answered — a
@@ -113,6 +212,17 @@ export async function answerTabOpen(req: TabOpenRequest, chat: AiTabChat, send:
     const result: TabOpenResult = { type: "tab_open_result", requestId: req.requestId, ...answer };
     send(JSON.stringify(result));
   };
+  if (req.tool === OPEN_QUERY_TOOL || req.tool === OPEN_URL_TOOL || req.tool === RUN_IN_TERMINAL_TOOL) {
+    try {
+      if (req.tool === OPEN_QUERY_TOOL) openAiQueryTab(req.query, chat);
+      else if (req.tool === OPEN_URL_TOOL) openAiUrlTab(req, chat);
+      else openAiTerminal(req, chat);
+      reply({ opened: true });
+    } catch (e) {
+      reply({ opened: false, error: errorText(e) });
+    }
+    return;
+  }
   let opened: ReturnType<typeof openAiTab>;
   try {
     opened = openAiTab({ tool: req.tool, filePath: req.filePath, projectName: req.projectName, line: req.line }, chat);

package/src/web/lib/running-agent-rows.ts

@@ -9,6 +9,7 @@
 import type { ChatEvent, ChatMessage } from "../../types/chat";
 import type { TeamMemberActivity } from "../hooks/use-team-activity-feed";
 import type { AgentTranscriptRunningEntry } from "../../shared/agent-transcript-protocol";
+import { isAsyncAgentLaunchAck } from "../../shared/background-agent-status";
 
 export interface RunningAgentRow {
   key: string;
@@ -19,6 +20,9 @@ export interface RunningAgentRow {
   /** ISO timestamp — only known for a teammate the team panel has already polled. */
   startedAt?: string;
   lastWriteAt?: number;
+  /** A sibling that has finished, listed beside the agents of its batch still at work. */
+  done?: boolean;
+  failed?: boolean;
 }
 
 /**
@@ -78,6 +82,8 @@ function currentStepOf(member: TeamMemberActivity): string | undefined {
 export interface CardLabel {
   handle: string | null;
   description: string;
+  /** Timestamp of the message that launched the card — the nearest thing to a start time. */
+  launchedAt?: string;
 }
 
 function addressableName(input: unknown): string | null {
@@ -85,6 +91,51 @@ function addressableName(input: unknown): string | null {
   return typeof name === "string" && name.trim() ? name.trim() : null;
 }
 
+function isAgentCall(ev: ChatEvent): ev is Extract<ChatEvent, { type: "tool_use" }> {
+  return ev.type === "tool_use" && (ev.tool === "Agent" || ev.tool === "Task") && !!ev.toolUseId;
+}
+
+/**
+ * Agents that finished beside ones still running: the other `Agent`/`Task` calls of any
+ * message that launched a running card, so a fan-out reads "5 running · 1 done".
+ *
+ * The hub's feed is the only judge of who runs, so a sibling it does not report is done;
+ * the call itself only says whether it failed. Agents of a launch with nothing left
+ * running stay off the bar.
+ */
+export function finishedSiblingRows(messages: ChatMessage[], running: RunningAgentRow[]): RunningAgentRow[] {
+  const runningCards = new Set(running.map((r) => r.cardId).filter(Boolean));
+  if (runningCards.size === 0) return [];
+  const rows: RunningAgentRow[] = [];
+  const seen = new Set<string>();
+  for (const msg of messages) {
+    const calls = (msg.events ?? []).filter(isAgentCall);
+    if (!calls.some((c) => runningCards.has(c.toolUseId!))) continue;
+    for (const call of calls) {
+      const id = call.toolUseId!;
+      if (runningCards.has(id) || seen.has(id)) continue;
+      seen.add(id);
+      rows.push({
+        key: `card:${id}`,
+        cardId: id,
+        ...(addressableName(call.input) ? { memberName: addressableName(call.input)! } : {}),
+        done: true,
+        failed: callFailed(msg.events!, call),
+      });
+    }
+  }
+  return rows;
+}
+
+function callFailed(events: ChatEvent[], call: Extract<ChatEvent, { type: "tool_use" }>): boolean {
+  if (call.bgStatus) return call.bgStatus !== "completed";
+  const result = events.find((e) => e.type === "tool_result" && e.toolUseId === call.toolUseId)
+    ?? (call as { result?: { output?: string; isError?: boolean } }).result;
+  if (!result) return false;
+  const r = result as { output?: unknown; isError?: boolean };
+  return !!r.isError && !isAsyncAgentLaunchAck(String(r.output ?? ""));
+}
+
 function findInEvents(events: ChatEvent[] | undefined, cardId: string): ChatEvent | undefined {
   if (!events) return undefined;
   for (const ev of events) {
@@ -106,6 +157,7 @@ export function findCardLabel(messages: ChatMessage[], cardId: string): CardLabe
         handle: addressableName(input),
         description: typeof input.description === "string" ? input.description
           : typeof input.prompt === "string" ? input.prompt : "",
+        launchedAt: messages[i]!.timestamp,
       };
     }
   }

package/src/web/lib/session-file-changes-client.ts

@@ -31,6 +31,12 @@ export async function fetchSessionFileChanges(
   return Array.isArray(res?.files) ? res.files : [];
 }
 
+/** How many files the session kept a "before" for: cheap, an upper bound on the list. */
+export async function fetchSessionChangeCount(projectName: string, sessionId: string, signal?: AbortSignal): Promise<number> {
+  const res = await api.get<{ count?: number }>(`${changesUrl(projectName, sessionId)}/count`, { signal });
+  return typeof res?.count === "number" ? res.count : 0;
+}
+
 export function fetchSessionFileDiff(
   projectName: string,
   sessionId: string,

package/src/web/lib/session-file-changes.ts

@@ -58,6 +58,19 @@ export function withReviewed(files: SessionFileChange[], paths: ReadonlySet<stri
   });
 }
 
+/**
+ * `files` with the rows the server pushed after the agent changed them: each replaces its file's
+ * row, a file not listed yet goes last (it is the newest), and the `gone` ones drop out.
+ */
+export function withPushedChanges(files: SessionFileChange[], pushed: SessionFileChange[], gone: readonly string[]): SessionFileChange[] {
+  const byPath = new Map(pushed.map((f) => [f.path, f]));
+  const drop = new Set(gone);
+  const out = files.filter((f) => !drop.has(f.path)).map((f) => byPath.get(f.path) ?? f);
+  const listed = new Set(files.map((f) => f.path));
+  for (const f of pushed) if (!listed.has(f.path)) out.push(f);
+  return out;
+}
+
 /**
  * Changes whenever what a diff of this file would show does: every write moves the version,
  * the baseline kind moves when a fallback to git HEAD turns into the session's own copy, and

package/src/web/lib/tab-tool-call.ts

@@ -1,5 +1,6 @@
 import {
-  CLAUDE_TAB_TOOLS_MCP_SERVER, CODEX_TAB_TOOLS_MCP_SERVER, MAX_TAB_LINE, OPEN_FILE_TOOL, OPEN_PREVIEW_TOOL, type TabTool,
+  CLAUDE_TAB_TOOLS_MCP_SERVER, CODEX_TAB_TOOLS_MCP_SERVER, MAX_TAB_LINE, OPEN_FILE_TOOL, OPEN_PREVIEW_TOOL, OPEN_URL_TOOL,
+  READ_TERMINAL_TOOL, RUN_IN_TERMINAL_TOOL, type TabTool,
 } from "../../shared/tab-open-protocol";
 import { isImagePlaceholderText } from "../../shared/tool-result-content";
 
@@ -23,6 +24,16 @@ const TOOL_NAME = new RegExp(
   `^(?:mcp__${CLAUDE_TAB_TOOLS_MCP_SERVER}__|${CODEX_TAB_TOOLS_MCP_SERVER}:)(${OPEN_FILE_TOOL}|${OPEN_PREVIEW_TOOL})$`,
 );
 
+/** The tab server's other tools, which take no file: their calls show in the generic card. */
+export type DeviceToolCall =
+  | { tool: typeof OPEN_URL_TOOL; url: string }
+  | { tool: typeof READ_TERMINAL_TOOL; terminal?: string; lines?: number }
+  | { tool: typeof RUN_IN_TERMINAL_TOOL; command: string; cwd?: string };
+
+const DEVICE_TOOL_NAME = new RegExp(
+  `^(?:mcp__${CLAUDE_TAB_TOOLS_MCP_SERVER}__|${CODEX_TAB_TOOLS_MCP_SERVER}:)(${OPEN_URL_TOOL}|${READ_TERMINAL_TOOL}|${RUN_IN_TERMINAL_TOOL})$`,
+);
+
 /** How Codex's events label an image block of a result (`mcpResultText`). */
 const CODEX_IMAGE_LABEL = /^\[image(?: [^\]\s]+)?\]$/;
 
@@ -39,6 +50,31 @@ export function tabToolCall(toolName: string, input: unknown): TabToolCall | nul
   return { tool, path: args.path, ...(validLine ? { line } : {}) };
 }
 
+/** The `open_url` / `read_terminal` / `run_in_terminal` tool a tool name is, under either provider's name, or null. */
+export function deviceToolOf(toolName: string): DeviceToolCall["tool"] | null {
+  return (DEVICE_TOOL_NAME.exec(toolName)?.[1] as DeviceToolCall["tool"] | undefined) ?? null;
+}
+
+/** The `open_url` / `read_terminal` / `run_in_terminal` call an event is, under either provider's name, or null. */
+export function deviceToolCall(toolName: string, input: unknown): DeviceToolCall | null {
+  const tool = deviceToolOf(toolName);
+  if (!tool || !isObj(input)) return null;
+  const args = "arguments" in input && isObj(input.arguments) ? input.arguments : input;
+  const text = (v: unknown): string | undefined => (typeof v === "string" && v.trim() ? v : undefined);
+  if (tool === OPEN_URL_TOOL) {
+    const url = text(args.url);
+    return url ? { tool, url } : null;
+  }
+  if (tool === RUN_IN_TERMINAL_TOOL) {
+    const command = text(args.command);
+    const cwd = text(args.cwd);
+    return command ? { tool, command, ...(cwd ? { cwd } : {}) } : null;
+  }
+  const terminal = text(args.terminal);
+  const lines = typeof args.lines === "number" && Number.isInteger(args.lines) && args.lines > 0 ? args.lines : undefined;
+  return { tool: READ_TERMINAL_TOOL, ...(terminal ? { terminal } : {}), ...(lines ? { lines } : {}) };
+}
+
 /** A tool result's text as the AI read it, without the stand-in for the screenshot. */
 export function tabToolResultText(output: string): string {
   const plain = () => output.split("\n").filter((line) => !CODEX_IMAGE_LABEL.test(line)).join("\n").trimEnd();

package/src/web/lib/utils.ts

@@ -10,7 +10,10 @@ export function basename(filePath: string): string {
   return filePath.split(/[/\\]/).pop() ?? filePath;
 }
 
-/** crypto.randomUUID() fallback for non-secure contexts (HTTP) */
+/**
+ * A short random id: 8 characters, not a UUID. Works on plain HTTP, where `crypto.randomUUID`
+ * does not exist; `uuidV4()` in `device-id.ts` makes a real one.
+ */
 export function randomId(): string {
   if (typeof crypto !== "undefined" && crypto.randomUUID) {
     return crypto.randomUUID().slice(0, 8);

package/src/web/stores/panel-store.ts

@@ -26,6 +26,7 @@ import {
   hydrateWindowPanels,
   stripProjectFromWindowPanels,
   syncWindowPanel,
+  type PopOutOptions,
 } from "./window-panel-actions";
 import { saveWindowPanels } from "./window-panel-persistence";
 import { useWindowStore } from "@/components/floating-window/window-store";
@@ -188,7 +189,7 @@ export interface PanelStore {
    * request is rejected (mobile, a tab type that cannot detach, or the window cap),
    * in which case nothing changed and the caller reports it.
    */
-  popOutTab: (tabId: string, fromPanelId: string) => string | null;
+  popOutTab: (tabId: string, fromPanelId: string, options?: PopOutOptions) => string | null;
   /** Send a window's tabs back to the grid and drop its panel. Runs on window close. */
   redockFromWindow: (windowId: string, originPanelId?: string | null) => void;
 
@@ -197,6 +198,15 @@ export interface PanelStore {
   isMobile: () => boolean;
 }
 
+/**
+ * A tab found already open inside a floating window is only "focused" if that window comes
+ * forward, out of the dock if need be — a minimized window is not on screen at all.
+ */
+function raiseWindowOf(panelId: string): void {
+  const windowId = windowIdFromPanelId(panelId);
+  if (windowId) useWindowStore.getState().focus(windowId);
+}
+
 function defaultLayout(): { panels: Record<string, Panel>; grid: string[][]; focusedPanelId: string } {
   const panel = createPanel();
   // Dock panel is seeded into panels but deliberately absent from grid —
@@ -584,6 +594,7 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
                 [p.id]: { ...p, tabs: stampActive(p.tabs, existing.id), activeTabId: existing.id, tabHistory: pushHistory(p.tabHistory, existing.id) },
               },
             }));
+            raiseWindowOf(p.id);
             persist();
             return existing.id;
           }
@@ -607,6 +618,7 @@ export const usePanelStore = create<PanelStore>()((set, get) => {
                 [p.id]: { ...p, tabs: stampActive(p.tabs, existing.id), activeTabId: existing.id, tabHistory: pushHistory(p.tabHistory, existing.id) },
               },
             }));
+            raiseWindowOf(p.id);
             persist();
             return existing.id;
           }

package/src/web/stores/panel-utils.ts

@@ -42,12 +42,17 @@ export const DOCK_ALLOWED_TAB_TYPES = new Set<TabType>(["terminal", "system-moni
  * Single source for both enforcement points: the action that performs the detach, and the
  * context-menu item that offers it. Split across two files, adding a window kind meant
  * remembering both, and one of them was always the one that got forgotten.
+ */
+export const NON_POPPABLE_TAB_TYPES = new Set<TabType>(["system-monitor", "settings", "problems", "logs"]);
+
+/**
+ * Tab types that may float in a window but never move into picture-in-picture.
  *
- * `design` is here for a different reason: its canvas accepts bridge messages only from an
- * iframe whose parent is the main window, and a pop-out would make the iframe's parent the
- * picture-in-picture window instead.
+ * A design canvas accepts bridge messages only from an iframe whose parent is the main
+ * window. A floating window keeps it in the main document; picture-in-picture would make the
+ * iframe's parent the PiP window instead.
  */
-export const NON_POPPABLE_TAB_TYPES = new Set<TabType>(["system-monitor", "settings", "problems", "design", "logs"]);
+export const NON_PIP_TAB_TYPES = new Set<TabType>(["design"]);
 
 /**
  * Prefix of the reserved panel IDs that host tabs detached into a floating window.

package/src/web/stores/settings-store.ts

@@ -45,6 +45,11 @@ interface SettingsState {
   gitStatusViewMode: GitStatusViewMode;
   /** GitLens-style annotation after the cursor's line in the code editor. */
   inlineBlame: boolean;
+  /**
+   * Open a design in a floating window rather than a tab (desktop only; a phone always shows
+   * it full screen). On by default.
+   */
+  designWindows: boolean;
   wordWrap: boolean;
   /** Word wrap on a phone-sized viewport. Device-local — see `persistDevicePref`. */
   mobileWordWrap: boolean;
@@ -175,6 +180,7 @@ interface SettingsState {
   setSidebarWidth: (width: number) => void;
   setGitStatusViewMode: (mode: GitStatusViewMode) => void;
   toggleInlineBlame: () => void;
+  setDesignWindows: (enabled: boolean) => void;
   toggleWordWrap: () => void;
   toggleMobileWordWrap: () => void;
   setLspEnabled: (enabled: boolean) => void;
@@ -215,6 +221,7 @@ interface PersistedSettings {
   sidebarWidth?: number;
   gitStatusViewMode?: GitStatusViewMode;
   inlineBlame?: boolean;
+  designWindows?: boolean;
   wordWrap?: boolean;
   mobileWordWrap?: boolean;
   lspEnabled?: boolean;
@@ -381,6 +388,7 @@ function applyServerUiPrefs(data: Record<string, unknown>) {
   const patch: Partial<PersistedSettings> = {};
   if (typeof data.wordWrap === "boolean") patch.wordWrap = data.wordWrap;
   if (typeof data.inlineBlame === "boolean") patch.inlineBlame = data.inlineBlame;
+  if (typeof data.designWindows === "boolean") patch.designWindows = data.designWindows;
   if (typeof data.tabWrap === "boolean") patch.tabWrap = data.tabWrap;
   if (typeof data.sidebarCollapsed === "boolean") patch.sidebarCollapsed = data.sidebarCollapsed;
   if (typeof data.sidebarWidth === "number" && data.sidebarWidth >= 200 && data.sidebarWidth <= 600) {
@@ -427,6 +435,7 @@ export const useSettingsStore = create<SettingsState>((set, get) => ({
   sidebarWidth: _initial.sidebarWidth ?? 280,
   gitStatusViewMode: _initial.gitStatusViewMode === "tree" ? "tree" : "flat",
   inlineBlame: _initial.inlineBlame ?? false,
+  designWindows: _initial.designWindows ?? true,
   wordWrap: _initial.wordWrap ?? false,
   remoteDesktopQuality: parseQualityChoice(_initial.remoteDesktopQuality),
   remoteDesktopViewStyle: parseViewStyle(_initial.remoteDesktopViewStyle),
@@ -572,6 +581,11 @@ export const useSettingsStore = create<SettingsState>((set, get) => ({
     set({ inlineBlame: next });
   },
 
+  setDesignWindows: (enabled) => {
+    persistUiPref({ designWindows: enabled });
+    set({ designWindows: enabled });
+  },
+
   toggleWordWrap: () => {
     const next = !get().wordWrap;
     persistUiPref({ wordWrap: next });

package/src/web/stores/window-panel-actions.ts

@@ -23,7 +23,7 @@ import {
 import { persistDock } from "./dock-actions";
 import { loadWindowPanels, saveWindowPanels } from "./window-panel-persistence";
 import { useWindowStore } from "@/components/floating-window/window-store";
-import { MAX_WINDOWS } from "@/components/floating-window/window-geometry";
+import { MAX_WINDOWS, type Rect } from "@/components/floating-window/window-geometry";
 import type { PanelStore } from "./panel-store";
 
 type Set = StoreApi<PanelStore>["setState"];
@@ -89,12 +89,22 @@ export function hydrateWindowPanels(set: Set, get: Get): void {
   set({ panels: { ...loaded, ...get().panels } });
 }
 
+export interface PopOutOptions {
+  /**
+   * The window is the tab's home rather than a detour: closing it closes the tab instead of
+   * handing it back to the grid (a design opened from the sidebar; see `closeWindow`).
+   */
+  closeTabsOnClose?: boolean;
+  /** Where the window opens; a cascaded default otherwise. */
+  rect?: Rect;
+}
+
 /**
  * Detach a tab into a new floating window. Returns the window id, or null when the
  * request is rejected — in which case nothing is mutated and the caller reports it.
  */
 export function makePopOutTab(set: Set, get: Get) {
-  return function popOutTab(tabId: string, fromPanelId: string): string | null {
+  return function popOutTab(tabId: string, fromPanelId: string, options: PopOutOptions = {}): string | null {
     // The window layer is desktop-only; on mobile a detached tab would be invisible.
     if (get().isMobile()) return null;
 
@@ -107,7 +117,15 @@ export function makePopOutTab(set: Set, get: Get) {
     const windowStore = useWindowStore.getState();
     if (Object.keys(windowStore.windows).length >= MAX_WINDOWS) return null;
 
-    const windowId = windowStore.open("tab-host", { originPanelId: fromPanelId, title: tab.title });
+    const windowId = windowStore.open(
+      "tab-host",
+      {
+        originPanelId: fromPanelId,
+        title: tab.title,
+        ...(options.closeTabsOnClose ? { closeTabsOnClose: true } : {}),
+      },
+      options.rect,
+    );
     const panelId = windowPanelId(windowId);
     set((s) => ({ panels: { ...s.panels, [panelId]: createWindowPanel(windowId) } }));
 

package/src/web/stores/window-panel-persistence.ts

@@ -49,7 +49,8 @@ const POPPABLE_TAB_TYPES: Record<TabType, boolean> = {
   "ai-resource": true,
   group: true,
   problems: false,
-  design: false,
+  // A design opens in a window on a desktop, and comes back in one after a reload.
+  design: true,
   // A viewer in a floating window is an ordinary tab move: `ReparentingTab` keeps one mount,
   // so it is still one WS session and one controller lease.
   android: true,

package/src/web/sw-notification-click.ts

@@ -5,6 +5,7 @@
 import { OPEN_FROM_NOTIFICATION, type OpenFromNotificationMessage, type WebPushPayload } from "../shared/web-push-payload";
 
 export interface NotificationWindow {
+  url: string;
   focused: boolean;
   visibilityState: DocumentVisibilityState;
   postMessage(message: unknown): void;
@@ -30,7 +31,9 @@ export async function routeNotificationClick(
   // A notification can name another origin: a device that subscribed on an old quick
   // tunnel is sent the current one. A window here cannot show that.
   if (target.origin === workerOrigin) {
-    const windows = await clients.matchAll({ type: "window", includeUncontrolled: true });
+    // A reviewer page (`/s/<code>`) opened on this origin is not the app and has no one
+    // listening, so a click handed to it would be lost.
+    const windows = (await clients.matchAll({ type: "window", includeUncontrolled: true })).filter((c) => !isSharePage(c.url));
     const client = windows.find((c) => c.focused)
       ?? windows.find((c) => c.visibilityState === "visible")
       ?? windows[0];
@@ -49,3 +52,11 @@ export async function routeNotificationClick(
   }
   await clients.openWindow(target.href);
 }
+
+function isSharePage(url: string): boolean {
+  try {
+    return new URL(url).pathname.startsWith("/s/");
+  } catch {
+    return false;
+  }
+}

package/templates/skill/SKILL.md.tmpl

@@ -36,7 +36,7 @@ Invoke when the user asks to:
 3. **List projects** → `ppm projects list`
 4. **Add project** → `ppm projects add <path>`
 5. **List DB connections** → `PPM_AI_CHAT=1 ppm db list`
-6. **Query a saved DB connection** → `PPM_AI_CHAT=1 ppm db query <connection-name> "<sql>"`
+6. **Read or change data in a saved connection** → the `db_query` / `db_execute` tools, not this CLI (see Rules of Thumb)
 7. **Read config** → `ppm config get <key>` (e.g. `port`, `auth.enabled`)
 8. **Tail logs** → `ppm logs --tail 100` or `ppm logs -f` to follow
 9. **Upgrade PPM** → `ppm upgrade` (or `--check` to only check)
@@ -47,6 +47,7 @@ Invoke when the user asks to:
 - Always run `ppm status` before assuming the server is up.
 - Commands exit non-zero on failure and print to stderr. Capture both streams.
 - Set `PPM_AI_CHAT=1` for every `ppm db` command, as above: connections the user has made unavailable to AI are then left out of `db list` and refused by the rest. PPM's own chat sets it already.
+- Inside a PPM chat, `db tables/schema/data/query/run` do **not** run — they refuse and name the tool that serves them (`db_query`, `db_execute`). Those tools are what the user can switch off per tool in Settings → Tools, and a write through `db_execute` waits for the user to approve it; the CLI obeys neither, so it is for a person at a terminal. The connection commands (`list`, `add`, `test`, `remove`, `driver`) are unaffected.
 - Most listing commands accept `--json` for structured output; prefer JSON when parsing. Check `--help` if unsure.
 - The config DB is **SQLite**. You may open `~/.ppm/ppm.db` read-only for inspection — see [references/db-schema.md](references/db-schema.md).
 - Do NOT edit the config DB directly while the server is running; use `ppm config set` or the HTTP API.

package/templates/skill/common-tasks.md

@@ -52,6 +52,12 @@ ppm db test staging
 
 ## Task 5: Query a saved DB connection
 
+Inside a PPM chat, use the `db_query` tool (and `db_execute` for a change, which the user
+approves). `ppm db query` refuses there and names the tool, because the CLI obeys neither the
+per-tool switch in Settings → Tools nor the approval.
+
+For a person at a terminal:
+
 ```bash
 # Run a SQL query against a registered connection
 ppm db query staging "SELECT count(*) AS total FROM users"

package/vite.config.ts

@@ -110,6 +110,16 @@ export default defineConfig({
         target: process.env.PPM_DEV_API ?? "http://localhost:8081",
         ws: true,
       },
+      // A design share link's reviewer page and its built assets (`vite.share.config.ts`),
+      // so "Open as reviewer" works from the dev server too, once `build:web` has run.
+      "/s/": {
+        target: process.env.PPM_DEV_API ?? "http://localhost:8081",
+        changeOrigin: false,
+      },
+      "/assets/share-": {
+        target: process.env.PPM_DEV_API ?? "http://localhost:8081",
+        changeOrigin: false,
+      },
     },
     fs: {
       // A git worktree's `node_modules` is often a junction back to the main checkout's (to