🤖 Stateless /compact UX with structured metadata (#197)

## Overview

Replace localStorage-based compaction state tracking with structured
metadata embedded in messages. Four critical bugs discovered after
initial implementation were fixed through systematic improvements to the
replay and metadata flow architecture.

**Key insight**: Embed structured metadata directly in the user's
compaction request message. The backend stores it as a black-box, and
the frontend queries it when needed—no localStorage, no callback chains,
no event systems.

## What Changed

### Architecture

**Before (localStorage-based):**
```
User types /compact -c msg → ChatInput → onCompactStart callback → App → localStorage
Backend compacts → useAutoCompactContinue reads localStorage → sends continue message
```

**After (metadata-based):**
```
User types /compact -c msg → ChatInput creates cmuxMetadata: { type: "compaction-request", parsed: { continueMessage } }
Backend stores metadata as-is (black-box) → useAutoCompactContinue queries messages → sends continue message
```

### Key Improvements

1. **Metadata Flow**: `compaction-request` → backend black-box →
`compaction-result` in summary
2. **Stream Event Buffering**: All stream events buffered until
`caught-up` to ensure aggregator has full historical context
3. **Single Source of Truth**: `cmuxMetadata` drives all compaction
detection, display, and continuation logic
4. **Type Safety**: Discriminated unions with proper narrowing
throughout

## Bugs Fixed

### Issue #1: Continue Message Lost After Edit ✅

**Problem:** Editing `/compact -c "msg"` lost the continue message.

**Root Cause:** When compaction completed, history was replaced with
just the summary. The original `compaction-request` message (containing
`continueMessage`) was deleted. `useAutoCompactContinue` looked for it
and found nothing.

**Solution:** Extract `continueMessage` from request **before** history
replacement and store it in summary metadata as `compaction-result`.
Hook now reads from summary, not request.

```typescript
// In WorkspaceStore during compaction completion:
const continueMessage = compactRequestMsg?.metadata?.cmuxMetadata?.parsed.continueMessage;
const summaryMessage = createCmuxMessage(/*...*/,  {
  cmuxMetadata: continueMessage 
    ? { type: "compaction-result", continueMessage } 
    : { type: "normal" },
});
```

### Issue #2: "streaming..." Instead of "compacting..." After Reload ✅

**Problem:** After page reload during active compaction,
StreamingBarrier showed "streaming..." instead of "compacting...".

**Root Cause:** Replay timing issue. When `stream-start` arrived during
replay, aggregator's message cache was still empty (messages buffered
separately), so `isCompacting` check failed.

**Solution:** Buffer **all stream events** (start/delta/end/abort/tool
calls) until `caught-up` message arrives. Process them only after
historical messages are loaded. This ensures aggregator always has full
context when detecting compaction state.

```typescript
// In WorkspaceStore:
if (!isCaughtUp && this.isStreamEvent(data)) {
  const pending = this.pendingStreamEvents.get(workspaceId) ?? [];
  pending.push(data);
  return; // Don't process yet
}

if (isCaughtUpMessage(data)) {
  aggregator.loadHistoricalMessages(historicalMsgs);
  // NOW process buffered events with full context
  for (const event of pendingEvents) {
    this.processStreamEvent(workspaceId, aggregator, event);
  }
}
```

**Benefits:**
- Eliminates entire class of replay timing bugs
- Works for all stream events (not just compaction detection)
- No special cases or optional parameters

### Issue #3: Edit Button Active During Compaction ✅

**Problem:** Clicking "Edit" during compaction created a stuck
state—input populated but disabled, user couldn't type or cancel.

**Solution:** Disable Edit button during compaction with helpful tooltip
explaining how to cancel first. Prevents user from entering broken
state.

```typescript
// In UserMessage:
{
  label: "Edit",
  onClick: handleEdit,
  disabled: isCompacting,
  tooltip: isCompacting
    ? `Cannot edit while compacting (press ${formatKeybind(KEYBINDS.INTERRUPT_STREAM)} to cancel)`
    : undefined,
}
```

### Issue #4: Duplicate Messages When Editing Compaction ✅

**Problem:** Editing a compaction message created duplicates instead of
replacing.

**Root Cause:** Compaction command path didn't pass `editMessageId`.

**Solution:** Pass `editMessageId` through compaction path and clear
editing state on success.

## Files Changed

### Deleted
- `src/components/Messages/PendingUserDraft.tsx` (84 lines)
- `src/components/Messages/ChatBarrier/CompactionBarrier.tsx` (37 lines)

### Modified
- **src/stores/WorkspaceStore.ts** - Stream event buffering until
caught-up, extract continueMessage before replacement
- **src/hooks/useAutoCompactContinue.ts** - Query `compaction-result`
from summary instead of request
- **src/utils/messages/StreamingMessageAggregator.ts** - Use
`cmuxMetadata` for isCompacting detection
- **src/components/ChatInput.tsx** - Create metadata on send, regenerate
on edit
- **src/components/AIView.tsx** - Pass isCompacting to MessageRenderer
- **src/components/Messages/MessageRenderer.tsx** - Pass isCompacting to
UserMessage
- **src/components/Messages/UserMessage.tsx** - Disable edit button
during compaction
- **src/types/message.ts** - Add `CmuxFrontendMetadata` discriminated
union
- **src/types/ipc.ts** - Add `cmuxMetadata` to SendMessageOptions
- **src/services/agentSession.ts** - Pass through metadata as black-box

### Added
- **tests/ipcMain/sendMessage.test.ts** - Integration test verifying
metadata round-trip

## Benefits

1. **Type-safe** - Discriminated unions enforce correct structure at
compile time
2. **Single source of truth** - Message metadata is authoritative, no
synchronization issues
3. **No string parsing on read** - Data is already structured from send
4. **Queryable** - Easy to find compaction messages with `.find()`
5. **Editable** - Re-parses edited commands automatically
6. **Stateless** - No localStorage or callback chains
7. **Simpler** - Removed 2 components, ~105 net LoC reduction
8. **Tested** - Integration test verifies metadata round-trip through
IPC
9. **Robust** - Stream event buffering eliminates replay timing bugs

## Testing

- ✅ TypeScript compilation passes (both renderer and main)
- ✅ Integration test passes (metadata round-trip)
- ✅ All type constraints satisfied
- ✅ No breaking changes to existing APIs
- ✅ Static checks passing (lint, fmt, typecheck)

Manual testing recommended:
- `/compact` without continue message
- `/compact -c "message"` with auto-continue
- Edit compaction message after completion
- Reload during compaction (verify "compacting..." barrier)
- Click Edit button during compaction (verify disabled with tooltip)

_Generated with `cmux`_

---------

Co-authored-by: Ammar Bandukwala <ammar@ammar.io>

Author: ammar-agent

src/App.tsx

@@ -197,7 +197,7 @@ function AppInner() {
   useResumeManager();
 
   // Handle auto-continue after compaction (when user uses /compact -c)
-  const { handleCompactStart } = useAutoCompactContinue();
+  useAutoCompactContinue();
 
   // Sync selectedWorkspace with URL hash
   useEffect(() => {
@@ -641,13 +641,11 @@ function AppInner() {
                 workspaceInfo={`${selectedWorkspace.projectName}/${selectedWorkspace.workspacePath.split("/").pop() ?? ""}`}
               >
                 <AIView
+                  key={selectedWorkspace.workspaceId}
                   workspaceId={selectedWorkspace.workspaceId}
                   projectName={selectedWorkspace.projectName}
                   branch={selectedWorkspace.workspacePath.split("/").pop() ?? ""}
                   workspacePath={selectedWorkspace.workspacePath}
-                  onCompactStart={(continueMessage) =>
-                    handleCompactStart(selectedWorkspace.workspaceId, continueMessage)
-                  }
                 />
               </ErrorBoundary>
             ) : (

src/components/AIView.tsx

@@ -192,7 +192,6 @@ interface AIViewProps {
   projectName: string;
   branch: string;
   workspacePath: string;
-  onCompactStart?: (continueMessage: string | undefined) => void;
   className?: string;
 }
 
@@ -201,7 +200,6 @@ const AIViewInner: React.FC<AIViewProps> = ({
   projectName,
   branch,
   workspacePath,
-  onCompactStart,
   className,
 }) => {
   // NEW: Get workspace state from store (only re-renders when THIS workspace changes)
@@ -326,6 +324,23 @@ const AIViewInner: React.FC<AIViewProps> = ({
     handleOpenTerminal,
   });
 
+  // Clear editing state if the message being edited no longer exists
+  // Must be before early return to satisfy React Hooks rules
+  useEffect(() => {
+    if (!workspaceState || !editingMessage) return;
+
+    const mergedMessages = mergeConsecutiveStreamErrors(workspaceState.messages);
+    const editCutoffHistoryId = mergedMessages.find(
+      (msg): msg is Exclude<DisplayedMessage, { type: "history-hidden" }> =>
+        msg.type !== "history-hidden" && msg.historyId === editingMessage.id
+    )?.historyId;
+
+    if (!editCutoffHistoryId) {
+      // Message was replaced or deleted - clear editing state
+      setEditingMessage(undefined);
+    }
+  }, [workspaceState, editingMessage]);
+
   // Return early if workspace state not loaded yet
   if (!workspaceState) {
     return (
@@ -344,7 +359,6 @@ const AIViewInner: React.FC<AIViewProps> = ({
     workspaceState;
 
   // Get active stream message ID for token counting
-  // Use getActiveStreamMessageId() which returns the messageId directly
   const activeStreamMessageId = aggregator.getActiveStreamMessageId();
 
   // Track if last message was interrupted or errored (for RetryBarrier)
@@ -451,6 +465,7 @@ const AIViewInner: React.FC<AIViewProps> = ({
                           onEditUserMessage={handleEditUserMessage}
                           workspaceId={workspaceId}
                           model={currentModel ?? undefined}
+                          isCompacting={isCompacting}
                         />
                         {isAtCutoff && (
                           <EditBarrier>
@@ -507,7 +522,6 @@ const AIViewInner: React.FC<AIViewProps> = ({
             onMessageSent={handleMessageSent}
             onTruncateHistory={handleClearHistory}
             onProviderConfig={handleProviderConfig}
-            onCompactStart={onCompactStart}
             disabled={!projectName || !branch}
             isCompacting={isCompacting}
             editingMessage={editingMessage}

src/components/ChatInput.tsx

@@ -26,6 +26,8 @@ import { VimTextArea } from "./VimTextArea";
 import { ImageAttachments, type ImageAttachment } from "./ImageAttachments";
 
 import type { ThinkingLevel } from "@/types/thinking";
+import type { CmuxFrontendMetadata } from "@/types/message";
+import type { SendMessageOptions } from "@/types/ipc";
 
 const InputSection = styled.div`
   position: relative;
@@ -122,7 +124,6 @@ export interface ChatInputProps {
   onTruncateHistory: (percentage?: number) => Promise<void>;
   onProviderConfig?: (provider: string, keyPath: string[], value: string) => Promise<void>;
   onModelChange?: (model: string) => void;
-  onCompactStart?: (continueMessage: string | undefined) => void; // Called when compaction starts to update continue message state
   disabled?: boolean;
   isCompacting?: boolean;
   editingMessage?: { id: string; content: string };
@@ -282,21 +283,61 @@ const createErrorToast = (error: SendMessageErrorType): Toast => {
   }
 };
 
+/**
+ * Prepare compaction message from /compact command
+ * Returns the actual message text (summarization request), metadata, and options
+ */
+function prepareCompactionMessage(
+  command: string,
+  sendMessageOptions: SendMessageOptions
+): {
+  messageText: string;
+  metadata: CmuxFrontendMetadata;
+  options: Partial<SendMessageOptions>;
+} {
+  const parsed = parseCommand(command);
+  if (parsed?.type !== "compact") {
+    throw new Error("Not a compact command");
+  }
+
+  const targetWords = parsed.maxOutputTokens ? Math.round(parsed.maxOutputTokens / 1.3) : 2000;
+
+  const messageText = `Summarize this conversation into a compact form for a new Assistant to continue helping the user. Use approximately ${targetWords} words.`;
+
+  const metadata: CmuxFrontendMetadata = {
+    type: "compaction-request",
+    rawCommand: command,
+    parsed: {
+      maxOutputTokens: parsed.maxOutputTokens,
+      continueMessage: parsed.continueMessage,
+    },
+  };
+
+  const isAnthropic = sendMessageOptions.model.startsWith("anthropic:");
+  const options: Partial<SendMessageOptions> = {
+    thinkingLevel: isAnthropic ? "off" : sendMessageOptions.thinkingLevel,
+    toolPolicy: [{ regex_match: "compact_summary", action: "require" }],
+    maxOutputTokens: parsed.maxOutputTokens,
+    mode: "compact" as const,
+  };
+
+  return { messageText, metadata, options };
+}
+
 export const ChatInput: React.FC<ChatInputProps> = ({
   workspaceId,
   onMessageSent,
   onTruncateHistory,
   onProviderConfig,
   onModelChange,
-  onCompactStart,
   disabled = false,
   isCompacting = false,
   editingMessage,
   onCancelEdit,
   canInterrupt = false,
   onReady,
 }) => {
-  const [input, setInput] = usePersistedState(getInputKey(workspaceId), "");
+  const [input, setInput] = usePersistedState(getInputKey(workspaceId), "", { listener: true });
   const [isSending, setIsSending] = useState(false);
   const [showCommandSuggestions, setShowCommandSuggestions] = useState(false);
   const [commandSuggestions, setCommandSuggestions] = useState<SlashSuggestion[]>([]);
@@ -524,8 +565,9 @@ export const ChatInput: React.FC<ChatInputProps> = ({
 
   const handleSend = async () => {
     // Allow sending if there's text or images
-    if ((!input.trim() && imageAttachments.length === 0) || disabled || isSending || isCompacting)
+    if ((!input.trim() && imageAttachments.length === 0) || disabled || isSending || isCompacting) {
       return;
+    }
 
     const messageText = input.trim();
 
@@ -610,41 +652,36 @@ export const ChatInput: React.FC<ChatInputProps> = ({
           setIsSending(true);
 
           try {
-            // Construct message asking for summarization
-            const targetWords = parsed.maxOutputTokens
-              ? Math.round(parsed.maxOutputTokens / 1.3)
-              : 2000;
-            const compactionMessage = `Summarize this conversation into a compact form for a new Assistant to continue helping the user. Use approximately ${targetWords} words.`;
-
-            // Send message with compact_summary tool required and maxOutputTokens in options
-            // Note: Anthropic doesn't support extended thinking with required tool_choice,
-            // so disable thinking for Anthropic models during compaction
-            const isAnthropic = sendMessageOptions.model.startsWith("anthropic:");
+            const {
+              messageText: compactionMessage,
+              metadata,
+              options,
+            } = prepareCompactionMessage(messageText, sendMessageOptions);
+
             const result = await window.api.workspace.sendMessage(workspaceId, compactionMessage, {
               ...sendMessageOptions,
-              thinkingLevel: isAnthropic ? "off" : sendMessageOptions.thinkingLevel,
-              toolPolicy: [{ regex_match: "compact_summary", action: "require" }],
-              maxOutputTokens: parsed.maxOutputTokens, // Pass to model directly
-              mode: "compact" as const, // Allow users to customize compaction behavior via Mode: compact in AGENTS.md
+              ...options,
+              cmuxMetadata: metadata,
+              editMessageId: editingMessage?.id, // Support editing compaction messages
             });
 
             if (!result.success) {
               console.error("Failed to initiate compaction:", result.error);
               setToast(createErrorToast(result.error));
               setInput(messageText); // Restore input on error
             } else {
-              // Notify parent to update continue message state (parent handles storage)
-              if (onCompactStart) {
-                onCompactStart(parsed.continueMessage);
-              }
-
               setToast({
                 id: Date.now().toString(),
                 type: "success",
-                message: parsed.continueMessage
-                  ? "Compaction started. Will continue automatically after completion."
-                  : "Compaction started. AI will summarize the conversation.",
+                message:
+                  metadata.type === "compaction-request" && metadata.parsed.continueMessage
+                    ? "Compaction started. Will continue automatically after completion."
+                    : "Compaction started. AI will summarize the conversation.",
               });
+              // Clear editing state on success
+              if (editingMessage && onCancelEdit) {
+                onCancelEdit();
+              }
             }
           } catch (error) {
             console.error("Compaction error:", error);
@@ -678,10 +715,31 @@ export const ChatInput: React.FC<ChatInputProps> = ({
           mimeType: img.mimeType,
         }));
 
-        const result = await window.api.workspace.sendMessage(workspaceId, messageText, {
+        // When editing a /compact command, regenerate the actual summarization request
+        let actualMessageText = messageText;
+        let cmuxMetadata: CmuxFrontendMetadata | undefined;
+        let compactionOptions = {};
+
+        if (editingMessage && messageText.startsWith("/")) {
+          const parsed = parseCommand(messageText);
+          if (parsed?.type === "compact") {
+            const {
+              messageText: regeneratedText,
+              metadata,
+              options,
+            } = prepareCompactionMessage(messageText, sendMessageOptions);
+            actualMessageText = regeneratedText;
+            cmuxMetadata = metadata;
+            compactionOptions = options;
+          }
+        }
+
+        const result = await window.api.workspace.sendMessage(workspaceId, actualMessageText, {
           ...sendMessageOptions,
+          ...compactionOptions,
           editMessageId: editingMessage?.id,
           imageParts: imageParts.length > 0 ? imageParts : undefined,
+          cmuxMetadata,
         });
 
         if (!result.success) {
@@ -782,7 +840,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
       return `Edit your message... (${formatKeybind(KEYBINDS.CANCEL)} to cancel edit, ${formatKeybind(KEYBINDS.SEND_MESSAGE)} to send)`;
     }
     if (isCompacting) {
-      return "Compacting conversation...";
+      return `Compacting... (${formatKeybind(KEYBINDS.INTERRUPT_STREAM)} to cancel)`;
     }
 
     // Build hints for normal input
@@ -818,7 +876,7 @@ export const ChatInput: React.FC<ChatInputProps> = ({
           onPaste={handlePaste}
           suppressKeys={showCommandSuggestions ? COMMAND_SUGGESTION_KEYS : undefined}
           placeholder={placeholder}
-          disabled={disabled || isSending || isCompacting}
+          disabled={!editingMessage && (disabled || isSending || isCompacting)}
           aria-label={editingMessage ? "Edit your last message" : "Message Claude"}
           aria-autocomplete="list"
           aria-controls={

src/components/Messages/MessageRenderer.tsx

@@ -13,15 +13,23 @@ interface MessageRendererProps {
   onEditUserMessage?: (messageId: string, content: string) => void;
   workspaceId?: string;
   model?: string;
+  isCompacting?: boolean;
 }
 
 // Memoized to prevent unnecessary re-renders when parent (AIView) updates
 export const MessageRenderer = React.memo<MessageRendererProps>(
-  ({ message, className, onEditUserMessage, workspaceId, model }) => {
+  ({ message, className, onEditUserMessage, workspaceId, model, isCompacting }) => {
     // Route based on message type
     switch (message.type) {
       case "user":
-        return <UserMessage message={message} className={className} onEdit={onEditUserMessage} />;
+        return (
+          <UserMessage
+            message={message}
+            className={className}
+            onEdit={onEditUserMessage}
+            isCompacting={isCompacting}
+          />
+        );
       case "assistant":
         return (
           <AssistantMessage message={message} className={className} workspaceId={workspaceId} />

src/components/Messages/UserMessage.tsx

@@ -4,6 +4,7 @@ import type { DisplayedMessage } from "@/types/message";
 import type { ButtonConfig } from "./MessageWindow";
 import { MessageWindow } from "./MessageWindow";
 import { TerminalOutput } from "./TerminalOutput";
+import { formatKeybind, KEYBINDS } from "@/utils/ui/keybinds";
 
 const FormattedContent = styled.pre`
   margin: 0;
@@ -34,9 +35,15 @@ interface UserMessageProps {
   message: DisplayedMessage & { type: "user" };
   className?: string;
   onEdit?: (messageId: string, content: string) => void;
+  isCompacting?: boolean;
 }
 
-export const UserMessage: React.FC<UserMessageProps> = ({ message, className, onEdit }) => {
+export const UserMessage: React.FC<UserMessageProps> = ({
+  message,
+  className,
+  onEdit,
+  isCompacting,
+}) => {
   const [copied, setCopied] = useState(false);
 
   const content = message.content;
@@ -72,6 +79,10 @@ export const UserMessage: React.FC<UserMessageProps> = ({ message, className, on
           {
             label: "Edit",
             onClick: handleEdit,
+            disabled: isCompacting,
+            tooltip: isCompacting
+              ? `Cannot edit while compacting (press ${formatKeybind(KEYBINDS.INTERRUPT_STREAM)} to cancel)`
+              : undefined,
           },
         ]
       : []),