🤖 feat: idle compaction for inactive workspaces (#1160)

## Summary

Automatically compacts workspaces that have been inactive for a
configurable period. Runs eligibility checks hourly after an initial
60-second delay on startup.

Closes #714.

## Configuration

- **Per-project setting**: `idleCompactionHours` (null = disabled,
number = hours threshold)
- **UI**: Settings → Project → Idle Compaction (checkbox + hours input)
- **Slash command**: `/idle <hours>` or `/idle off`

## UX Invariants

Two critical behaviors to preserve sidebar ordering and provide
feedback:

1. **Compaction preserves recency** — Idle compaction does not make a
workspace appear "recently used" in the sidebar. The
`computeRecencyFromMessages()` function calculates recency from the last
user message or last user-initiated compaction, explicitly filtering out
idle compaction requests.

2. **Sidebar shows status during compaction** — The compaction request
includes `displayStatus` in metadata, which the
`StreamingMessageAggregator` reads to show "Idle Compacting..." in the
sidebar. Status clears when the `idleCompacted: true` summary message
arrives.

## Eligibility Checks

A workspace is eligible for idle compaction when:
- Has at least one message
- Idle time ≥ configured threshold (based on
`computeRecencyFromMessages`)
- Not currently streaming
- Not already compacted (last message is not a compaction summary)
- Last message is not from user (not awaiting a response)

## Visual Indicators

- Regular compaction badge: `📦 compacted`
- Idle compaction badge: `💤📦 idle-compacted`

## Architecture

```
Backend (hourly check)                   Frontend
──────────────────────                   ────────
IdleCompactionService.checkAllWorkspaces()
    │
    ├─► checkEligibility()
    │
    └─► emitIdleCompactionNeeded(workspaceId)
              │
              ▼
        WorkspaceService → session stream
              │
              ══════════════════════════════════════════════►
                                                              │
                              useIdleCompactionHandler hook ◄─┘
                                   │
                                   ▼
                              executeCompaction({ source: "idle-compaction" })
                                   │
                                   │ Adds: model, gateway, thinkingLevel
                                   │ (from localStorage)
                                   ▼
                              CompactionHandler.performCompaction()
                                   │
                                   └─► recency = computeRecencyFromMessages()
                                       (preserves original timestamp)
```

### Why the frontend relay?

The backend cannot currently construct compaction requests because it
lacks access to user preferences:
- **Preferred compaction model** — stored in localStorage
- **Gateway routing** — which models should use the mux gateway vs
direct API

These preferences live in the browser and are assembled by
`buildSendMessageOptions()` when sending any message. Until we persist
these preferences to backend-accessible storage, the frontend must relay
compaction requests.

## Known Limitation

**Requires frontend to be running.** Since compaction requests are
relayed through the frontend, a standalone `mux server` instance cannot
perform idle compaction. This will be resolved once user preferences are
persisted to the backend.

## Future: Backend-Only Architecture

Once compaction preferences are persisted to backend-accessible storage
(per-workspace or per-project config file), the entire flow can happen
on the backend:

```
Backend (hourly check)
──────────────────────
IdleCompactionService.checkAllWorkspaces()
    │
    ├─► checkEligibility()
    │
    └─► WorkspaceService.sendMessage() directly
              │
              │ Reads: model, gateway, thinkingLevel
              │ (from persisted config)
              ▼
        CompactionHandler.performCompaction()
```

**Migration path:**
1. Persist compaction preferences (model, gateway, thinking level) to
backend config
2. Have `IdleCompactionService` call `WorkspaceService.sendMessage()`
directly
3. Remove `useIdleCompactionHandler` hook (~40 lines) and
`idle-compaction-needed` event type

This will enable standalone `mux server` deployments to perform
auto-compaction without any frontend involvement.

---
_Generated with `mux` • Model: `anthropic:claude-opus-4-5` • Thinking:
`high`_

Author: ethanndickson

.storybook/mocks/orpc.ts

@@ -188,6 +188,10 @@ export function createMockORPCClient(options: MockORPCClientOptions = {}): APICl
         setEnabled: async () => ({ success: true, data: undefined }),
         setToolAllowlist: async () => ({ success: true, data: undefined }),
       },
+      idleCompaction: {
+        get: async () => ({ success: true, hours: null }),
+        set: async () => ({ success: true }),
+      },
     },
     workspace: {
       list: async () => workspaces,

src/browser/components/AIView.tsx

@@ -58,6 +58,7 @@ import { useProviderOptions } from "@/browser/hooks/useProviderOptions";
 import { useAutoCompactionSettings } from "../hooks/useAutoCompactionSettings";
 import { useSendMessageOptions } from "@/browser/hooks/useSendMessageOptions";
 import { useForceCompaction } from "@/browser/hooks/useForceCompaction";
+import { useIdleCompactionHandler } from "@/browser/hooks/useIdleCompactionHandler";
 import { useAPI } from "@/browser/contexts/API";
 import { useReviews } from "@/browser/hooks/useReviews";
 import { ReviewsBanner } from "./ReviewsBanner";
@@ -202,6 +203,9 @@ const AIViewInner: React.FC<AIViewProps> = ({
     onTrigger: handleForceCompaction,
   });
 
+  // Idle compaction - trigger compaction when backend signals workspace has been idle
+  useIdleCompactionHandler({ api });
+
   // Auto-retry state - minimal setter for keybinds and message sent handler
   // RetryBarrier manages its own state, but we need this for interrupt keybind
   const [, setAutoRetry] = usePersistedState<boolean>(

src/browser/components/ChatInput/index.tsx

@@ -984,6 +984,58 @@ const ChatInputInner: React.FC<ChatInputProps> = (props) => {
           }
           return;
         }
+        // Handle /idle command
+        if (parsed.type === "idle-compaction") {
+          if (!api) {
+            setToast({
+              id: Date.now().toString(),
+              type: "error",
+              message: "Not connected to server",
+            });
+            return;
+          }
+          if (!selectedWorkspace?.projectPath) {
+            setToast({
+              id: Date.now().toString(),
+              type: "error",
+              message: "No project selected",
+            });
+            return;
+          }
+          setInput(""); // Clear input immediately
+
+          try {
+            const result = await api.projects.idleCompaction.set({
+              projectPath: selectedWorkspace.projectPath,
+              hours: parsed.hours,
+            });
+
+            if (!result.success) {
+              setToast({
+                id: Date.now().toString(),
+                type: "error",
+                message: result.error ?? "Failed to update setting",
+              });
+              setInput(messageText); // Restore input on error
+            } else {
+              setToast({
+                id: Date.now().toString(),
+                type: "success",
+                message: parsed.hours
+                  ? `Idle compaction set to ${parsed.hours} hours`
+                  : "Idle compaction disabled",
+              });
+            }
+          } catch (error) {
+            setToast({
+              id: Date.now().toString(),
+              type: "error",
+              message: error instanceof Error ? error.message : "Failed to update setting",
+            });
+            setInput(messageText); // Restore input on error
+          }
+          return;
+        }
       }
 
       // Regular message - send directly via API

src/browser/components/Messages/AssistantMessage.tsx

@@ -1,4 +1,4 @@
-import { COMPACTED_EMOJI } from "@/common/constants/ui";
+import { COMPACTED_EMOJI, IDLE_COMPACTED_EMOJI } from "@/common/constants/ui";
 import { useCopyToClipboard } from "@/browser/hooks/useCopyToClipboard";
 import { useStartHere } from "@/browser/hooks/useStartHere";
 import type { DisplayedMessage } from "@/common/types/message";
@@ -109,13 +109,16 @@ export const AssistantMessage: React.FC<AssistantMessageProps> = ({
   const renderLabel = () => {
     const modelName = message.model;
     const isCompacted = message.isCompacted;
+    const isIdleCompacted = message.isIdleCompacted;
 
     return (
       <div className="flex items-center gap-2">
         {modelName && <ModelDisplay modelString={modelName} />}
         {isCompacted && (
           <span className="text-plan-mode bg-plan-mode/10 rounded-sm px-1.5 py-0.5 text-[10px] font-medium uppercase">
-            {COMPACTED_EMOJI} compacted
+            {isIdleCompacted
+              ? `${IDLE_COMPACTED_EMOJI} idle-compacted`
+              : `${COMPACTED_EMOJI} compacted`}
           </span>
         )}
       </div>

src/browser/components/Settings/sections/ProjectSettingsSection.tsx

@@ -195,6 +195,17 @@ export const ProjectSettingsSection: React.FC = () => {
   const [editing, setEditing] = useState<{ name: string; command: string } | null>(null);
   const [savingEdit, setSavingEdit] = useState(false);
 
+  // Idle compaction state
+  const [idleHours, setIdleHours] = useState<number | null>(null);
+  const [idleHoursInput, setIdleHoursInput] = useState<string>("");
+  const [savingIdleHours, setSavingIdleHours] = useState(false);
+
+  // Sync input field when idleHours loads/changes
+  // Show "24" as default placeholder when disabled
+  useEffect(() => {
+    setIdleHoursInput(idleHours?.toString() ?? "24");
+  }, [idleHours]);
+
   // Set default project when projects load
   useEffect(() => {
     if (projectList.length > 0 && !selectedProject) {
@@ -206,11 +217,15 @@ export const ProjectSettingsSection: React.FC = () => {
     if (!api || !selectedProject) return;
     setLoading(true);
     try {
-      const result = await api.projects.mcp.list({ projectPath: selectedProject });
-      setServers(result ?? {});
+      const [mcpResult, idleResult] = await Promise.all([
+        api.projects.mcp.list({ projectPath: selectedProject }),
+        api.projects.idleCompaction.get({ projectPath: selectedProject }),
+      ]);
+      setServers(mcpResult ?? {});
+      setIdleHours(idleResult.hours);
       setError(null);
     } catch (err) {
-      setError(err instanceof Error ? err.message : "Failed to load MCP servers");
+      setError(err instanceof Error ? err.message : "Failed to load project settings");
     } finally {
       setLoading(false);
     }
@@ -380,6 +395,29 @@ export const ProjectSettingsSection: React.FC = () => {
     }
   }, [api, selectedProject, editing, refresh, clearTestResult]);
 
+  const handleIdleHoursChange = useCallback(
+    async (hours: number | null) => {
+      if (!api || !selectedProject) return;
+      setSavingIdleHours(true);
+      try {
+        const result = await api.projects.idleCompaction.set({
+          projectPath: selectedProject,
+          hours,
+        });
+        if (result.success) {
+          setIdleHours(hours);
+        } else {
+          setError(result.error ?? "Failed to update idle compaction setting");
+        }
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Failed to update idle compaction setting");
+      } finally {
+        setSavingIdleHours(false);
+      }
+    },
+    [api, selectedProject]
+  );
+
   if (projectList.length === 0) {
     return (
       <div className="flex flex-col items-center justify-center py-12 text-center">
@@ -417,8 +455,60 @@ export const ProjectSettingsSection: React.FC = () => {
         </p>
       </div>
 
+      {/* Idle Compaction */}
+      <div className="space-y-4">
+        <div>
+          <h3 className="font-medium">Idle Compaction</h3>
+          <p className="text-muted-foreground text-xs">
+            Automatically compact workspaces after a period of inactivity to provide helpful
+            summaries when returning
+          </p>
+        </div>
+
+        <div className="flex items-center gap-3">
+          <label className="flex items-center gap-2">
+            <input
+              type="checkbox"
+              checked={idleHours !== null}
+              onChange={(e) => void handleIdleHoursChange(e.target.checked ? 24 : null)}
+              disabled={savingIdleHours}
+              className="accent-accent h-4 w-4 rounded"
+            />
+            <span className="text-sm">Enable idle compaction</span>
+          </label>
+          {savingIdleHours && <Loader2 className="text-muted-foreground h-4 w-4 animate-spin" />}
+        </div>
+
+        <div
+          className={cn(
+            "flex items-center gap-2",
+            idleHours === null && "pointer-events-none opacity-50"
+          )}
+        >
+          <span className="text-sm">Compact after</span>
+          <input
+            type="number"
+            min={1}
+            value={idleHoursInput}
+            onChange={(e) => setIdleHoursInput(e.target.value)}
+            onBlur={(e) => {
+              const val = parseInt(e.target.value, 10);
+              if (!isNaN(val) && val >= 1 && val !== idleHours) {
+                void handleIdleHoursChange(val);
+              } else if (e.target.value === "" || isNaN(val) || val < 1) {
+                // Reset to current value on invalid input
+                setIdleHoursInput(idleHours?.toString() ?? "24");
+              }
+            }}
+            disabled={savingIdleHours || idleHours === null}
+            className="border-border-medium bg-secondary/30 focus:ring-accent w-20 rounded-md border px-2 py-1 text-sm focus:ring-1 focus:outline-none disabled:cursor-not-allowed"
+          />
+          <span className="text-sm">hours of inactivity</span>
+        </div>
+      </div>
+
       {/* MCP Servers header */}
-      <div className="flex items-center justify-between">
+      <div className="border-border-medium flex items-center justify-between border-t pt-6">
         <div>
           <h3 className="font-medium">MCP Servers</h3>
           <p className="text-muted-foreground text-xs">