@hienlh/ppm 0.17.47 → 0.17.49

package/src/services/edge-forwarder.ts

@@ -0,0 +1,191 @@
+/**
+ * Edge forwarder — owns the public port and pipes raw TCP to the server's
+ * current loopback port.
+ *
+ * ─── CRITICAL INVARIANT: THIS PROCESS MUST NEVER SPAWN A CHILD ───
+ *
+ * On Windows a child spawned with fd stdio inherits every inheritable handle,
+ * including a listening socket. When such a descendant is orphaned it keeps the
+ * socket open, so the port stays in LISTEN under a dead PID and can never be
+ * rebound — a "zombie port". The server hits this constantly because it spawns
+ * chat/tool/MCP subprocesses; those inherit its listener and wedge its port.
+ *
+ * The edge exists precisely because it spawns nothing, so its socket cannot be
+ * inherited and its port cannot zombie. cloudflared can therefore stay pinned
+ * to it forever and the public URL stops rotating. Adding any child-process
+ * call to this file reintroduces the exact bug the edge was built to remove.
+ *
+ * Raw TCP, never HTTP: WebSocket upgrades and SSE streams pass through
+ * untouched, and forwarded requests keep the headers cloudflared set.
+ */
+import net from "node:net";
+import { resolveTargetPort, _resetTargetCache } from "./edge-target-resolver.ts";
+
+/** Delay between attempts while waiting for the server to come back. */
+const CONNECT_RETRY_MS = 250;
+/**
+ * How long a client connection waits for a reachable server before giving up.
+ * During an upgrade the server is briefly absent; refusing instantly would
+ * surface as a broken page rather than a slow one.
+ */
+const CONNECT_WINDOW_MS = 5000;
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/** Resolve once the socket is connected; reject on the first connect error. */
+function connectUpstream(port: number): Promise<net.Socket> {
+  return new Promise((resolvePromise, reject) => {
+    const upstream = net.connect({
+      port,
+      host: "127.0.0.1", // never taken from status.json — loopback only
+      allowHalfOpen: true,
+    });
+    const onError = (err: Error) => {
+      upstream.destroy();
+      reject(err);
+    };
+    upstream.once("error", onError);
+    upstream.once("connect", () => {
+      upstream.removeListener("error", onError);
+      resolvePromise(upstream);
+    });
+  });
+}
+
+/**
+ * Largest amount of client data held while waiting for the server. Bounds the
+ * memory a slow upload can pin during an upgrade window.
+ */
+const MAX_PENDING_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Pipe one client connection to the server.
+ *
+ * Resolving the upstream is async, so the first bytes usually arrive before
+ * there is anywhere to send them. They must be captured by a `data` listener
+ * attached synchronously on this very tick and replayed once the upstream
+ * exists.
+ *
+ * `socket.pause()` is NOT a substitute — verified against Bun 1.3.13: bytes
+ * that arrive while paused are lost, and a later `pipe()`/`resume()` does not
+ * bring them back. A socket with no `data` listener drops them outright too.
+ * Both variants silently swallowed the first request in testing.
+ */
+async function handleConnection(
+  client: net.Socket,
+  connectWindowMs: number,
+): Promise<void> {
+  const pending: Buffer[] = [];
+  let pendingBytes = 0;
+  let clientEnded = false;
+  const onEarlyData = (chunk: Buffer) => {
+    pendingBytes += chunk.length;
+    if (pendingBytes > MAX_PENDING_BYTES) {
+      client.destroy();
+      return;
+    }
+    pending.push(chunk);
+  };
+  client.on("data", onEarlyData);
+  client.once("end", () => { clientEnded = true; });
+
+  let upstream: net.Socket | null = null;
+  let clientGone = false;
+
+  // A socket error with no listener is an unhandled 'error' event, which would
+  // take the whole edge process — and the public port — down with it.
+  const teardown = () => {
+    upstream?.destroy();
+    client.destroy();
+  };
+  client.on("error", teardown);
+  client.once("close", () => { clientGone = true; });
+
+  const deadline = Date.now() + connectWindowMs;
+  while (!clientGone && Date.now() < deadline) {
+    const port = resolveTargetPort();
+    if (port !== null) {
+      try {
+        upstream = await connectUpstream(port);
+        break;
+      } catch {
+        // Server not up yet (or moved mid-restart) — re-resolve and retry.
+        _resetTargetCache();
+      }
+    }
+    await sleep(CONNECT_RETRY_MS);
+  }
+
+  if (clientGone) return;
+  if (!upstream) {
+    client.destroy();
+    return;
+  }
+
+  upstream.on("error", teardown);
+
+  // Replay what arrived during the connect, then hand both directions to the
+  // stream machinery. Removing the listener and piping happen in the same tick,
+  // so no chunk can slip through the gap.
+  client.off("data", onEarlyData);
+  for (const chunk of pending) upstream.write(chunk);
+  pending.length = 0;
+
+  client.pipe(upstream);
+  upstream.pipe(client);
+
+  // The client may have half-closed while we were still connecting.
+  if (clientEnded) upstream.end();
+}
+
+export interface EdgeForwarderOptions {
+  publicPort: number;
+  host?: string;
+  /** How long a client waits for a reachable server. Defaults to 5s. */
+  connectWindowMs?: number;
+}
+
+/**
+ * Bind the public port and start forwarding. Resolves once listening so the
+ * caller can fail fast when the port is unavailable.
+ */
+export function startEdgeForwarder(
+  opts: EdgeForwarderOptions,
+): Promise<net.Server> {
+  const host = opts.host ?? "0.0.0.0";
+  const connectWindowMs = opts.connectWindowMs ?? CONNECT_WINDOW_MS;
+  return new Promise((resolvePromise, reject) => {
+    // allowHalfOpen keeps the other direction alive when one side sends FIN —
+    // long-lived chat WS and SSE streams depend on it.
+    const server = net.createServer({ allowHalfOpen: true }, (client) => {
+      void handleConnection(client, connectWindowMs);
+    });
+    server.once("error", reject);
+    server.listen(opts.publicPort, host, () => {
+      server.removeListener("error", reject);
+      resolvePromise(server);
+    });
+  });
+}
+
+// ─── Process entry ─────────────────────────────────────────────────────
+// Mirrors the `__serve__` guard in src/server/index.ts: the supervisor
+// re-invokes the binary as `<bin> __edge__ <publicPort> <host>`.
+if (process.argv.includes("__edge__")) {
+  const idx = process.argv.indexOf("__edge__");
+  const publicPort = parseInt(process.argv[idx + 1] ?? "", 10);
+  const host = process.argv[idx + 2] ?? "0.0.0.0";
+
+  if (!Number.isInteger(publicPort) || publicPort <= 0 || publicPort > 65535) {
+    process.stderr.write(`[edge] Invalid public port: ${process.argv[idx + 1]}\n`);
+    process.exit(2);
+  }
+
+  try {
+    await startEdgeForwarder({ publicPort, host });
+    process.stderr.write(`[edge] Listening on ${host}:${publicPort}\n`);
+  } catch (err) {
+    process.stderr.write(`[edge] Failed to bind ${host}:${publicPort}: ${err}\n`);
+    process.exit(1);
+  }
+}

package/src/services/edge-target-resolver.ts

@@ -0,0 +1,63 @@
+/**
+ * Resolves which loopback port the edge forwarder should send traffic to.
+ *
+ * Split out of `edge-forwarder.ts` so the forwarder file stays about piping
+ * bytes and this one stays about trusting (or not trusting) the port it is told.
+ *
+ * The source of truth is `~/.ppm/.server-port`, written by the server itself
+ * the moment it binds — NOT `status.json`. Two reasons:
+ *   1. `writeStatus` replaces status.json wholesale at supervisor startup, so a
+ *      supervisor restart would blank the target out from under a live edge.
+ *   2. The edge is deliberately detached and outlives the supervisor; it must
+ *      not depend on the supervisor being alive to know where the server is.
+ * The supervisor mirrors the value into `status.json.serverPort` for `ppm
+ * status`, but that copy is observability only.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { getPpmDir } from "./ppm-dir.ts";
+
+/** File the server writes its bound port to. Single writer: the server. */
+export const SERVER_PORT_FILE = () => resolve(getPpmDir(), ".server-port");
+
+/** How long a resolved target port is trusted before re-reading from disk. */
+const TARGET_CACHE_MS = 1000;
+
+let cachedPort: number | null = null;
+let cachedAt = 0;
+
+/**
+ * Current server port, or null when it is absent/invalid.
+ *
+ * The value is validated rather than trusted: anything able to write the file
+ * would otherwise be able to redirect all tunnel traffic. Only a plausible port
+ * number is accepted, and callers must always dial loopback.
+ *
+ * Only successful reads are cached — caching a miss would stretch the
+ * forwarder's retry loop to one attempt per second during startup, which is
+ * exactly when the server is still coming up.
+ */
+export function resolveTargetPort(now: number = Date.now()): number | null {
+  if (cachedPort !== null && now - cachedAt < TARGET_CACHE_MS) return cachedPort;
+
+  let raw: number;
+  try {
+    const file = SERVER_PORT_FILE();
+    if (!existsSync(file)) return null;
+    raw = parseInt(readFileSync(file, "utf-8").trim(), 10);
+  } catch {
+    return null;
+  }
+
+  if (!Number.isInteger(raw) || raw <= 0 || raw > 65535) return null;
+
+  cachedPort = raw;
+  cachedAt = now;
+  return cachedPort;
+}
+
+/** Drop the memoized target port (tests, and after a known server restart). */
+export function _resetTargetCache(): void {
+  cachedPort = null;
+  cachedAt = 0;
+}

package/src/services/jsonl-transcript-parser.ts

@@ -154,6 +154,48 @@ export function nestChildEvents(events: ChatEvent[]): void {
   }
 }
 
+/**
+ * Nest child events across message boundaries. A backgrounded subagent keeps
+ * running after its turn ends, so its events land in later messages than the
+ * Agent/Task tool_use that spawned it. Collects parents globally, moves each
+ * child event into its parent's children array, and blanks out messages left
+ * with nothing but moved child content (callers filter empty messages).
+ * Mutates messages in-place.
+ */
+export function nestChildEventsAcrossMessages(messages: { content: string; events?: ChatEvent[] }[]): void {
+  const parentMap = new Map<string, ChatEvent & { type: "tool_use" }>();
+  for (const msg of messages) {
+    for (const ev of msg.events ?? []) {
+      if (ev.type === "tool_use" && (ev.tool === "Agent" || ev.tool === "Task") && ev.toolUseId) {
+        parentMap.set(ev.toolUseId, ev);
+      }
+    }
+  }
+  if (parentMap.size === 0) return;
+
+  for (const msg of messages) {
+    if (!msg.events?.length) continue;
+    const kept: ChatEvent[] = [];
+    let moved = 0;
+    for (const ev of msg.events) {
+      const pid = (ev as any).parentToolUseId as string | undefined;
+      const parent = pid ? parentMap.get(pid) : undefined;
+      if (parent && parent !== ev) {
+        if (!parent.children) parent.children = [];
+        parent.children.push(ev);
+        moved++;
+      } else {
+        kept.push(ev);
+      }
+    }
+    if (moved === 0) continue;
+    msg.events = kept.length > 0 ? kept : undefined;
+    // A message that was purely subagent output duplicates its (now nested)
+    // text via `content` — blank it so the empty-message filter drops it.
+    if (kept.length === 0) msg.content = "";
+  }
+}
+
 /**
  * Validate JSONL path — must be under ~/.claude/ (prevents arbitrary file reads).
  * Throws Error with descriptive message. Returns resolved realpath on success.
@@ -233,9 +275,9 @@ export async function parseJsonlTranscript(
     merged.push(msg);
   }
 
-  for (const msg of merged) {
-    if (msg.events) nestChildEvents(msg.events);
-  }
+  // Nest across messages: a backgrounded subagent's events land in later
+  // messages than the Agent tool_use that spawned it.
+  nestChildEventsAcrossMessages(merged);
 
   return merged.filter(
     (msg) => msg.content.trim().length > 0 || (msg.events && msg.events.length > 0),

package/src/services/slash-discovery/discover-skill-roots.ts

@@ -1,4 +1,4 @@
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, basename } from "node:path";
 import { existsSync, statSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -39,13 +39,14 @@ function addRoot(
   basePath: string,
   origin: ItemOrigin,
   source: DefinitionSource,
+  pluginName?: string,
 ): void {
   const full = resolve(basePath, origin);
   if (!isDir(full)) return;
   const resolved = resolve(full);
   if (seen.has(resolved)) return;
   seen.add(resolved);
-  roots.push({ path: resolved, source, origin });
+  roots.push({ path: resolved, source, origin, ...(pluginName && { pluginName }) });
 }
 
 /**
@@ -143,6 +144,23 @@ export function resolveInstalledPlugins(pluginsDir: string): InstalledPlugin[] {
   }
 }
 
+/**
+ * Plugin identifier used as the namespace prefix. The registry key is
+ * `plugin-id@marketplace-id`, so the id is everything before the `@`; scanned
+ * fallbacks read the manifest, and the directory name is the last resort.
+ */
+export function resolvePluginName(plugin: InstalledPlugin): string {
+  const fromKey = plugin.key?.split("@")[0]?.trim();
+  if (fromKey) return fromKey;
+  try {
+    const manifest = JSON.parse(
+      readFileSync(resolve(plugin.path, ".claude-plugin", "plugin.json"), "utf-8"),
+    ) as { name?: unknown };
+    if (typeof manifest.name === "string" && manifest.name.trim()) return manifest.name.trim();
+  } catch { /* manifest missing or malformed — fall through */ }
+  return basename(plugin.path);
+}
+
 /** Add roots for Claude Code plugins, which ship their own skills/commands/agents */
 function addPluginRoots(roots: SkillRoot[], seen: Set<string>, projectPath: string): void {
   const pluginsDir = resolve(homedir(), ".claude", "plugins");
@@ -150,8 +168,9 @@ function addPluginRoots(roots: SkillRoot[], seen: Set<string>, projectPath: stri
   const disabled = loadDisabledPluginKeys(projectPath);
   for (const plugin of resolveInstalledPlugins(pluginsDir)) {
     if (plugin.key && disabled.has(plugin.key)) continue;
+    const pluginName = resolvePluginName(plugin);
     for (const origin of ORIGINS) {
-      addRoot(roots, seen, plugin.path, origin, "user-plugin");
+      addRoot(roots, seen, plugin.path, origin, "user-plugin", pluginName);
     }
   }
 }

package/src/services/slash-discovery/index.ts

@@ -11,6 +11,7 @@ export { isPpmHandled, getBuiltinByName } from "./builtin-commands.ts";
 export { executeBuiltin } from "./builtin-handlers.ts";
 export { invalidateCache, invalidateAll } from "./cache.ts";
 export { ensureSdkCommands, invalidateSdkCommands } from "./sdk-commands.ts";
+export { rewriteSlashAlias } from "./rewrite-slash-alias.ts";
 export type { SlashItem, SlashItemWithSource, ShadowedItem, DiscoveryResult, SkillRoot, DefinitionSource } from "./types.ts";
 
 /**

package/src/services/slash-discovery/rewrite-slash-alias.ts

@@ -0,0 +1,35 @@
+import type { SlashItem } from "./types.ts";
+
+/** Split a leading `/name` off a message, if there is one. */
+function splitCommand(content: string): { name: string; rest: string } | null {
+  const match = content.match(/^\/(\S+)/);
+  if (!match) return null;
+  return { name: match[1]!, rest: content.slice(match[0].length) };
+}
+
+/**
+ * Rewrite a leading slash command that used a legacy alias into the name the
+ * runtime actually registers.
+ *
+ * Claude Code names a plugin item after its location, prefixed by the owning
+ * plugin (`/ak-engineer:ak-debug`). Kits that instead declare a self-namespaced
+ * frontmatter name (AgentKit ships `name: ak:debug`) publish a name nothing can
+ * resolve, so users typing the documented `/ak:debug` get a dead command. The
+ * declared name is kept as an alias during discovery; this turns it back into
+ * the canonical one.
+ *
+ * When two plugins claim the same alias — the AgentKit engineer and marketing
+ * kits overlap on ~30 skills — the first match in discovery order wins, which
+ * follows the plugin registry order.
+ *
+ * Unknown commands pass through untouched: reporting those is the SDK's job.
+ */
+export function rewriteSlashAlias(content: string, items: SlashItem[]): string {
+  const cmd = splitCommand(content);
+  if (!cmd) return content;
+  // A name that already resolves is never rewritten, even if some other item
+  // happens to alias it.
+  if (items.some((item) => item.name === cmd.name)) return content;
+  const hit = items.find((item) => item.aliases?.includes(cmd.name));
+  return hit ? `/${hit.name}${cmd.rest}` : content;
+}

package/src/services/slash-discovery/skill-loader.ts

@@ -53,6 +53,34 @@ function walkDir(dir: string, visitor: (filePath: string) => void, visited = new
   }
 }
 
+/**
+ * Resolve the invocable name for an item found under `root`.
+ *
+ * Plugin items are namespaced by their owning plugin, but the two kinds differ
+ * in what follows the prefix. A skill or command is named after where its file
+ * lives, so a kit that self-namespaces instead (AgentKit ships `name: ak:debug`)
+ * is not invocable under that declared name — it is kept as an alias so typed
+ * input can be rewritten to the canonical one. An agent is named after its
+ * frontmatter `name`, which is also how the runtime addresses it for delegation.
+ */
+function qualify(
+  root: SkillRoot,
+  pathName: string,
+  declared: string | undefined,
+  nameSource: "path" | "declared" = "path",
+): { name: string; aliases?: string[] } {
+  if (!root.pluginName) return { name: declared ?? pathName };
+  if (nameSource === "declared") {
+    const suffix = declared || pathName;
+    return { name: suffix ? `${root.pluginName}:${suffix}` : "" };
+  }
+  // A SKILL.md sitting at the plugin root has no directory to take a name from
+  const suffix = pathName || declared;
+  if (!suffix) return { name: "" };
+  const name = `${root.pluginName}:${suffix}`;
+  return { name, ...(declared && declared !== name && { aliases: [declared] }) };
+}
+
 /** Collect commands from a root with origin "commands" */
 function loadCommands(root: SkillRoot): SlashItemWithSource[] {
   const items: SlashItemWithSource[] = [];
@@ -66,10 +94,13 @@ function loadCommands(root: SkillRoot): SlashItemWithSource[] {
       const content = readFileSync(filePath, "utf-8");
       const { meta } = parseFrontmatter(content);
       const rel = relative(root.path, filePath);
-      const name = rel.replace(/\.md$/, "").split(sep).join("/");
+      const pathName = rel.replace(/\.md$/, "").split(sep).join("/");
+      const { name, aliases } = qualify(root, pathName, str(meta.name));
+      if (!name) return;
       items.push({
         type: "command",
-        name: str(meta.name) ?? name,
+        name,
+        ...(aliases && { aliases }),
         description: str(meta.description) ?? "",
         argumentHint: str(meta["argument-hint"]),
         scope,
@@ -106,11 +137,12 @@ function loadSkills(root: SkillRoot): SlashItemWithSource[] {
       dirsWithSkillMd.add(skillDir);
       const rel = relative(root.path, skillDir);
       const pathName = rel.split(sep).join("/");
-      const name = str(meta.name) ?? pathName;
+      const { name, aliases } = qualify(root, pathName, str(meta.name));
       if (!name) return;
       items.push({
         type: "skill",
         name,
+        ...(aliases && { aliases }),
         description: str(meta.description) ?? "",
         argumentHint: str(meta["argument-hint"]),
         scope,
@@ -136,11 +168,12 @@ function loadSkills(root: SkillRoot): SlashItemWithSource[] {
         const { meta } = parseFrontmatter(content);
         const rel = relative(root.path, filePath);
         const pathName = rel.replace(/\.md$/, "").split(sep).join("/");
-        const name = str(meta.name) ?? pathName;
+        const { name, aliases } = qualify(root, pathName, str(meta.name));
         if (!name) return;
         items.push({
           type: "skill",
           name,
+          ...(aliases && { aliases }),
           description: str(meta.description) ?? "",
           argumentHint: str(meta["argument-hint"]),
           scope,
@@ -168,7 +201,9 @@ function loadAgents(root: SkillRoot): SlashItemWithSource[] {
       const content = readFileSync(filePath, "utf-8");
       const { meta } = parseFrontmatter(content);
       const rel = relative(root.path, filePath);
-      const name = str(meta.name) ?? rel.replace(/\.md$/, "").split(sep).join("/");
+      const pathName = rel.replace(/\.md$/, "").split(sep).join("/");
+      const { name } = qualify(root, pathName, str(meta.name), "declared");
+      if (!name) return;
       items.push({
         type: "agent",
         name,

package/src/services/slash-discovery/types.ts

@@ -41,6 +41,12 @@ export interface SkillRoot {
   path: string;              // Resolved absolute path
   source: DefinitionSource;
   origin: ItemOrigin;
+  /**
+   * Owning Claude Code plugin, set only for roots under ~/.claude/plugins/.
+   * Items below such a root are namespaced `<pluginName>:<path>`, matching how
+   * Claude Code itself registers them.
+   */
+  pluginName?: string;
 }
 
 /** Extends SlashItem with source metadata */

package/src/types/api.ts

@@ -70,6 +70,7 @@ export type ChatWsServerMessage =
   | { type: "phase_changed"; phase: SessionPhase; elapsed?: number }
   | { type: "session_state"; sessionId: string; phase: SessionPhase; pendingApproval: { requestId: string; tool: string; input: unknown } | null; sessionTitle: string | null; model?: string; effort?: string; thinking?: boolean }
   | { type: "turn_events"; events: unknown[] }
+  | { type: "user_message"; content: string; imageCount?: number; timestamp?: string }
   | { type: "title_updated"; title: string }
   | { type: "compact_status"; status: "compacting" | "done" }
   | { type: "ping" };

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

@@ -239,6 +239,46 @@ export function useChat(sessionId: string | null, providerId = "claude", project
     return true;
   }, []);
 
+  /**
+   * Fallback for child events arriving after their parent Agent/Task card was
+   * finalized: a backgrounded subagent keeps streaming past the turn's `done`
+   * (the SDK ends the turn at the boundary while the agent runs on), so the
+   * parent tool_use now lives in a finalized message, not the streaming buffer.
+   * Nest the child there instead of letting it render flat in the transcript.
+   */
+  const routeToFinalizedParent = useCallback((childEvent: ChatEvent, parentToolUseId: string): boolean => {
+    const isParent = (e: ChatEvent) =>
+      e.type === "tool_use" && (e.tool === "Agent" || e.tool === "Task") && (e as any).toolUseId === parentToolUseId;
+    const msgs = messagesRef.current;
+    let msgIdx = -1;
+    for (let i = msgs.length - 1; i >= 0; i--) {
+      if (msgs[i]!.events?.some(isParent)) { msgIdx = i; break; }
+    }
+    if (msgIdx === -1) return false;
+
+    setMessages((prev) => {
+      // Re-locate in prev — state may have shifted since the ref snapshot
+      let idx = -1;
+      for (let i = prev.length - 1; i >= 0; i--) {
+        if (prev[i]!.events?.some(isParent)) { idx = i; break; }
+      }
+      if (idx === -1) return prev;
+      const msg = prev[idx]!;
+      const events = msg.events!.map((e) => {
+        if (!isParent(e) || e.type !== "tool_use") return e;
+        const children = [...(e.children ?? [])];
+        // Replays can redeliver id-bearing children — upsert instead of duplicating
+        const cid = (childEvent as any).toolUseId as string | undefined;
+        const dup = cid ? children.findIndex((c) => c.type === childEvent.type && (c as any).toolUseId === cid) : -1;
+        if (dup !== -1) children[dup] = childEvent;
+        else children.push(childEvent);
+        return { ...e, children };
+      });
+      return [...prev.slice(0, idx), { ...msg, events }, ...prev.slice(idx + 1)];
+    });
+    return true;
+  }, []);
+
   /** Flush refs into React state (called from throttled timer or directly) */
   const flushMessages = useCallback(() => {
     syncRafRef.current = 0;
@@ -323,6 +363,7 @@ export function useChat(sessionId: string | null, providerId = "claude", project
           syncMessages();
           break;
         }
+        if (pid && routeToFinalizedParent(ev as ChatEvent, pid)) break;
         streamingContentRef.current += ev.content;
         streamingEventsRef.current.push(ev as ChatEvent);
         syncMessages();
@@ -335,6 +376,7 @@ export function useChat(sessionId: string | null, providerId = "claude", project
           syncMessages();
           break;
         }
+        if (pid && routeToFinalizedParent(ev as ChatEvent, pid)) break;
         streamingEventsRef.current.push(ev as ChatEvent);
         syncMessages();
         break;
@@ -352,6 +394,7 @@ export function useChat(sessionId: string | null, providerId = "claude", project
           syncMessages();
           break;
         }
+        if (pid && routeToFinalizedParent(ev as ChatEvent, pid)) break;
         const tuId = ev.toolUseId as string | undefined;
         upsertStreamingEvent((e) => !!tuId && e.type === "tool_use" && (e as any).toolUseId === tuId);
         syncMessages();
@@ -372,6 +415,7 @@ export function useChat(sessionId: string | null, providerId = "claude", project
           syncMessages();
           break;
         }
+        if (pid && routeToFinalizedParent(ev as ChatEvent, pid)) break;
         upsertStreamingEvent((e) => !!trId && e.type === "tool_result" && (e as any).toolUseId === trId);
         syncMessages();
         break;
@@ -593,7 +637,7 @@ export function useChat(sessionId: string | null, providerId = "claude", project
         break;
       }
     }
-  }, [routeToParent, syncMessages]);
+  }, [routeToParent, routeToFinalizedParent, syncMessages]);
 
   const handleMessage = useCallback((event: MessageEvent) => {
     let data: ChatWsServerMessage;
@@ -610,6 +654,26 @@ export function useChat(sessionId: string | null, providerId = "claude", project
     // on the global bus (`use-global-events.ts`) instead of here — a chat socket is
     // not guaranteed to exist since chat tabs mount lazily.
 
+    // A user message sent from another device/tab of this session — render its
+    // bubble. The sender never receives this echo (server excludes the sender),
+    // so no dedupe against the optimistic append is needed.
+    if ((data as any).type === "user_message") {
+      const content = (data as any).content as string;
+      setMessages((prev) => {
+        const last = prev[prev.length - 1];
+        // Dedupe: a concurrent turn_events replay or REST refetch may already
+        // have appended this same turn's user message.
+        if (last?.role === "user" && last.content === content) return prev;
+        return [...prev, {
+          id: `user-remote-${Date.now()}`,
+          role: "user" as const,
+          content,
+          timestamp: (data as any).timestamp ?? new Date().toISOString(),
+        }];
+      });
+      return;
+    }
+
     // Handle title updates from SDK summary
     if ((data as any).type === "title_updated") {
       setSessionTitle((data as any).title ?? null);