refactor(hooks): split session events into individual typed events

Major changes:
- Replace monolithic SessionEvent with reason discriminator with individual
  event types: session_start, session_before_switch, session_switch,
  session_before_new, session_new, session_before_branch, session_branch,
  session_before_compact, session_compact, session_shutdown
- Each event has dedicated result type (SessionBeforeSwitchResult, etc.)
- HookHandler type now allows bare return statements (void in return type)
- HookAPI.on() has proper overloads for each event with correct typing

Additional fixes:
- AgentSession now always subscribes to agent in constructor (was only
  subscribing when external subscribe() called, breaking internal handlers)
- Standardize on undefined over null throughout codebase
- HookUIContext methods return undefined instead of null
- SessionManager methods return undefined instead of null
- Simplify hook exports to 'export type * from types.js'
- Add detailed JSDoc for skipConversationRestore vs cancel
- Fix createBranchedSession to rebuild index in persist mode
- newSession() now returns the session file path

Updated all example hooks, tests, and emission sites to use new event types.

packages/coding-agent/src/core/export-html.ts

@@ -121,7 +121,7 @@ function resolveColorValue(
 }
 
 /** Load theme JSON from built-in or custom themes directory. */
-function loadThemeJson(name: string): ThemeJson | null {
+function loadThemeJson(name: string): ThemeJson | undefined {
 	// Try built-in themes first
 	const themesDir = getThemesDir();
 	const builtinPath = path.join(themesDir, `${name}.json`);
@@ -129,7 +129,7 @@ function loadThemeJson(name: string): ThemeJson | null {
 		try {
 			return JSON.parse(readFileSync(builtinPath, "utf-8")) as ThemeJson;
 		} catch {
-			return null;
+			return undefined;
 		}
 	}
 
@@ -140,11 +140,11 @@ function loadThemeJson(name: string): ThemeJson | null {
 		try {
 			return JSON.parse(readFileSync(customPath, "utf-8")) as ThemeJson;
 		} catch {
-			return null;
+			return undefined;
 		}
 	}
 
-	return null;
+	return undefined;
 }
 
 /** Build complete theme colors object, resolving theme JSON values against defaults. */
@@ -831,7 +831,9 @@ function formatMessage(
 
 	switch (message.role) {
 		case "bashExecution": {
-			const isError = message.cancelled || (message.exitCode !== 0 && message.exitCode !== null);
+			const isError =
+				message.cancelled ||
+				(message.exitCode !== 0 && message.exitCode !== null && message.exitCode !== undefined);
 
 			html += `<div class="tool-execution user-bash${isError ? " user-bash-error" : ""}">`;
 			html += timestampHtml;
@@ -844,7 +846,7 @@ function formatMessage(
 
 			if (message.cancelled) {
 				html += `<div class="bash-status warning">(cancelled)</div>`;
-			} else if (message.exitCode !== 0 && message.exitCode !== null) {
+			} else if (message.exitCode !== 0 && message.exitCode !== null && message.exitCode !== undefined) {
 				html += `<div class="bash-status error">(exit ${message.exitCode})</div>`;
 			}
 
@@ -1020,7 +1022,7 @@ function generateHtml(data: ParsedSessionData, filename: string, colors: ThemeCo
 	const lastModelInfo = lastProvider ? `${lastProvider}/${lastModel}` : lastModel;
 
 	const contextWindow = data.contextWindow || 0;
-	const contextPercent = contextWindow > 0 ? ((contextTokens / contextWindow) * 100).toFixed(1) : null;
+	const contextPercent = contextWindow > 0 ? ((contextTokens / contextWindow) * 100).toFixed(1) : undefined;
 
 	let messagesHtml = "";
 	for (const event of data.sessionEvents) {