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/components/Messages/InitMessage.tsx

@@ -35,7 +35,7 @@ export const InitMessage = React.memo<InitMessageProps>(({ message, className })
         </div>
       </div>
       {message.lines.length > 0 && (
-        <pre className="m-0 max-h-[120px] overflow-auto whitespace-pre-wrap rounded border border-white/[0.08] bg-black/15 px-2 py-1.5">
+        <pre className="m-0 max-h-[120px] overflow-auto rounded border border-white/[0.08] bg-black/15 px-2 py-1.5 whitespace-pre-wrap">
           {message.lines.join("\n")}
         </pre>
       )}

src/hooks/useWorkspaceManagement.ts

@@ -3,6 +3,7 @@ import type { FrontendWorkspaceMetadata } from "@/types/workspace";
 import type { WorkspaceSelection } from "@/components/ProjectSidebar";
 import type { ProjectConfig } from "@/config";
 import { deleteWorkspaceStorage } from "@/constants/storage";
+import { getWorkspaceStoreForEagerSubscription } from "@/stores/WorkspaceStore";
 
 interface UseWorkspaceManagementProps {
   selectedWorkspace: WorkspaceSelection | null;
@@ -97,7 +98,22 @@ 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 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/services/bashExecutionService.ts

@@ -136,7 +136,7 @@ export class BashExecutionService {
       detached: config.detached ?? true,
     });
 
-    log.debug(`BashExecutionService: Spawned process with PID ${child.pid}`);
+    log.debug(`BashExecutionService: Spawned process with PID ${child.pid ?? "unknown"}`);
 
     // Line-by-line streaming with incremental buffers
     let outBuf = "";
@@ -168,7 +168,7 @@ export class BashExecutionService {
     });
 
     child.on("close", (code: number | null) => {
-      log.debug(`BashExecutionService: Process exited with code ${code}`);
+      log.debug(`BashExecutionService: Process exited with code ${code ?? "unknown"}`);
       // Flush any remaining partial lines
       if (outBuf.trim().length > 0) {
         callbacks.onStdout(outBuf);

src/services/initStateManager.test.ts

@@ -34,9 +34,15 @@ describe("InitStateManager", () => {
       const events: Array<WorkspaceInitEvent & { workspaceId: string }> = [];
 
       // Subscribe to events
-      manager.on("init-start", (event) => events.push(event));
-      manager.on("init-output", (event) => events.push(event));
-      manager.on("init-end", (event) => events.push(event));
+      manager.on("init-start", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
+      manager.on("init-output", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
+      manager.on("init-end", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
 
       // Start init
       manager.startInit(workspaceId, "/path/to/hook");
@@ -103,9 +109,15 @@ describe("InitStateManager", () => {
       const workspaceId = "test-workspace";
       const events: Array<WorkspaceInitEvent & { workspaceId: string }> = [];
 
-      manager.on("init-start", (event) => events.push(event));
-      manager.on("init-output", (event) => events.push(event));
-      manager.on("init-end", (event) => events.push(event));
+      manager.on("init-start", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
+      manager.on("init-output", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
+      manager.on("init-end", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
 
       // Create state
       manager.startInit(workspaceId, "/path/to/hook");
@@ -138,9 +150,15 @@ describe("InitStateManager", () => {
       expect(manager.getInitState(workspaceId)).toBeUndefined();
 
       // Subscribe to events
-      manager.on("init-start", (event) => events.push(event));
-      manager.on("init-output", (event) => events.push(event));
-      manager.on("init-end", (event) => events.push(event));
+      manager.on("init-start", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
+      manager.on("init-output", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
+      manager.on("init-end", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
 
       // Replay from disk
       await manager.replayInit(workspaceId);
@@ -160,9 +178,15 @@ describe("InitStateManager", () => {
       const workspaceId = "nonexistent-workspace";
       const events: Array<WorkspaceInitEvent & { workspaceId: string }> = [];
 
-      manager.on("init-start", (event) => events.push(event));
-      manager.on("init-output", (event) => events.push(event));
-      manager.on("init-end", (event) => events.push(event));
+      manager.on("init-start", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
+      manager.on("init-output", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
+      manager.on("init-end", (event: WorkspaceInitEvent & { workspaceId: string }) =>
+        events.push(event)
+      );
 
       await manager.replayInit(workspaceId);
 

src/services/initStateManager.ts

@@ -19,11 +19,9 @@ export interface InitStatus {
 
 /**
  * In-memory state for active init hooks.
- * Extends InitStatus with event emission tracking.
+ * Currently identical to InitStatus, but kept separate for future extension.
  */
-interface InitHookState extends InitStatus {
-  // No additional fields needed for now, but keeps type separate for future extension
-}
+type InitHookState = InitStatus;
 
 /**
  * InitStateManager - Manages init hook lifecycle with persistence and replay.
@@ -66,8 +64,8 @@ export class InitStateManager extends EventEmitter {
    */
   private serializeInitEvents(
     state: InitHookState & { workspaceId?: string }
-  ): (WorkspaceInitEvent & { workspaceId: string })[] {
-    const events: (WorkspaceInitEvent & { workspaceId: string })[] = [];
+  ): Array<WorkspaceInitEvent & { workspaceId: string }> {
+    const events: Array<WorkspaceInitEvent & { workspaceId: string }> = [];
     const workspaceId = state.workspaceId ?? "unknown";
 
     // Emit init-start

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.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from "@jest/globals";
-import * as fs from "fs";
+import * as fs from "fs/promises";
 import * as path from "path";
 import { EventStore } from "./eventStore";
 import type { Config } from "@/config";
@@ -42,10 +42,12 @@ describe("EventStore", () => {
     emittedEvents.push(event);
   };
 
-  beforeEach(() => {
+  beforeEach(async () => {
     // Create test session directory
-    if (!fs.existsSync(testSessionDir)) {
-      fs.mkdirSync(testSessionDir, { recursive: true });
+    try {
+      await fs.access(testSessionDir);
+    } catch {
+      await fs.mkdir(testSessionDir, { recursive: true });
     }
 
     mockConfig = {
@@ -59,10 +61,13 @@ describe("EventStore", () => {
     store = new EventStore(mockConfig, testFilename, serializeState, emitEvent, "TestStore");
   });
 
-  afterEach(() => {
+  afterEach(async () => {
     // Clean up test files
-    if (fs.existsSync(testSessionDir)) {
-      fs.rmSync(testSessionDir, { recursive: true, force: true });
+    try {
+      await fs.access(testSessionDir);
+      await fs.rm(testSessionDir, { recursive: true, force: true });
+    } catch {
+      // Directory doesn't exist, nothing to clean up
     }
   });
 
@@ -119,11 +124,15 @@ describe("EventStore", () => {
       // Verify file exists
       const workspaceDir = path.join(testSessionDir, testWorkspaceId);
       const filePath = path.join(workspaceDir, testFilename);
-      expect(fs.existsSync(filePath)).toBe(true);
+      try {
+        await fs.access(filePath);
+      } catch {
+        throw new Error(`File ${filePath} does not exist`);
+      }
 
       // Verify content
-      const content = fs.readFileSync(filePath, "utf-8");
-      const parsed = JSON.parse(content);
+      const content = await fs.readFile(filePath, "utf-8");
+      const parsed = JSON.parse(content) as TestState;
       expect(parsed).toEqual(state);
     });
 
@@ -240,4 +249,3 @@ describe("EventStore", () => {
     });
   });
 });
-

src/utils/eventStore.ts

@@ -1,4 +1,3 @@
-import { EventEmitter } from "events";
 import { SessionFileManager } from "@/utils/sessionFile";
 import type { Config } from "@/config";
 import { log } from "@/services/log";
@@ -147,8 +146,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 };
 
@@ -196,4 +193,3 @@ export class EventStore<TState, TEvent> {
  *
  * See InitStateManager refactor (this PR) for reference implementation.
  */
-