perf: skip initial PTY replay for fresh sessions and cache slash-command scans

Two cuts to the user-perceived "tile is empty" window after clicking
Create Session.

#1 — TerminalInstance's setup effect always issued pty:replay-since(0)
on first mount and gated live writes until that IPC resolved, even for
brand-new sessions whose broker ring buffer is empty by construction.
The roundtrip cost an event-loop tick + IPC latency before xterm could
paint the first byte. Mark freshly-created session IDs in a renderer-
side Set inside handleCreateSession; consumeFresh on the first mount
opens the live-write gate immediately and skips the replay block.
Subsequent remounts (hide → dispose → reveal) consume false and go
through the normal replay path, so the hide/reveal catch-up logic is
unchanged. Skip is gated on isVisibleRef so a fresh-but-hidden mount
falls through to the existing path that records the catch-up offset.

#2 — The slash-command effect ran a fresh slash-commands:scan IPC on
every tile mount, then awaited the result before populating the
warning-on-typing set. For users with many command files, the scan is
dozens of readFile calls. Add a renderer-side cwd+sessionType cache
(slash-command-cache.ts): handleCreateSession warms it in parallel
with PTY cold-start, so the tile-mount effect can read synchronously
when the cache is hit. Concurrent scans dedupe via an inflight map;
errors are not cached so a later attempt can retry.

Behavioral note: the cache lives for the app lifetime and never
invalidates, so a slash command file added at runtime won't be picked
up until restart. The set is only used for typing-time warnings, so
the regression is a phantom "not in mcode's known slash commands"
message — the command itself still works.

Tests: unit coverage for both utils (markFresh/consumeFresh idempotency
and one-shot semantics; cache dedup, key-by-(type,cwd), error-not-cached).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: waterdrop86

src/renderer/App.tsx

@@ -22,6 +22,8 @@ import { useChangesStore } from './stores/changes-store';
 import { useTodoStore } from './stores/todo-store';
 import { executeAppCommand } from './utils/app-commands';
 import { autoExpandInKanban } from './utils/session-actions';
+import { ensureSlashCommandsScan } from './utils/slash-command-cache';
+import { markFresh } from './utils/fresh-sessions';
 import TitleBar from './components/TitleBar';
 import { ErrorBoundary, ErrorFallback } from './components/shared/ErrorBoundary';
 import CreateTaskDialog from './components/shared/CreateTaskDialog';
@@ -32,6 +34,7 @@ import { useUpdateSubscriptions } from './hooks/useUpdateSubscriptions';
 import { useUpdateStore } from './stores/update-store';
 import UpdateBanner from './components/UpdateBanner';
 import { canSessionBeDefaultTaskTarget } from '@shared/session-capabilities';
+import { isAgentSessionType } from '@shared/session-agents';
 import type { CreateTaskInput, SessionCreateInput, SidebarTab } from '@shared/types';
 
 function App(): React.JSX.Element {
@@ -167,7 +170,17 @@ function App(): React.JSX.Element {
 
   const handleCreateSession = async (input: SessionCreateInput): Promise<void> => {
     try {
+      // Warm the slash-command cache in parallel with PTY cold-start so the
+      // tile-mount path can read it synchronously instead of issuing its own scan.
+      const sessionType = input.sessionType ?? 'claude';
+      if (isAgentSessionType(sessionType)) {
+        ensureSlashCommandsScan(sessionType, input.cwd);
+      }
+
       const session = await window.mcode.sessions.create(input);
+      // First mount of this session can skip the initial pty:replay-since(0)
+      // round-trip — the broker ring buffer is empty by construction.
+      markFresh(session.sessionId);
       addSession(session);
 
       if (splitIntent) {

src/renderer/components/SessionTile/TerminalInstance.tsx

@@ -29,6 +29,11 @@ import {
   stripTerminalInputControlSequences,
 } from '../../utils/slash-command-validation';
 import { utf8ByteLength } from '../../utils/utf8-byte-length';
+import {
+  ensureSlashCommandsScan,
+  getSlashCommandsCached,
+} from '../../utils/slash-command-cache';
+import { consumeFresh } from '../../utils/fresh-sessions';
 
 interface TerminalInstanceProps {
   sessionId: string;
@@ -114,16 +119,16 @@ function TerminalInstance({ sessionId, sessionType, scrollbackLines, isVisible =
       knownSlashCommandsRef.current = new Set();
       return;
     }
+    const cached = getSlashCommandsCached(agent.sessionType, cwd);
+    if (cached) {
+      knownSlashCommandsRef.current = cached;
+      return;
+    }
     let stale = false;
-    window.mcode.slashCommands.scan(agent.sessionType, cwd).then((commands) => {
-      if (!stale) {
-        knownSlashCommandsRef.current = new Set(commands.map((cmd) => cmd.name.toLowerCase()));
-      }
-    }).catch(() => {
-      if (!stale) knownSlashCommandsRef.current = new Set();
+    ensureSlashCommandsScan(agent.sessionType, cwd).then((set) => {
+      if (!stale) knownSlashCommandsRef.current = set;
     });
     return () => { stale = true; };
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- sessionType is read via ref
   }, [cwd]);
 
   // fit() while hidden would resize xterm to the 0×0 container, hand bash a
@@ -437,10 +442,21 @@ function TerminalInstance({ sessionId, sessionType, scrollbackLines, isVisible =
     // includes those bytes (broker appends synchronously per chunk), so we'd
     // double-write. The bridge loop below catches up bytes added between the
     // IPC send and response.
+    //
+    // Exception: a freshly-created session has an empty broker ring buffer by
+    // construction, so the replay round-trip would just return zero bytes. We
+    // skip it and open the gate immediately, removing one IPC roundtrip and
+    // one event-loop tick from the user-perceived "tile is empty" window.
+    const skipInitialReplay = consumeFresh(sessionId) && isVisibleRef.current;
     hiddenAtOffsetRef.current = null;
-    dropLiveWritesRef.current = true;
     byteOffsetRef.current = 0;
-    setTerminalLive(sessionId, false);
+    if (skipInitialReplay) {
+      dropLiveWritesRef.current = false;
+      setTerminalLive(sessionId, true);
+    } else {
+      dropLiveWritesRef.current = true;
+      setTerminalLive(sessionId, false);
+    }
 
     // Fit before replay: cursor-position / clear-screen escapes in the
     // buffered bytes are interpreted at the terminal's current cols/rows,
@@ -449,6 +465,7 @@ function TerminalInstance({ sessionId, sessionType, scrollbackLines, isVisible =
     let cancelledInitial = false;
     const initialFitTimer = window.setTimeout(() => {
       safeFit();
+      if (skipInitialReplay) return;
       (async () => {
         try {
           const r = await window.mcode.pty.getReplaySince(sessionId, 0);

src/renderer/utils/fresh-sessions.ts

@@ -0,0 +1,15 @@
+// Session IDs whose first TerminalInstance mount can skip the initial
+// pty:replay-since(0) round-trip. Marked by handleCreateSession (the spawn
+// is brand-new, so the broker ring buffer is empty); consumed by the
+// TerminalInstance setup effect on the *first* mount only — a later
+// hide → dispose → reveal remount goes through the normal replay path.
+
+const fresh = new Set<string>();
+
+export function markFresh(sessionId: string): void {
+  fresh.add(sessionId);
+}
+
+export function consumeFresh(sessionId: string): boolean {
+  return fresh.delete(sessionId);
+}

src/renderer/utils/slash-command-cache.ts

@@ -0,0 +1,54 @@
+import type { SlashCommandEntry } from '@shared/types';
+import type { AgentSessionType } from '@shared/session-agents';
+
+type Key = string;
+
+const cache = new Map<Key, Set<string>>();
+const inflight = new Map<Key, Promise<Set<string>>>();
+
+function key(sessionType: AgentSessionType, cwd: string): Key {
+  return `${sessionType}|${cwd}`;
+}
+
+function toSet(commands: SlashCommandEntry[]): Set<string> {
+  return new Set(commands.map((cmd) => cmd.name.toLowerCase()));
+}
+
+export function getSlashCommandsCached(
+  sessionType: AgentSessionType,
+  cwd: string,
+): Set<string> | undefined {
+  return cache.get(key(sessionType, cwd));
+}
+
+// Kicks off (or joins) a scan and resolves with the cached set.
+// Errors aren't cached so a later attempt can retry; the resolved value is an empty set.
+export function ensureSlashCommandsScan(
+  sessionType: AgentSessionType,
+  cwd: string,
+): Promise<Set<string>> {
+  const k = key(sessionType, cwd);
+  const cached = cache.get(k);
+  if (cached) return Promise.resolve(cached);
+  const existing = inflight.get(k);
+  if (existing) return existing;
+  const p = window.mcode.slashCommands
+    .scan(sessionType, cwd)
+    .then((commands) => {
+      const set = toSet(commands);
+      cache.set(k, set);
+      inflight.delete(k);
+      return set;
+    })
+    .catch(() => {
+      inflight.delete(k);
+      return new Set<string>();
+    });
+  inflight.set(k, p);
+  return p;
+}
+
+export function _resetSlashCommandCacheForTests(): void {
+  cache.clear();
+  inflight.clear();
+}

tests/unit/renderer/utils/fresh-sessions.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { markFresh, consumeFresh } from '../../../../src/renderer/utils/fresh-sessions';
+
+describe('fresh-sessions', () => {
+  it('returns true on the first consume after markFresh, false thereafter', () => {
+    const id = 'session-' + Math.random();
+    markFresh(id);
+    expect(consumeFresh(id)).toBe(true);
+    expect(consumeFresh(id)).toBe(false);
+  });
+
+  it('returns false for an unmarked session', () => {
+    expect(consumeFresh('session-' + Math.random())).toBe(false);
+  });
+
+  it('treats each session id independently', () => {
+    const a = 'a-' + Math.random();
+    const b = 'b-' + Math.random();
+    markFresh(a);
+    markFresh(b);
+    expect(consumeFresh(a)).toBe(true);
+    expect(consumeFresh(b)).toBe(true);
+    expect(consumeFresh(a)).toBe(false);
+    expect(consumeFresh(b)).toBe(false);
+  });
+
+  it('marking twice is idempotent', () => {
+    const id = 'dup-' + Math.random();
+    markFresh(id);
+    markFresh(id);
+    expect(consumeFresh(id)).toBe(true);
+    expect(consumeFresh(id)).toBe(false);
+  });
+});

tests/unit/renderer/utils/slash-command-cache.test.ts

@@ -0,0 +1,88 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  ensureSlashCommandsScan,
+  getSlashCommandsCached,
+  _resetSlashCommandCacheForTests,
+} from '../../../../src/renderer/utils/slash-command-cache';
+import type { SlashCommandEntry } from '../../../../src/shared/types';
+
+interface MockGlobal {
+  mcode: {
+    slashCommands: { scan: ReturnType<typeof vi.fn> };
+  };
+}
+
+function setScanResult(value: SlashCommandEntry[] | Promise<SlashCommandEntry[]>): ReturnType<typeof vi.fn> {
+  const scan = vi.fn(() => (value instanceof Promise ? value : Promise.resolve(value)));
+  (window as unknown as MockGlobal).mcode = {
+    slashCommands: { scan },
+  };
+  return scan;
+}
+
+function entry(name: string): SlashCommandEntry {
+  return { name, description: '', source: 'user' };
+}
+
+describe('slash-command-cache', () => {
+  beforeEach(() => {
+    _resetSlashCommandCacheForTests();
+  });
+
+  it('returns undefined from getSlashCommandsCached before any scan', () => {
+    setScanResult([]);
+    expect(getSlashCommandsCached('claude', '/repo')).toBeUndefined();
+  });
+
+  it('caches the scan result and lowercases names', async () => {
+    setScanResult([entry('Foo'), entry('BAR')]);
+    const set = await ensureSlashCommandsScan('claude', '/repo');
+    expect(set).toEqual(new Set(['foo', 'bar']));
+    expect(getSlashCommandsCached('claude', '/repo')).toBe(set);
+  });
+
+  it('dedupes concurrent scans for the same key into a single IPC call', async () => {
+    let resolveScan: (cmds: SlashCommandEntry[]) => void = () => {};
+    const pending = new Promise<SlashCommandEntry[]>((res) => { resolveScan = res; });
+    const scan = setScanResult(pending);
+
+    const p1 = ensureSlashCommandsScan('claude', '/repo');
+    const p2 = ensureSlashCommandsScan('claude', '/repo');
+    expect(scan).toHaveBeenCalledTimes(1);
+
+    resolveScan([entry('alpha')]);
+    const [s1, s2] = await Promise.all([p1, p2]);
+    expect(s1).toBe(s2);
+    expect(s1).toEqual(new Set(['alpha']));
+  });
+
+  it('keys cache by sessionType and cwd', async () => {
+    const scan = setScanResult([entry('hi')]);
+    await ensureSlashCommandsScan('claude', '/a');
+    await ensureSlashCommandsScan('claude', '/b');
+    await ensureSlashCommandsScan('codex', '/a');
+    expect(scan).toHaveBeenCalledTimes(3);
+
+    // Subsequent calls hit the cache.
+    await ensureSlashCommandsScan('claude', '/a');
+    expect(scan).toHaveBeenCalledTimes(3);
+  });
+
+  it('does not cache errors so a later attempt can retry', async () => {
+    const scan = vi.fn()
+      .mockRejectedValueOnce(new Error('boom'))
+      .mockResolvedValueOnce([entry('ok')]);
+    (window as unknown as MockGlobal).mcode = {
+      slashCommands: { scan },
+    };
+
+    const first = await ensureSlashCommandsScan('claude', '/repo');
+    expect(first).toEqual(new Set());
+    expect(getSlashCommandsCached('claude', '/repo')).toBeUndefined();
+
+    const second = await ensureSlashCommandsScan('claude', '/repo');
+    expect(second).toEqual(new Set(['ok']));
+    expect(scan).toHaveBeenCalledTimes(2);
+  });
+});