fix: overhaul session lifecycle to fix crashes, message loss, and duplicate notifications

Root cause: ClaudeProcess.isReady() returned `alive` (set immediately on spawn),
so sendInput() bypassed readiness checks and sent messages before the process
had initialized.  This caused message loss, process crashes, infinite restart
loops, and broken session naming.

Five fixes:

1. ClaudeProcess.isReady() now requires system_init to have been received,
   not just process alive — fulfills the CodingProcess interface contract.

2. sendInput() restructured: readiness check applies to ALL paths, not just
   the auto-start branch.  Messages are always queued via waitForReady() when
   the process hasn't initialized yet.

3. Lifetime restart cap (10 total) prevents infinite restart loops.  Previously
   the 5-min cooldown reset allowed sessions to restart hundreds of times.

4. Duplicate "Session started" eliminated: frontend no longer shows a message
   for claude_started; only the system_init (with model info) serves as the
   "session ready" notification.

5. Session naming env includes XDG_* dirs for proper Claude CLI config/auth
   resolution (was stripped to just PATH+HOME).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: alari76

server/claude-process.ts

@@ -115,6 +115,13 @@ export class ClaudeProcess extends EventEmitter<ClaudeProcessEvents> implements
    */
   private _receivedOutput = false
 
+  /**
+   * Set to true once the process emits a system init event (type=system, subtype=init).
+   * Until this fires, the process is still loading configs/hooks and is not ready
+   * to process user messages reliably.
+   */
+  private _systemInitReceived = false
+
   // Grouped streaming state — reset per content block
   private thinking: ThinkingState = { active: false, text: '', summaryEmitted: false }
   private tool: ToolState = { name: null, input: '' }
@@ -325,6 +332,7 @@ export class ClaudeProcess extends EventEmitter<ClaudeProcessEvents> implements
       case 'system':
         if (event.subtype === 'init') {
           this.sessionId = (event as ClaudeSystemInit).session_id || this.sessionId
+          this._systemInitReceived = true
           const model = ('model' in event ? (event as Record<string, unknown>).model : 'unknown') as string
           this.emit('system_init', model)
         }
@@ -736,8 +744,9 @@ export class ClaudeProcess extends EventEmitter<ClaudeProcessEvents> implements
   }
 
   isReady(): boolean {
-    // Claude CLI stdin is always buffered — ready as soon as alive
-    return this.alive
+    // Ready only after system_init has been received, proving the process
+    // has finished loading configs/hooks and is accepting user messages.
+    return this.alive && this._systemInitReceived
   }
 
   getSessionId(): string {

server/prompt-router.test.ts

@@ -51,6 +51,7 @@ function makeSession(overrides: Partial<Session> = {}): Session {
     _apiRetryCount: 0,
     _processGeneration: 0,
     _noOutputExitCount: 0,
+    _lifetimeRestarts: 0,
     _lastActivityAt: Date.now(),
     planManager: makePlanManager() as any,
     ...overrides,

server/session-lifecycle.test.ts

@@ -87,6 +87,7 @@ function makeSession(overrides: Partial<Session> = {}): Session {
     _apiRetryCount: 0,
     _processGeneration: 0,
     _noOutputExitCount: 0,
+    _lifetimeRestarts: 0,
     _lastActivityAt: Date.now(),
     planManager: makePlanManager() as any,
     ...overrides,

server/session-lifecycle.ts

@@ -343,6 +343,7 @@ export class SessionLifecycle {
       stoppedByUser: session._stoppedByUser || sessionConflict,
       exitCode: code,
       exitSignal: signal,
+      lifetimeRestarts: session._lifetimeRestarts,
     })
 
     if (action.kind === 'non_retryable') {
@@ -377,6 +378,7 @@ export class SessionLifecycle {
     if (action.kind === 'restart') {
       session.restartCount = action.updatedCount
       session.lastRestartAt = action.updatedLastRestartAt
+      session._lifetimeRestarts = action.updatedLifetimeCount
 
       for (const listener of this.deps.exitListeners) {
         try { listener(sessionId, code, signal, true) } catch { /* listener error */ }

server/session-manager.ts

@@ -304,6 +304,7 @@ export class SessionManager {
       _namingAttempts: 0,
       _processGeneration: 0,
       _noOutputExitCount: 0,
+      _lifetimeRestarts: 0,
       isProcessing: false,
       pendingControlRequests: new Map(),
       pendingToolApprovals: new Map(),
@@ -900,11 +901,10 @@ export class SessionManager {
 
   private onSystemInit(cp: CodingProcess, session: Session, model: string): void {
     session.claudeSessionId = cp.getSessionId()
-    // Only show model message on first init or when model actually changes
-    if (!session._lastReportedModel || session._lastReportedModel !== model) {
-      session._lastReportedModel = model
-      this.broadcastAndHistory(session, { type: 'system_message', subtype: 'init', text: `Model: ${model}`, model })
-    }
+    session._lastReportedModel = model
+    // Always broadcast — this is the single "session is ready" notification.
+    // The text includes the model so the user knows which model is active.
+    this.broadcastAndHistory(session, { type: 'system_message', subtype: 'init', text: `Model: ${model}`, model })
   }
 
   private onTextEvent(session: Session, sessionId: string, text: string): void {
@@ -1104,66 +1104,30 @@ export class SessionManager {
     // Reset stopped-by-user flag so idle-reaped sessions can auto-start
     session._stoppedByUser = false
 
+    // --- Phase 1: ensure process is alive ---
     if (!session.claudeProcess?.isAlive()) {
       // Race guard: prevent concurrent startClaude calls when multiple sendInput
       // requests arrive for an inactive session
       if (session._isStarting) return
       session._isStarting = true
       // Claude not running (e.g. after server restart or idle reap) — auto-start first.
-      // Claude CLI in -p mode waits for first input before emitting init,
-      // so we write directly to the stdin pipe buffer (no waiting for init).
       try {
         this.startClaude(sessionId)
       } finally {
         session._isStarting = false
       }
+    }
 
-      // If we have a saved claudeSessionId, Claude CLI resumes with full
-      // conversation history from its own session storage — no need for our
-      // lossy 4000-char context summary. Only fall back to buildSessionContext
-      // for sessions without a saved Claude session ID.
-      if (!session.claudeSessionId) {
-        const context = this.buildSessionContext(session)
-        if (context) {
-          const combined = context + '\n\n' + data
-          session._lastUserInput = combined
-          session._lastUserInputAt = Date.now()
-          if (!session._namingUserInput) session._namingUserInput = data
-          session._apiRetry.count = 0
-          if (!session.isProcessing) {
-            session.isProcessing = true
-            this._globalBroadcast?.({ type: 'sessions_updated' })
-          }
-          if (session.claudeProcess && !session.claudeProcess.isReady()) {
-            void this.waitForReady(sessionId).then((ready) => {
-              if (ready) session.claudeProcess?.sendMessage(combined)
-              // If not ready (process exited), message stays in _lastUserInput
-              // and will be re-sent on auto-restart
-            })
-          } else {
-            session.claudeProcess?.sendMessage(combined)
-          }
-          return
-        }
-      }
+    // --- Phase 2: determine message content (with context injection if needed) ---
+    let messageToSend = data
 
-      // Process just started — if not ready yet (OpenCode needs server init),
-      // queue the message via waitForReady.
-      if (session.claudeProcess && !session.claudeProcess.isReady()) {
-        session._lastUserInput = data
-        session._lastUserInputAt = Date.now()
-        if (!session._namingUserInput) session._namingUserInput = data
-        session._apiRetry.count = 0
-        if (!session.isProcessing) {
-          session.isProcessing = true
-          this._globalBroadcast?.({ type: 'sessions_updated' })
-        }
-        void this.waitForReady(sessionId).then((ready) => {
-          if (ready) session.claudeProcess?.sendMessage(data)
-          // If not ready (process exited), message stays in _lastUserInput
-          // and will be re-sent on auto-restart
-        })
-        return
+    // If we auto-started above and have no saved claudeSessionId, Claude CLI
+    // starts a fresh session without conversation history.  Inject a context
+    // summary so the new process has awareness of prior conversation.
+    if (!session.claudeSessionId) {
+      const context = this.buildSessionContext(session)
+      if (context) {
+        messageToSend = context + '\n\n' + data
       }
     }
 
@@ -1175,15 +1139,25 @@ export class SessionManager {
       this.retrySessionNamingOnInteraction(sessionId)
     }
 
-    session._lastUserInput = data
+    session._lastUserInput = messageToSend
     session._lastUserInputAt = Date.now()
     if (!session._namingUserInput) session._namingUserInput = data
     session._apiRetry.count = 0
     if (!session.isProcessing) {
       session.isProcessing = true
       this._globalBroadcast?.({ type: 'sessions_updated' })
     }
-    session.claudeProcess?.sendMessage(data)
+
+    // --- Phase 3: send, waiting for readiness if needed ---
+    if (session.claudeProcess && !session.claudeProcess.isReady()) {
+      void this.waitForReady(sessionId).then((ready) => {
+        if (ready) session.claudeProcess?.sendMessage(messageToSend)
+        // If not ready (process exited), message stays in _lastUserInput
+        // and will be re-sent on auto-restart
+      })
+    } else {
+      session.claudeProcess?.sendMessage(messageToSend)
+    }
   }
 
   /**

server/session-naming.ts

@@ -26,14 +26,33 @@ export interface SessionNamingDeps {
   rename(sessionId: string, newName: string): boolean
 }
 
+/** Build a minimal env for claude -p that includes auth/config paths
+ *  without leaking the full parent env (e.g. CODEKIN_* session vars). */
+function buildNamingEnv(): Record<string, string> {
+  const env: Record<string, string> = {}
+  // Core paths
+  if (process.env.PATH) env.PATH = process.env.PATH
+  if (process.env.HOME) env.HOME = process.env.HOME
+  // XDG dirs — Claude CLI uses these for config/credential resolution
+  for (const key of ['XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME', 'XDG_CACHE_HOME']) {
+    if (process.env[key]) env[key] = process.env[key]!
+  }
+  // SHELL and TERM for proper subprocess behavior
+  if (process.env.SHELL) env.SHELL = process.env.SHELL
+  if (process.env.TERM) env.TERM = process.env.TERM
+  // Suppress Node.js warnings in child
+  env.NODE_NO_WARNINGS = '1'
+  return env
+}
+
 /** Generate a session name by spawning `claude -p` in one-shot mode. */
 function generateNameViaCLI(prompt: string): Promise<string> {
   return new Promise((resolve, reject) => {
     // --max-turns 2: one turn to receive/process the prompt, one to reply with the name.
     // Using 1 would sometimes cause the CLI to exit before producing output.
     const proc = spawn(CLAUDE_BINARY, ['-p', '--max-turns', '2', '--model', 'haiku'], {
       stdio: ['pipe', 'pipe', 'pipe'],
-      env: { PATH: process.env.PATH, HOME: process.env.HOME },
+      env: buildNamingEnv(),
     })
 
     let stdout = ''

server/session-persistence.ts

@@ -135,6 +135,7 @@ export class SessionPersistence {
           _namingAttempts: 0,
           _processGeneration: 0,
           _noOutputExitCount: 0,
+          _lifetimeRestarts: 0,
           isProcessing: false,
           pendingControlRequests: new Map(),
           pendingToolApprovals: new Map(),

server/session-restart-scheduler.ts

@@ -6,10 +6,14 @@
  * Returns an action descriptor that the caller (SessionManager) executes.
  */
 
-/** Max auto-restart attempts before requiring manual intervention. */
+/** Max auto-restart attempts per cooldown window before pausing. */
 const MAX_RESTARTS = 3
-/** Window after which the restart counter resets (5 minutes). */
+/** Window after which the per-window restart counter resets (5 minutes). */
 const RESTART_COOLDOWN_MS = 5 * 60 * 1000
+/** Hard cap on total lifetime restarts.  Once reached, the session stops
+ *  permanently regardless of cooldown windows.  Prevents sessions from
+ *  restarting indefinitely (3 per window × many windows = hundreds). */
+const MAX_LIFETIME_RESTARTS = 10
 /** Delay between crash and auto-restart attempt. */
 const RESTART_DELAY_MS = 2000
 
@@ -30,12 +34,14 @@ export interface RestartState {
   exitCode?: number | null
   /** Signal that killed the process, if any. */
   exitSignal?: string | null
+  /** Total number of restarts over the entire session lifetime. */
+  lifetimeRestarts?: number
 }
 
 export type RestartAction =
   | { kind: 'stopped_by_user' }
   | { kind: 'non_retryable'; exitCode: number }
-  | { kind: 'restart'; attempt: number; maxAttempts: number; delayMs: number; updatedCount: number; updatedLastRestartAt: number }
+  | { kind: 'restart'; attempt: number; maxAttempts: number; delayMs: number; updatedCount: number; updatedLastRestartAt: number; updatedLifetimeCount: number }
   | { kind: 'exhausted'; maxAttempts: number }
 
 /**
@@ -52,10 +58,16 @@ export function evaluateRestart(state: RestartState): RestartAction {
     return { kind: 'non_retryable', exitCode: state.exitCode }
   }
 
+  // Hard lifetime cap: prevent sessions from restarting indefinitely
+  const lifetime = state.lifetimeRestarts ?? 0
+  if (lifetime >= MAX_LIFETIME_RESTARTS) {
+    return { kind: 'exhausted', maxAttempts: MAX_LIFETIME_RESTARTS }
+  }
+
   const now = Date.now()
   let { restartCount } = state
 
-  // Reset counter if cooldown has elapsed
+  // Reset per-window counter if cooldown has elapsed
   if (state.lastRestartAt && (now - state.lastRestartAt) > RESTART_COOLDOWN_MS) {
     restartCount = 0
   }
@@ -69,6 +81,7 @@ export function evaluateRestart(state: RestartState): RestartAction {
       delayMs: RESTART_DELAY_MS,
       updatedCount,
       updatedLastRestartAt: now,
+      updatedLifetimeCount: lifetime + 1,
     }
   }
 

server/types.ts

@@ -114,6 +114,10 @@ export interface Session {
   /** Number of consecutive no-output exits with the same claudeSessionId.
    *  Only after reaching the threshold do we clear claudeSessionId. */
   _noOutputExitCount: number
+  /** Total lifetime restart count.  Unlike restartCount (which resets after
+   *  the cooldown window), this never resets and provides a hard cap to
+   *  prevent sessions from restarting indefinitely. */
+  _lifetimeRestarts: number
   /** Grace period timer before auto-denying prompts after last client leaves. */
   _leaveGraceTimer?: ReturnType<typeof setTimeout> | null
   /** Timestamp of last meaningful activity (input, prompt response, client join). Used by idle reaper. */

server/ws-message-handler.test.ts

@@ -41,6 +41,7 @@ function mockSession(overrides: Partial<Session> = {}): Session {
     _namingAttempts: 0,
     _processGeneration: 0,
     _noOutputExitCount: 0,
+    _lifetimeRestarts: 0,
     _apiRetry: { count: 0 },
     ...overrides,
   }