docs: Add init hooks documentation

Added user-facing documentation for .cmux/init hooks under Workspaces section.

Covers:
- Basic example with setup instructions
- Behavior (runs once, streams output, non-blocking, exit codes)
- Common use cases (deps, builds, codegen, services)
- Output display (banner with status and logs)
- Idempotency considerations

Follows docs/STYLE.md guidelines:
- Assumes technical competence
- Focuses on non-obvious behavior (non-blocking, idempotency)
- Concise and practical examples
- No obvious details

fix: Subscribe to workspace immediately after creation for real-time init events

When a workspace is created, the init hook starts running immediately in
the background. However, the frontend previously waited for React effects
to process the workspace metadata update before subscribing to events.

This created a race condition where early init hook output lines were
emitted before the frontend subscribed, causing them to be dropped at the
WebSocket layer (only subscribed clients receive messages).

Although these events would be replayed when subscription finally happened,
this broke the real-time streaming UX - users saw all output appear at once
in a batch instead of streaming line-by-line.

Fix by calling workspaceStore.addWorkspace() immediately after receiving
the workspace creation response, before React effects run. This ensures
the frontend is subscribed before (or very quickly after) the init hook
starts emitting events, preserving the real-time streaming experience.

Also export getWorkspaceStoreForEagerSubscription() to allow non-React
code to access the singleton store instance for imperative operations.

Author: ammar-agent

docs/SUMMARY.md

@@ -10,6 +10,7 @@
 
 - [Workspaces](./workspaces.md)
   - [Forking](./fork.md)
+  - [Init Hooks](./init-hooks.md)
 - [Models](./models.md)
 - [Keyboard Shortcuts](./keybinds.md)
   - [Vim Mode](./vim-mode.md)

docs/init-hooks.md

@@ -0,0 +1,48 @@
+# Init Hooks
+
+Add a `.cmux/init` executable script to your project root to run commands when creating new workspaces.
+
+## Example
+
+```bash
+#!/bin/bash
+set -e
+
+bun install
+bun run build
+```
+
+Make it executable:
+
+```bash
+chmod +x .cmux/init
+```
+
+## Behavior
+
+- **Runs once** per workspace on creation
+- **Streams output** to the workspace UI in real-time
+- **Non-blocking** - workspace is immediately usable, even while hook runs
+- **Exit codes preserved** - failures are logged but don't prevent workspace usage
+
+The init script runs in the workspace directory with the workspace's environment.
+
+## Use Cases
+
+- Install dependencies (`npm install`, `bun install`, etc.)
+- Run build steps
+- Generate code or configs
+- Set up databases or services
+- Warm caches
+
+## Output
+
+Init output appears in a banner at the top of the workspace. Click to expand/collapse the log. The banner shows:
+- Script path (`.cmux/init`)
+- Status (running, success, or exit code on failure)
+- Full stdout/stderr output
+
+## Idempotency
+
+The hook runs every time you create a workspace, even if you delete and recreate with the same name. Make your script idempotent if you're modifying shared state.
+

src/hooks/useWorkspaceManagement.ts

@@ -97,7 +97,23 @@ export function useWorkspaceManagement({
       const loadedProjects = new Map<string, ProjectConfig>(projectsList);
       onProjectsUpdate(loadedProjects);
 
-      // Reload workspace metadata to get the new workspace ID
+      // OPTIMIZATION: Subscribe immediately to workspace to receive init hook events in real-time
+      // Without this, we'd wait for loadWorkspaceMetadata() + React effect, during which
+      // early init hook events would be emitted but dropped (not subscribed yet).
+      // Those events would then be replayed in a batch when subscription finally happens,
+      // losing the real-time streaming UX.
+      const { getWorkspaceStoreForEagerSubscription } = await import("@/stores/WorkspaceStore");
+      const workspaceStore = getWorkspaceStoreForEagerSubscription();
+      workspaceStore.addWorkspace({
+        id: result.metadata.id,
+        name: result.metadata.name,
+        projectName: result.metadata.projectName,
+        projectPath: result.metadata.projectPath,
+        namedWorkspacePath: result.metadata.namedWorkspacePath,
+        createdAt: result.metadata.createdAt,
+      });
+
+      // Reload workspace metadata to get the new workspace ID (for consistency with other state)
       await loadWorkspaceMetadata();
 
       // Return the new workspace selection

src/stores/WorkspaceStore.ts

@@ -1024,6 +1024,15 @@ function getStoreInstance(): WorkspaceStore {
   return storeInstance;
 }
 
+/**
+ * Get the WorkspaceStore instance for eager workspace subscription.
+ * Used by useWorkspaceManagement to subscribe to new workspaces immediately
+ * after creation, before React effects run.
+ */
+export function getWorkspaceStoreForEagerSubscription(): WorkspaceStore {
+  return getStoreInstance();
+}
+
 /**
  * Hook to get state for a specific workspace.
  * Only re-renders when THIS workspace's state changes.

src/utils/eventStore.ts

@@ -147,8 +147,6 @@ export class EventStore<TState, TEvent> {
       state = diskState;
     }
 
-    log.debug(`[${this.storeName}] Replaying events for ${workspaceId}`);
-
     // Augment state with context for serialization
     const augmentedState = { ...state, ...context };