@hienlh/ppm 0.13.52 → 0.13.54

package/src/cli/commands/db-cmd.ts

@@ -67,14 +67,26 @@ export function registerDbCommands(program: Command): void {
   // ── ppm db list ──────────────────────────────────────────────────────
   db.command("list")
     .description("List all saved database connections")
-    .action(async () => {
+    .option("--json", "Output as JSON")
+    .action(async (options: { json?: boolean }) => {
       try {
         const { getConnections } = await import("../../services/db.service.ts");
         const conns = getConnections();
         if (conns.length === 0) {
+          if (options.json) { console.log("[]"); return; }
           console.log(`${C.yellow}No connections saved.${C.reset} Run: ppm db add`);
           return;
         }
+        if (options.json) {
+          const data = conns.map((c) => {
+            const cfg = parseConfig(c);
+            let target = cfg.connectionString ?? cfg.path ?? null;
+            if (cfg.connectionString) target = maskPassword(target!);
+            return { id: c.id, name: c.name, type: c.type, group: c.group_name ?? null, readonly: !!c.readonly, connection: target };
+          });
+          console.log(JSON.stringify(data, null, 2));
+          return;
+        }
         const rows = conns.map((c) => {
           const cfg = parseConfig(c);
           let target = cfg.connectionString ?? cfg.path ?? "-";
@@ -197,7 +209,8 @@ export function registerDbCommands(program: Command): void {
   // ── ppm db tables ────────────────────────────────────────────────────
   db.command("tables <name>")
     .description("List tables in a database connection")
-    .action(async (nameOrId: string) => {
+    .option("--json", "Output as JSON")
+    .action(async (nameOrId: string, options: { json?: boolean }) => {
       try {
         const { resolveConnection } = await import("../../services/db.service.ts");
         const conn = resolveConnection(nameOrId);
@@ -212,9 +225,11 @@ export function registerDbCommands(program: Command): void {
           const tables = await postgresService.getTables(cfg.connectionString!);
           await postgresService.closeAll();
           if (tables.length === 0) {
+            if (options.json) { console.log("[]"); return; }
             console.log(`${C.dim}No tables found.${C.reset}`);
             return;
           }
+          if (options.json) { console.log(JSON.stringify(tables, null, 2)); return; }
           printTable(
             ["Schema", "Table", "Rows (est.)"],
             tables.map((t) => [t.schema, t.name, String(t.rowCount)]),
@@ -224,9 +239,11 @@ export function registerDbCommands(program: Command): void {
           const tables = sqliteService.getTables(cfg.path!, cfg.path!);
           sqliteService.closeAll();
           if (tables.length === 0) {
+            if (options.json) { console.log("[]"); return; }
             console.log(`${C.dim}No tables found.${C.reset}`);
             return;
           }
+          if (options.json) { console.log(JSON.stringify(tables, null, 2)); return; }
           printTable(
             ["Table", "Rows"],
             tables.map((t) => [t.name, String(t.rowCount)]),
@@ -242,7 +259,8 @@ export function registerDbCommands(program: Command): void {
   db.command("schema <name> <table>")
     .description("Show table schema (columns, types, constraints)")
     .option("-s, --schema <schema>", "PostgreSQL schema name", "public")
-    .action(async (nameOrId: string, table: string, options: { schema: string }) => {
+    .option("--json", "Output as JSON")
+    .action(async (nameOrId: string, table: string, options: { schema: string; json?: boolean }) => {
       try {
         const { resolveConnection } = await import("../../services/db.service.ts");
         const conn = resolveConnection(nameOrId);
@@ -256,6 +274,7 @@ export function registerDbCommands(program: Command): void {
           const { postgresService } = await import("../../services/postgres.service.ts");
           const cols = await postgresService.getTableSchema(cfg.connectionString!, table, options.schema);
           await postgresService.closeAll();
+          if (options.json) { console.log(JSON.stringify(cols, null, 2)); return; }
           printTable(
             ["Column", "Type", "Nullable", "PK", "Default"],
             cols.map((c) => [c.name, c.type, c.nullable ? "YES" : "NO", c.pk ? "PK" : "", c.defaultValue ?? ""]),
@@ -264,6 +283,7 @@ export function registerDbCommands(program: Command): void {
           const { sqliteService } = await import("../../services/sqlite.service.ts");
           const cols = sqliteService.getTableSchema(cfg.path!, cfg.path!, table);
           sqliteService.closeAll();
+          if (options.json) { console.log(JSON.stringify(cols, null, 2)); return; }
           printTable(
             ["Column", "Type", "Not Null", "PK", "Default"],
             cols.map((c) => [c.name, c.type, c.notnull ? "YES" : "NO", c.pk ? "PK" : "", c.dflt_value ?? ""]),
@@ -283,6 +303,7 @@ export function registerDbCommands(program: Command): void {
     .option("--order <column>", "Order by column")
     .option("--desc", "Descending order")
     .option("-s, --schema <schema>", "PostgreSQL schema name", "public")
+    .option("--json", "Output as JSON")
     .action(async (nameOrId: string, table: string, options) => {
       try {
         const { resolveConnection } = await import("../../services/db.service.ts");
@@ -302,6 +323,7 @@ export function registerDbCommands(program: Command): void {
             cfg.connectionString!, table, options.schema, page, limit, options.order, orderDir,
           );
           await postgresService.closeAll();
+          if (options.json) { console.log(JSON.stringify(result, null, 2)); return; }
           console.log(`${C.cyan}${table}${C.reset} — page ${result.page}, ${result.total} total rows\n`);
           formatRows(result.columns, result.rows, limit);
         } else {
@@ -310,6 +332,7 @@ export function registerDbCommands(program: Command): void {
             cfg.path!, cfg.path!, table, page, limit, options.order, orderDir,
           );
           sqliteService.closeAll();
+          if (options.json) { console.log(JSON.stringify(result, null, 2)); return; }
           console.log(`${C.cyan}${table}${C.reset} — page ${result.page}, ${result.total} total rows\n`);
           formatRows(result.columns, result.rows, limit);
         }
@@ -322,7 +345,8 @@ export function registerDbCommands(program: Command): void {
   // ── ppm db query ─────────────────────────────────────────────────────
   db.command("query <name> <sql>")
     .description("Execute a SQL query against a saved connection")
-    .action(async (nameOrId: string, sql: string) => {
+    .option("--json", "Output as JSON")
+    .action(async (nameOrId: string, sql: string, options: { json?: boolean }) => {
       try {
         const { resolveConnection } = await import("../../services/db.service.ts");
         const conn = resolveConnection(nameOrId);
@@ -343,6 +367,7 @@ export function registerDbCommands(program: Command): void {
           const { postgresService } = await import("../../services/postgres.service.ts");
           const result = await postgresService.executeQuery(cfg.connectionString!, sql);
           await postgresService.closeAll();
+          if (options.json) { console.log(JSON.stringify(result, null, 2)); return; }
           if (result.changeType === "select") {
             formatRows(result.columns, result.rows);
           } else {
@@ -352,6 +377,7 @@ export function registerDbCommands(program: Command): void {
           const { sqliteService } = await import("../../services/sqlite.service.ts");
           const result = sqliteService.executeQuery(cfg.path!, cfg.path!, sql);
           sqliteService.closeAll();
+          if (options.json) { console.log(JSON.stringify(result, null, 2)); return; }
           if (result.changeType === "select") {
             formatRows(result.columns, result.rows);
           } else {

package/src/server/routes/chat.ts

@@ -3,6 +3,7 @@ import { resolve, join, basename } from "node:path";
 import { mkdirSync, existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { chatService } from "../../services/chat.service.ts";
+import { draftService } from "../../services/draft.service.ts";
 import { providerRegistry } from "../../providers/registry.ts";
 import { renameSession as sdkRenameSession } from "@anthropic-ai/claude-agent-sdk";
 import { listSlashItems, searchSlashItems, invalidateCache } from "../../services/slash-items.service.ts";
@@ -221,9 +222,12 @@ chatRoutes.delete("/sessions", async (c) => {
         deleteSessionMetadata(s.id);
         deleteSessionTitle(s.id);
         unpinSession(s.id);
+        try { draftService.delete(projectPath, s.id); } catch { /* ignore */ }
         deleted++;
       } catch { /* skip individual failures */ }
     }
+    // Clean up any orphaned drafts left behind
+    try { draftService.deleteOrphaned(); } catch { /* ignore */ }
 
     return c.json(ok({ deleted, total: toDelete.length }));
   } catch (e) {
@@ -244,6 +248,8 @@ chatRoutes.delete("/sessions/:id", async (c) => {
     deleteSessionMetadata(id);
     deleteSessionTitle(id);
     unpinSession(id);
+    // Fire-and-forget draft cleanup
+    try { draftService.delete(c.get("projectPath"), id); } catch { /* ignore */ }
     return c.json(ok({ deleted: id }));
   } catch (e) {
     return c.json(err((e as Error).message), 404);
@@ -516,3 +522,46 @@ chatRoutes.get("/uploads/:filename", async (c) => {
     return c.json(err((e as Error).message), 500);
   }
 });
+
+// ---------------------------------------------------------------------------
+// Draft endpoints — auto-save / restore chat input per session
+// ---------------------------------------------------------------------------
+
+/** GET /chat/drafts/:sessionId — load draft for a session (or null) */
+chatRoutes.get("/drafts/:sessionId", (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const sessionId = c.req.param("sessionId");
+    const draft = draftService.get(projectPath, sessionId);
+    return c.json(ok(draft));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** PUT /chat/drafts/:sessionId — upsert draft content + attachments */
+chatRoutes.put("/drafts/:sessionId", async (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const sessionId = c.req.param("sessionId");
+    const body = await c.req.json<{ content?: string; attachments?: string }>();
+    const content = typeof body.content === "string" ? body.content : "";
+    const attachments = typeof body.attachments === "string" ? body.attachments : undefined;
+    draftService.upsert(projectPath, sessionId, content, attachments);
+    return c.json(ok({ saved: true }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/** DELETE /chat/drafts/:sessionId — remove draft */
+chatRoutes.delete("/drafts/:sessionId", (c) => {
+  try {
+    const projectPath = c.get("projectPath");
+    const sessionId = c.req.param("sessionId");
+    draftService.delete(projectPath, sessionId);
+    return c.json(ok({ deleted: true }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});

package/src/services/db.service.ts

@@ -3,7 +3,7 @@ import { resolve } from "node:path";
 import { mkdirSync, existsSync } from "node:fs";
 import { encrypt, decrypt } from "../lib/account-crypto.ts";
 import { getPpmDir } from "./ppm-dir.ts";
-const CURRENT_SCHEMA_VERSION = 21;
+const CURRENT_SCHEMA_VERSION = 26;
 
 let db: Database | null = null;
 let dbProfile: string | null = null;
@@ -638,6 +638,21 @@ function runMigrations(database: Database): void {
       PRAGMA user_version = 25;
     `);
   }
+
+  if (current < 26) {
+    database.exec(`
+      CREATE TABLE IF NOT EXISTS chat_drafts (
+        project_path TEXT NOT NULL,
+        session_id TEXT NOT NULL DEFAULT '__new__',
+        content TEXT NOT NULL DEFAULT '',
+        attachments TEXT DEFAULT '[]',
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (project_path, session_id)
+      );
+
+      PRAGMA user_version = 26;
+    `);
+  }
 }
 
 // ---------------------------------------------------------------------------

package/src/services/draft.service.ts

@@ -0,0 +1,49 @@
+import { getDb } from "./db.service.ts";
+
+const MAX_CONTENT_LENGTH = 50 * 1024; // ~50K characters cap
+
+export interface DraftData {
+  content: string;
+  attachments: string; // JSON string
+  updatedAt: string;
+}
+
+class DraftService {
+  get(projectPath: string, sessionId: string): DraftData | null {
+    const row = getDb()
+      .query("SELECT content, attachments, updated_at FROM chat_drafts WHERE project_path = ? AND session_id = ?")
+      .get(projectPath, sessionId) as { content: string; attachments: string; updated_at: string } | null;
+    if (!row) return null;
+    return { content: row.content, attachments: row.attachments, updatedAt: row.updated_at };
+  }
+
+  upsert(projectPath: string, sessionId: string, content: string, attachments?: string): void {
+    // Silent truncation at 50KB
+    const safeContent = content.length > MAX_CONTENT_LENGTH ? content.slice(0, MAX_CONTENT_LENGTH) : content;
+    getDb()
+      .query(
+        "INSERT INTO chat_drafts (project_path, session_id, content, attachments, updated_at) VALUES (?, ?, ?, ?, datetime('now')) ON CONFLICT(project_path, session_id) DO UPDATE SET content = excluded.content, attachments = excluded.attachments, updated_at = excluded.updated_at",
+      )
+      .run(projectPath, sessionId, safeContent, attachments ?? "[]");
+  }
+
+  delete(projectPath: string, sessionId: string): void {
+    getDb()
+      .query("DELETE FROM chat_drafts WHERE project_path = ? AND session_id = ?")
+      .run(projectPath, sessionId);
+  }
+
+  /** Delete orphaned drafts whose session_id is not in session_metadata */
+  deleteOrphaned(): number {
+    const result = getDb()
+      .query(
+        `DELETE FROM chat_drafts
+         WHERE session_id != '__new__'
+           AND session_id NOT IN (SELECT session_id FROM session_metadata)`,
+      )
+      .run();
+    return (result as { changes: number }).changes;
+  }
+}
+
+export const draftService = new DraftService();

package/src/services/ppmbot/cli-reference-default.ts

@@ -161,6 +161,7 @@ ppm chat delete <session-id>
 \`\`\`
 ppm db list
   List all saved database connections
+  --json — Output as JSON
 
 ppm db add
   Add a new database connection
@@ -179,10 +180,12 @@ ppm db test <name>
 
 ppm db tables <name>
   List tables in a database connection
+  --json — Output as JSON
 
 ppm db schema <name> <table>
   Show table schema (columns, types, constraints)
   -s, --schema <schema> — PostgreSQL schema name [default: public]
+  --json — Output as JSON
 
 ppm db data <name> <table>
   View table data (paginated)
@@ -191,9 +194,11 @@ ppm db data <name> <table>
   --order <column> — Order by column
   --desc — Descending order
   -s, --schema <schema> — PostgreSQL schema name [default: public]
+  --json — Output as JSON
 
 ppm db query <name> <sql>
   Execute a SQL query against a saved connection
+  --json — Output as JSON
 \`\`\`
 ## ppm autostart — Auto-start on boot
 \`\`\`
@@ -322,6 +327,6 @@ ppm bot memory forget "<topic>"
 \`\`\`
 
 ## Tips
-- Use \`--json\` flag when parsing command output programmatically
+- Use \`--json\` flag when parsing command output programmatically (available on most list/status commands — check \`--help\`)
 - For git/chat/db operations: always specify \`--project <name>\` or connection name
 `;

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

@@ -14,6 +14,7 @@ import { MessageInput, type ChatAttachment, type MessagePriority } from "./messa
 import { SlashCommandPicker, type SlashItem } from "./slash-command-picker";
 import { FilePicker } from "./file-picker";
 import { ChatHistoryBar } from "./chat-history-bar";
+import { useDraft, type DraftAttachment } from "@/hooks/use-draft";
 
 import type { DragEvent } from "react";
 import type { FileNode } from "../../../types/project";
@@ -69,6 +70,9 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
   const { usageInfo, usageLoading, lastFetchedAt, refreshUsage } =
     useUsage(projectName, providerId);
 
+  // Draft auto-save/restore
+  const { draft, draftLoading, saveDraft, clearDraft } = useDraft(projectName, sessionId);
+
   // Load global default permission mode on mount (if no per-session override)
   useEffect(() => {
     if (permissionMode) return;
@@ -258,13 +262,22 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
     [sessionId, providerId, projectName, sendMessage, buildMessageWithAttachments, permissionMode],
   );
 
-  /** Stable wrapper for MessageInput onSend — clears forkDraft and delegates to handleSend */
+  /** Stable wrapper for MessageInput onSend — clears forkDraft + draft and delegates to handleSend */
   const handleInputSend = useCallback(
     (content: string, attachments: ChatAttachment[], priority?: MessagePriority) => {
       setForkDraft(undefined);
+      clearDraft();
       handleSend(content, attachments, priority);
     },
-    [handleSend],
+    [handleSend, clearDraft],
+  );
+
+  /** Draft auto-save callback — called by MessageInput on content change */
+  const handleContentChange = useCallback(
+    (content: string, attachments?: DraftAttachment[]) => {
+      saveDraft(content, attachments);
+    },
+    [saveDraft],
   );
 
   /** Stable callback for slash items loaded — prevents MessageInput memo break */
@@ -469,29 +482,32 @@ export function ChatTab({ metadata, tabId }: ChatTabProps) {
           />
         )}
 
-        {/* Input */}
-        <MessageInput
-          onSend={handleInputSend}
-          isStreaming={isStreaming}
-          onCancel={cancelStreaming}
-          autoFocus={!(metadata?.sessionId) || !!forkDraft}
-          initialValue={forkDraft}
-          projectName={projectName}
-          onSlashStateChange={handleSlashStateChange}
-          onSlashItemsLoaded={handleSlashItemsLoaded}
-          slashSelected={slashSelected}
-          onFileStateChange={handleFileStateChange}
-          onFileItemsLoaded={setFileItems}
-          fileSelected={fileSelected}
-          externalFiles={externalFiles}
-          externalPaths={externalPaths}
-          onExternalPathsConsumed={handleExternalPathsConsumed}
-          onDisambiguate={handleDisambiguate}
-          permissionMode={permissionMode}
-          onModeChange={setPermissionMode}
-          providerId={providerId}
-          onProviderChange={!sessionId ? setProviderId : undefined}
-        />
+        {/* Input — gate on draftLoading to avoid empty→filled flash */}
+        {!draftLoading && (
+          <MessageInput
+            onSend={handleInputSend}
+            isStreaming={isStreaming}
+            onCancel={cancelStreaming}
+            autoFocus={!(metadata?.sessionId) || !!forkDraft}
+            initialValue={forkDraft ?? draft?.content}
+            projectName={projectName}
+            onSlashStateChange={handleSlashStateChange}
+            onSlashItemsLoaded={handleSlashItemsLoaded}
+            slashSelected={slashSelected}
+            onFileStateChange={handleFileStateChange}
+            onFileItemsLoaded={setFileItems}
+            fileSelected={fileSelected}
+            externalFiles={externalFiles}
+            externalPaths={externalPaths}
+            onExternalPathsConsumed={handleExternalPathsConsumed}
+            onDisambiguate={handleDisambiguate}
+            onContentChange={handleContentChange}
+            permissionMode={permissionMode}
+            onModeChange={setPermissionMode}
+            providerId={providerId}
+            onProviderChange={!sessionId ? setProviderId : undefined}
+          />
+        )}
       </div>
 
       {/* Bug report popup is now global — see BugReportPopup in app.tsx */}

package/src/web/components/chat/message-input.tsx

@@ -50,6 +50,8 @@ interface MessageInputProps {
   onDisambiguate?: (matches: FileNode[]) => void;
   /** Pre-fill input value (e.g. from command palette "Ask AI") */
   initialValue?: string;
+  /** Called on content change for draft auto-save */
+  onContentChange?: (content: string, attachments?: Array<{ name: string; path: string }>) => void;
   /** Auto-focus textarea on mount */
   autoFocus?: boolean;
   /** Current permission mode */
@@ -79,6 +81,7 @@ export const MessageInput = memo(function MessageInput({
   onExternalPathsConsumed,
   onDisambiguate,
   initialValue,
+  onContentChange,
   autoFocus,
   permissionMode,
   onModeChange,
@@ -561,6 +564,8 @@ export const MessageInput = memo(function MessageInput({
       setHasText(text.trim().length > 0);
       // Update picker state (slash/file autocomplete)
       updatePickerState(text, el.selectionStart);
+      // Notify parent for draft auto-save (debounced in hook)
+      onContentChange?.(text, attachments.filter((a) => a.status === "ready" && a.serverPath).map((a) => ({ name: a.name, path: a.serverPath! })));
       // JS auto-resize fallback — only when CSS field-sizing: content is unsupported
       if (needsJsResize.current) {
         if (resizeRafRef.current) cancelAnimationFrame(resizeRafRef.current);
@@ -571,7 +576,7 @@ export const MessageInput = memo(function MessageInput({
         });
       }
     },
-    [updatePickerState],
+    [updatePickerState, onContentChange, attachments],
   );
 
   /** Handle paste — intercept images from clipboard */

package/src/web/components/editor/editor-breadcrumb.tsx

@@ -165,7 +165,14 @@ function SegmentDropdown({ segment, isLast, projectName, onFileClick }: SegmentD
 
   function handleOpenChange(open: boolean) {
     if (open && !isLoaded) {
-      loadChildren(projectName, segment.parentPath);
+      // Load ancestor directories top-down so mergeChildren can traverse
+      // the tree to the target (needed when file opened via search/quick-open)
+      const parts = segment.parentPath.split("/").filter(Boolean);
+      (async () => {
+        for (let i = 0; i <= parts.length; i++) {
+          await loadChildren(projectName, parts.slice(0, i).join("/"));
+        }
+      })();
     }
   }
 

package/src/web/hooks/use-draft.ts

@@ -0,0 +1,93 @@
+import { useState, useEffect, useRef, useCallback } from "react";
+import { api, projectUrl } from "@/lib/api-client";
+
+export interface DraftAttachment {
+  name: string;
+  path: string;
+}
+
+interface DraftState {
+  content: string;
+  attachments: DraftAttachment[];
+}
+
+interface DraftResult {
+  content: string;
+  attachments: string; // JSON string
+  updatedAt: string;
+}
+
+export function useDraft(projectName: string, sessionId: string | null) {
+  const [draft, setDraft] = useState<DraftState | null>(null);
+  const [loading, setLoading] = useState(true);
+  const timerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const sessionRef = useRef(sessionId);
+  sessionRef.current = sessionId;
+
+  const effectiveId = sessionId ?? "__new__";
+
+  // Load draft on mount / session change
+  useEffect(() => {
+    if (!projectName) {
+      setLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setLoading(true);
+    api
+      .get<DraftResult | null>(
+        `${projectUrl(projectName)}/chat/drafts/${encodeURIComponent(effectiveId)}`,
+      )
+      .then((data) => {
+        if (cancelled) return;
+        if (data) {
+          let attachments: DraftAttachment[] = [];
+          try { attachments = JSON.parse(data.attachments); } catch { /* ignore */ }
+          setDraft({ content: data.content, attachments });
+        } else {
+          setDraft(null);
+        }
+      })
+      .catch(() => { if (!cancelled) setDraft(null); })
+      .finally(() => { if (!cancelled) setLoading(false); });
+    return () => { cancelled = true; };
+  }, [projectName, effectiveId]);
+
+  // Debounced save (1s)
+  const save = useCallback(
+    (content: string, attachments?: DraftAttachment[]) => {
+      if (!projectName) return;
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => {
+        const id = sessionRef.current ?? "__new__";
+        api
+          .put(
+            `${projectUrl(projectName)}/chat/drafts/${encodeURIComponent(id)}`,
+            { content, attachments: JSON.stringify(attachments ?? []) },
+          )
+          .catch(() => {});
+      }, 1000);
+    },
+    [projectName],
+  );
+
+  // Clear draft (on send)
+  const clear = useCallback(() => {
+    if (!projectName) return;
+    if (timerRef.current) clearTimeout(timerRef.current);
+    const id = sessionRef.current ?? "__new__";
+    api
+      .del(`${projectUrl(projectName)}/chat/drafts/${encodeURIComponent(id)}`)
+      .catch(() => {});
+    setDraft(null);
+  }, [projectName]);
+
+  // Cleanup timer on unmount
+  useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  return { draft, draftLoading: loading, saveDraft: save, clearDraft: clear };
+}

package/src/web/hooks/use-terminal.ts

@@ -195,10 +195,13 @@ export function useTerminal(
         if (event.data.startsWith("{")) {
           try {
             const msg = JSON.parse(event.data);
-            if (msg.type === "session" || msg.type === "error" || msg.type === "exited" || msg.type === "ping") {
+            // Any valid JSON with a "type" field is a control/system message —
+            // real PTY output is raw text/escape sequences, never typed JSON.
+            // Handle known terminal control types, silently drop everything else
+            // (e.g. chat events that may leak via WS under race conditions).
+            if (msg.type) {
               if (msg.type === "session" && msg.id) {
                 actualSessionId.current = msg.id;
-                // Persist to localStorage so reload reconnects to same PTY
                 if (storageKey) {
                   try { localStorage.setItem(storageKey, msg.id); } catch { /* */ }
                 }
@@ -209,7 +212,7 @@ export function useTerminal(
               if (msg.type === "exited") {
                 setExited(true);
               }
-              return; // Don't write raw JSON to terminal
+              return; // Never write typed JSON to terminal
             }
           } catch {
             // Not JSON, write as terminal output

package/templates/skill/SKILL.md.tmpl

@@ -46,7 +46,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.
-- Listing commands accept `--json` for structured output; prefer JSON when parsing.
+- 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.