circuschief 0.1.4 → 0.2.1

package/packages/server/src/db/migrations/sessionsMigrations.js

@@ -10,6 +10,65 @@ const TABLE_SESSIONS = 'sessions';
 // Column type constants
 const COL_INTEGER_DEFAULT_0 = 'INTEGER DEFAULT 0';
 
+/**
+ * SQL column definition for the sessions table with updated status CHECK constraint.
+ */
+const SESSIONS_BASE_COLUMNS = `
+    id TEXT PRIMARY KEY,
+    project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'starting' CHECK (status IN ('starting', 'running', 'waiting', 'stopped', 'completed', 'error', 'scheduled')),
+    mode TEXT NOT NULL DEFAULT 'standard' CHECK (mode IN ('plan', 'standard', 'yolo')),
+    thinking_enabled INTEGER NOT NULL DEFAULT 0,
+    git_branch TEXT,
+    git_worktree TEXT,
+    pr_url TEXT,
+    error TEXT,
+    effort_level TEXT CHECK(effort_level IN ('low', 'medium', 'high', 'max', 'auto')),
+    cost_usd REAL DEFAULT 0,
+    claude_session_id TEXT,
+    model TEXT,
+    next_template_id TEXT REFERENCES session_templates(id) ON DELETE SET NULL,
+    parent_session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL,
+    input_tokens INTEGER DEFAULT 0,
+    output_tokens INTEGER DEFAULT 0,
+    cache_read_input_tokens INTEGER DEFAULT 0,
+    cache_creation_input_tokens INTEGER DEFAULT 0,
+    web_search_requests INTEGER DEFAULT 0,
+    context_window INTEGER DEFAULT 200000,
+    archived INTEGER NOT NULL DEFAULT 0,
+    starred INTEGER NOT NULL DEFAULT 0,
+    manually_named INTEGER NOT NULL DEFAULT 0,
+    scheduled_at INTEGER DEFAULT NULL,
+    reschedule_delay_minutes INTEGER DEFAULT 15,
+    auto_reschedule_enabled INTEGER DEFAULT 0,
+    reschedule_on_token_limit INTEGER DEFAULT 1,
+    reschedule_on_service_error INTEGER DEFAULT 1,
+    max_reschedule_count INTEGER DEFAULT NULL,
+    max_total_tokens INTEGER DEFAULT NULL,
+    reschedule_count INTEGER DEFAULT 0,
+    reschedule_at_token_count INTEGER DEFAULT NULL,
+    created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+    updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+`;
+
+/**
+ * All possible column names that may exist in the sessions table for migration SELECT.
+ */
+const SESSIONS_ALL_COLUMNS = [
+  'id', 'project_id', 'name', 'status', 'mode', 'thinking_enabled',
+  'git_branch', 'git_worktree', 'pr_url', 'error', 'effort_level',
+  'cost_usd', 'claude_session_id', 'model', 'next_template_id',
+  'parent_session_id', 'input_tokens', 'output_tokens',
+  'cache_read_input_tokens', 'cache_creation_input_tokens',
+  'web_search_requests', 'context_window', 'archived', 'starred',
+  'manually_named', 'scheduled_at', 'reschedule_delay_minutes',
+  'auto_reschedule_enabled', 'reschedule_on_token_limit',
+  'reschedule_on_service_error', 'max_reschedule_count',
+  'max_total_tokens', 'reschedule_count', 'reschedule_at_token_count',
+  'created_at', 'updated_at',
+];
+
 /**
  * Migrate sessions table to include 'stopped' and 'scheduled' in status CHECK constraint.
  * SQLite doesn't support ALTER TABLE to modify constraints, so we recreate the table.
@@ -22,76 +81,17 @@ function migrateSessionsStatusConstraint(db) {
     return;
   }
 
-  // Get all columns from the current table to preserve data
   const columnNames = getColumns(db, TABLE_SESSIONS);
-
-  const baseColumns = `
-      id TEXT PRIMARY KEY,
-      project_id TEXT NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
-      name TEXT NOT NULL,
-      status TEXT NOT NULL DEFAULT 'starting' CHECK (status IN ('starting', 'running', 'waiting', 'stopped', 'completed', 'error', 'scheduled')),
-      mode TEXT NOT NULL DEFAULT 'standard' CHECK (mode IN ('plan', 'standard', 'yolo')),
-      thinking_enabled INTEGER NOT NULL DEFAULT 0,
-      git_branch TEXT,
-      git_worktree TEXT,
-      pr_url TEXT,
-      error TEXT,
-      effort_level TEXT CHECK(effort_level IN ('low', 'medium', 'high', 'max', 'auto')),
-      cost_usd REAL DEFAULT 0,
-      claude_session_id TEXT,
-      model TEXT,
-      next_template_id TEXT REFERENCES session_templates(id) ON DELETE SET NULL,
-      parent_session_id TEXT REFERENCES sessions(id) ON DELETE SET NULL,
-      input_tokens INTEGER DEFAULT 0,
-      output_tokens INTEGER DEFAULT 0,
-      cache_read_input_tokens INTEGER DEFAULT 0,
-      cache_creation_input_tokens INTEGER DEFAULT 0,
-      web_search_requests INTEGER DEFAULT 0,
-      context_window INTEGER DEFAULT 200000,
-      archived INTEGER NOT NULL DEFAULT 0,
-      starred INTEGER NOT NULL DEFAULT 0,
-      manually_named INTEGER NOT NULL DEFAULT 0,
-      scheduled_at INTEGER DEFAULT NULL,
-      reschedule_delay_minutes INTEGER DEFAULT 15,
-      auto_reschedule_enabled INTEGER DEFAULT 0,
-      reschedule_on_token_limit INTEGER DEFAULT 1,
-      reschedule_on_service_error INTEGER DEFAULT 1,
-      max_reschedule_count INTEGER DEFAULT NULL,
-      max_total_tokens INTEGER DEFAULT NULL,
-      reschedule_count INTEGER DEFAULT 0,
-      reschedule_at_token_count INTEGER DEFAULT NULL,
-      created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
-      updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
-  `;
-
-  const selectColumns = [
-    'id', 'project_id', 'name', 'status', 'mode', 'thinking_enabled',
-    'git_branch', 'git_worktree', 'pr_url', 'error', 'effort_level',
-    'cost_usd', 'claude_session_id', 'model', 'next_template_id',
-    'parent_session_id', 'input_tokens', 'output_tokens',
-    'cache_read_input_tokens', 'cache_creation_input_tokens',
-    'web_search_requests', 'context_window', 'archived', 'starred',
-    'manually_named', 'scheduled_at', 'reschedule_delay_minutes',
-    'auto_reschedule_enabled', 'reschedule_on_token_limit',
-    'reschedule_on_service_error', 'max_reschedule_count',
-    'max_total_tokens', 'reschedule_count', 'reschedule_at_token_count',
-    'created_at', 'updated_at',
-  ]
+  const selectColumns = SESSIONS_ALL_COLUMNS
     .filter((col) => columnNames.includes(col))
     .join(', ');
 
   db.exec(`
-    CREATE TABLE sessions_new (
-      ${baseColumns}
-    );
-
+    CREATE TABLE sessions_new (${SESSIONS_BASE_COLUMNS});
     INSERT INTO sessions_new (${selectColumns})
     SELECT ${selectColumns} FROM sessions;
-
     DROP TABLE sessions;
-
     ALTER TABLE sessions_new RENAME TO sessions;
-
     CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_id);
     CREATE INDEX IF NOT EXISTS idx_sessions_status ON sessions(status);
     CREATE INDEX IF NOT EXISTS idx_sessions_archived ON sessions(archived);

package/packages/server/src/index.js

@@ -1,14 +1,16 @@
 import { createServer } from 'http';
-import { parseArgs } from 'node:util';
 import { execSync } from 'child_process';
 import { createApp } from './app.js';
 import { initDatabase } from './database.js';
-import { initWebSocket } from './websocket.js';
-import { DEFAULT_SERVER_PORT } from '../../shared/src/index.js';
+import { initWebSocket, webSocketManager } from './websocket.js';
+import { parseCliOptions } from './cli.js';
+import { settings } from './db/index.js';
 import * as prStatusService from './services/prStatusService.js';
 import * as systemMonitor from './services/systemMonitor.js';
 import { schedulerService } from './services/schedulerService.js';
 import * as sessionManager from './services/sessionManager.js';
+import { clearScheduledTimers } from './services/summaryService.js';
+import { commandRunner } from './services/commandRunner.js';
 
 /**
  * Validate Node.js environment at startup.
@@ -27,17 +29,7 @@ function validateNodeEnvironment() {
   }
 }
 
-const { values } = parseArgs({
-  options: {
-    port: {
-      type: 'string',
-      short: 'p',
-      default: String(DEFAULT_SERVER_PORT),
-    },
-  },
-});
-
-const port = parseInt(values.port, 10);
+const { port, disableAnalytics } = parseCliOptions();
 process.env.PORT = String(port);
 const production = process.env.NODE_ENV === 'production';
 const dbPath = process.env.DB_PATH || 'circuschief.db';
@@ -57,6 +49,12 @@ validateNodeEnvironment();
 initDatabase(dbPath);
 console.log(`Database initialized: ${dbPath}`);
 
+// Apply --no-analytics flag to persisted settings
+if (disableAnalytics) {
+  settings.setGeneralSettings({ disableAnalytics: true });
+  console.log('Analytics disabled via --no-analytics flag');
+}
+
 // Create Express app
 const app = createApp({ production });
 
@@ -77,30 +75,45 @@ prStatusService.start();
 systemMonitor.start();
 
 // Graceful shutdown
-process.on('SIGTERM', () => {
-  console.log('SIGTERM received, shutting down gracefully');
-  schedulerService.stop();
-  prStatusService.stop();
-  systemMonitor.stop();
-  server.close(() => {
-    console.log('Server closed');
-    process.exit(0);
-  });
-});
+let shuttingDown = false;
+function shutdown(signal) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.log(`${signal} received, shutting down gracefully`);
+
+  // Safety net: force exit after 5 seconds
+  const forceTimeout = setTimeout(() => {
+    console.error('Graceful shutdown timed out, forcing exit');
+    process.exit(1);
+  }, 5000);
+  forceTimeout.unref();
 
-process.on('SIGINT', () => {
-  console.log('SIGINT received, shutting down gracefully');
+  // Stop periodic services
   schedulerService.stop();
   prStatusService.stop();
   systemMonitor.stop();
+
+  // Clear dangling timers from summary service
+  clearScheduledTimers();
+
+  // Kill child processes spawned by commandRunner
+  commandRunner.shutdownAll();
+
+  // Close all WebSocket connections (must happen before server.close())
+  webSocketManager.close();
+
+  // Close HTTP server (now unblocked since WS clients are terminated)
   server.close(() => {
     console.log('Server closed');
     process.exit(0);
   });
-});
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
 
 // Start server on all interfaces
 server.listen(port, '0.0.0.0', () => {
-  console.log(`Server running on http://0.0.0.0:${port}`);
-  console.log(`WebSocket available at ws://0.0.0.0:${port}/ws`);
+  console.log(`Circus Chief running on http://localhost:${port}`);
+  console.log(`WebSocket available at ws://localhost:${port}/ws`);
 });

package/packages/server/src/services/commandRunner.js

@@ -33,11 +33,10 @@ export class CommandRunner {
    * Wrap command with platform-specific TTY allocation.
    */
   #wrapCommandForPlatform(command) {
-    const osType = platform();
-    if (osType === 'linux') {
-      return `script -q -e -c ${JSON.stringify(command)} /dev/null`;
-    }
-    return `script -q /dev/null sh -c ${JSON.stringify(command)}`;
+    const cmd = JSON.stringify(command);
+    return platform() === 'linux'
+      ? `script -q -e -c ${cmd} /dev/null`
+      : `script -q /dev/null sh -c ${cmd}`;
   }
 
   /**
@@ -62,8 +61,7 @@ export class CommandRunner {
    */
   #flushOutputBuffer(entryInput, runId) {
     const entry = entryInput;
-    if (!entry.outputBuffer) return;
-    if (!entry.sessionId || !entry.buttonId) return;
+    if (!entry.outputBuffer || !entry.sessionId || !entry.buttonId) return;
     if (!commandRuns || typeof commandRuns.appendOutput !== 'function') return;
     try {
       commandRuns.appendOutput(runId, entry.outputBuffer);
@@ -104,21 +102,31 @@ export class CommandRunner {
 
     this.processes.delete(runId);
     if (onComplete) onComplete(exitCode, entry.output);
-    // Use ?? 1 (not signal-specific codes like 143 for SIGTERM) because:
-    // - Exit codes >128 indicate signal termination (convention: 128 + signal number)
-    // - Normalizing to 1 simplifies error handling for consumers
-    // - The signal information is already logged above for debugging
+    // Normalize to 1 on signal termination (signal info already logged above)
     return exitCode ?? 1;
   }
 
-  /**
-   * Run a command and stream output via callback
-   *
-   * @param {{ runId: string, command: string, workingDirectory: string }} params - Command parameters
-   * @param {{ onOutput?: function, onComplete?: function, onError?: function }} callbacks - Callback functions
-   * @param {{ sessionId?: string, buttonId?: string }} metadata - Optional metadata
-   * @returns {Promise<number>} Exit code
-   */
+  /** Handle a run failure (process error or setup exception). Flushes output, marks failed, resolves. */
+  #handleRunFailure({ entry: entryParam, runId, err, onError, resolve }) {
+    const entry = entryParam;
+    let errorOutput = `[Error] Failed to execute command: ${err.message}`;
+    if (entry) {
+      const remaining = entry.outputProcessor.flush();
+      if (remaining) { entry.output += remaining; entry.outputBuffer += remaining; }
+      this.#flushOutputBuffer(entry, runId);
+      errorOutput = entry.output;
+    }
+    const msg = entry ? `Failed to execute command: ${err.message}` : `Error running command: ${err.message}`;
+    console.error(`[commandRunner.run] Error for runId: ${runId}`, err);
+    if (onError) onError(msg);
+    if (commandRuns && typeof commandRuns.complete === 'function') {
+      try { commandRuns.complete(runId, 1, errorOutput); } catch (dbErr) { console.warn(`[commandRunner.run] DB error for runId: ${runId}`, dbErr.message); }
+    }
+    this.processes.delete(runId);
+    resolve(1);
+  }
+
+  /** Run a command and stream output via callback. Returns exit code. */
   async run(params, callbacks = {}, metadata = {}) {
     const { runId, command, workingDirectory } = params;
     const { onOutput, onComplete, onError } = callbacks;
@@ -139,7 +147,6 @@ export class CommandRunner {
         const entry = this.#createProcessEntry(child, sessionId, buttonId);
         this.processes.set(runId, entry);
 
-        // Buffer timer management
         const clearBufferTimer = () => {
           if (entry.bufferFlushTimer) {
             clearInterval(entry.bufferFlushTimer);
@@ -148,7 +155,6 @@ export class CommandRunner {
         };
         entry.bufferFlushTimer = setInterval(() => this.#flushOutputBuffer(entry, runId), this.outputBufferFlushInterval);
 
-        // Data handler for both stdout and stderr
         const handleData = (data) => {
           const text = entry.outputProcessor.process(data.toString());
           if (text) {
@@ -163,20 +169,7 @@ export class CommandRunner {
 
         child.on('error', (err) => {
           clearBufferTimer();
-          const remainingText = entry.outputProcessor.flush();
-          if (remainingText) {
-            entry.output += remainingText;
-            entry.outputBuffer += remainingText;
-          }
-          this.#flushOutputBuffer(entry, runId);
-          const msg = `Failed to execute command: ${err.message}`;
-          console.error(`[commandRunner.run] Error for runId: ${runId}`, err);
-          if (onError) onError(msg);
-          if (commandRuns && typeof commandRuns.complete === 'function') {
-            try { commandRuns.complete(runId, 1, entry.output); } catch (dbErr) { console.warn('[commandRunner.run] Warning: Error completing run in database for runId:', runId, dbErr.message); }
-          }
-          this.processes.delete(runId);
-          resolve(1);
+          this.#handleRunFailure({ entry, runId, err, onError, resolve });
         });
 
         child.on('close', (exitCode, signal) => {
@@ -190,28 +183,12 @@ export class CommandRunner {
           resolve(this.#handleProcessClose({ entry, runId, exitCode, signal }, onComplete));
         });
       } catch (err) {
-        const msg = `Error running command: ${err.message}`;
-        console.error(`[commandRunner.run] Exception for runId: ${runId}`, err);
-        if (onError) onError(msg);
-        // Mark as error in database (if available) and persist the error message
-        if (commandRuns && typeof commandRuns.complete === 'function') {
-          try {
-            commandRuns.complete(runId, 1, `[Error] ${msg}`);
-          } catch (dbErr) {
-            console.warn(`[commandRunner.run] Warning: Error marking failed run in database for runId: ${runId}`, dbErr.message);
-          }
-        }
-        this.processes.delete(runId);
-        resolve(1);
+        this.#handleRunFailure({ entry: null, runId, err, onError, resolve });
       }
     });
   }
 
-  /**
-   * Kill a running process
-   * @param {string} runId
-   * @returns {boolean} True if process was killed, false if not found
-   */
+  /** Kill a running process. Returns true if killed, false if not found. */
   kill(runId) {
     const entry = this.processes.get(runId);
     if (!entry) {
@@ -234,22 +211,10 @@ export class CommandRunner {
 
       // Give it a moment to terminate gracefully, then force kill
       setTimeout(() => {
-        // Check if process is still in our map (not yet closed)
-        if (this.processes.has(runId)) {
-          console.log(`[commandRunner.kill] Process still running, sending SIGKILL to runId: ${runId}`);
-          try {
-            process.kill(-pid, 'SIGKILL');
-          } catch (e) {
-            // Fallback to killing just the process if process group kill fails
-            try {
-              entry.process.kill('SIGKILL');
-            } catch (err) {
-              // Process may have already exited
-              console.log(`[commandRunner.kill] SIGKILL failed, process may have exited: ${err.message}`);
-            }
-          }
-        } else {
-          console.log(`[commandRunner.kill] Process already exited for runId: ${runId}`);
+        if (!this.processes.has(runId)) return;
+        console.log(`[commandRunner.kill] Process still running, sending SIGKILL to runId: ${runId}`);
+        try { process.kill(-pid, 'SIGKILL'); } catch {
+          try { entry.process.kill('SIGKILL'); } catch { /* already dead */ }
         }
       }, 1000);
 
@@ -279,30 +244,30 @@ export class CommandRunner {
     }
   }
 
-  /**
-   * Get all active runs
-   * @returns {Map} Map of runId -> process info
-   */
+  /** Terminate all active child processes (called during graceful shutdown). */
+  shutdownAll() {
+    const sendSignal = (sig) => {
+      for (const [, entry] of this.processes) {
+        try { process.kill(-entry.process.pid, sig); } catch {
+          try { entry.process.kill(sig); } catch { /* already dead */ }
+        }
+      }
+    };
+    sendSignal('SIGTERM');
+    setTimeout(() => sendSignal('SIGKILL'), 1000).unref();
+  }
+
+  /** Get all active runs as a new Map. */
   getActiveRuns() {
     return new Map(this.processes);
   }
 
-  /**
-   * Check if a run is active
-   * @param {string} runId
-   * @returns {boolean}
-   */
+  /** Check if a run is active. */
   isRunning(runId) {
     return this.processes.has(runId);
   }
 
-  /**
-   * Get all running commands for a project
-   * Used for merging in-memory running commands with completed runs from the database
-   * @param {string} projectId
-   * @param {Function} getSessionById - Function to look up session by ID
-   * @returns {Array} Running command runs
-   */
+  /** Get all running commands for a project (merges in-memory with completed DB runs). */
   getRunningByProjectId(projectId, getSessionById) {
     const results = [];
     for (const [runId, entry] of this.processes.entries()) {
@@ -324,15 +289,7 @@ export class CommandRunner {
     return results;
   }
 
-  /**
-   * Get all active runs for a specific session (both running and recent completed)
-   * @param {string} sessionId
-   * @returns {Array} Array of run info objects
-   */
-  /**
-   * Mark an orphaned run as error in the database
-   * @param {Object} dbRun - The database run record
-   */
+  /** Mark an orphaned run as error in the database. */
   #markOrphanedRunAsError(dbRun) {
     console.log(
       `[commandRunner.getRunsBySession] Orphaned run detected: ${dbRun.id}, marking as error`
@@ -348,11 +305,7 @@ export class CommandRunner {
     }
   }
 
-  /**
-   * Process a database run record and return a normalized run object
-   * @param {Object} dbRun - The database run record
-   * @returns {Object} Normalized run object
-   */
+  /** Process a database run record and return a normalized run object. */
   #processDbRun(dbRun) {
     let status = dbRun.status;
     let exitCode = dbRun.exitCode;

package/packages/server/src/services/kanbanTriggers.js

@@ -120,6 +120,45 @@ export function getTemplateSessionSettings(template, session) {
  * @param {Object} [options] - Options
  * @param {number} [options.depth=0] - Current recursion depth
  */
+/**
+ * Create and configure a child session from a template for lane entry.
+ * @param {Object} template
+ * @param {Object} session - Parent session
+ * @param {Object} lane
+ * @param {number} depth - Current trigger depth
+ * @returns {{ newSession: Object, renderedPrompt: string, settings: Object }}
+ */
+async function buildChildSessionFromTemplate(template, session, lane, depth) {
+  // Render prompt with session context
+  const parentSummary = sessionSummaries.getBySessionId(session.id);
+  const rootSession = getRootSession(session);
+  const rootSummary = sessionSummaries.getBySessionId(rootSession.id);
+  const renderedPrompt = await renderTemplatePrompt(
+    template.prompt,
+    { parentSession: session, parentSummary, rootSession, rootSummary }
+  );
+
+  // Get settings and create session
+  const settings = getTemplateSessionSettings(template, session);
+  const newSession = sessions.create(session.projectId, `${template.name} (lane: ${lane.name})`, renderedPrompt, {
+    mode: settings.mode,
+    thinkingEnabled: settings.thinkingEnabled,
+    gitBranch: settings.gitBranch,
+    status: 'starting',
+    model: settings.model,
+  });
+
+  // Configure session
+  sessions.update(newSession.id, {
+    parentSessionId: session.id,
+    nextTemplateId: template.nextTemplateId || null,
+    targetLaneId: template.targetLaneId || null,
+    laneTriggerDepth: depth + 1,
+  });
+
+  return { newSession, renderedPrompt, settings };
+}
+
 export async function triggerOnEnterTemplate(sessionId, lane, options = {}) {
   const { depth = 0 } = options;
 
@@ -141,32 +180,7 @@ export async function triggerOnEnterTemplate(sessionId, lane, options = {}) {
   console.log(`Kanban: Triggering on-enter template "${template.name}" for session "${session.name}" entering lane "${lane.name}"`);
 
   try {
-    // Render prompt with session context
-    const parentSummary = sessionSummaries.getBySessionId(sessionId);
-    const rootSession = getRootSession(session);
-    const rootSummary = sessionSummaries.getBySessionId(rootSession.id);
-    const renderedPrompt = await renderTemplatePrompt(
-      template.prompt,
-      { parentSession: session, parentSummary, rootSession, rootSummary }
-    );
-
-    // Get settings and create session
-    const settings = getTemplateSessionSettings(template, session);
-    const newSession = sessions.create(session.projectId, `${template.name} (lane: ${lane.name})`, renderedPrompt, {
-      mode: settings.mode,
-      thinkingEnabled: settings.thinkingEnabled,
-      gitBranch: settings.gitBranch,
-      status: 'starting',
-      model: settings.model,
-    });
-
-    // Configure session
-    sessions.update(newSession.id, {
-      parentSessionId: session.id,
-      nextTemplateId: template.nextTemplateId || null,
-      targetLaneId: template.targetLaneId || null,
-      laneTriggerDepth: depth + 1,
-    });
+    const { newSession, renderedPrompt, settings } = await buildChildSessionFromTemplate(template, session, lane, depth);
 
     // Determine working directory
     const { workingDirectory, gitWorktree } = await determineWorkingDirectory(session, project, {
@@ -203,6 +217,48 @@ export async function triggerOnEnterTemplate(sessionId, lane, options = {}) {
  * @param {Object} [options] - Options
  * @param {number} [options.depth=0] - Current recursion depth
  */
+/**
+ * Create and configure a child session from a lane's on-enter prompt.
+ * @param {Object} lane
+ * @param {Object} session - Parent session
+ * @param {number} depth - Current trigger depth
+ * @returns {Promise<{ newSession: Object, renderedPrompt: string, settings: Object }>}
+ */
+async function buildChildSessionFromPrompt(lane, session, depth) {
+  // Render prompt with session context
+  const parentSummary = sessionSummaries.getBySessionId(session.id);
+  const rootSession = getRootSession(session);
+  const rootSummary = sessionSummaries.getBySessionId(rootSession.id);
+  const renderedPrompt = await renderTemplatePrompt(
+    lane.onEnterPrompt,
+    { parentSession: session, parentSummary, rootSession, rootSummary }
+  );
+
+  // Get settings and create session
+  const settings = getLaneSessionSettings(lane, session);
+  const newSession = sessions.create(session.projectId, `Lane prompt (lane: ${lane.name})`, renderedPrompt, {
+    ...settings,
+    status: 'starting',
+  });
+
+  // Configure session
+  const sessionUpdates = { parentSessionId: session.id, laneTriggerDepth: depth + 1 };
+  if (lane.onEnterAutoRescheduleEnabled) {
+    Object.assign(sessionUpdates, {
+      autoRescheduleEnabled: true,
+      rescheduleDelayMinutes: lane.onEnterRescheduleDelayMinutes || 15,
+      rescheduleOnTokenLimit: lane.onEnterRescheduleOnTokenLimit ?? true,
+      rescheduleOnServiceError: lane.onEnterRescheduleOnServiceError ?? true,
+      maxRescheduleCount: lane.onEnterMaxRescheduleCount || null,
+      maxTotalTokens: lane.onEnterMaxTotalTokens || null,
+      rescheduleAtTokenCount: lane.onEnterRescheduleAtTokenCount || null,
+    });
+  }
+  sessions.update(newSession.id, sessionUpdates);
+
+  return { newSession, renderedPrompt, settings };
+}
+
 export async function triggerOnEnterPrompt(sessionId, lane, options = {}) {
   const { depth = 0 } = options;
 
@@ -218,36 +274,7 @@ export async function triggerOnEnterPrompt(sessionId, lane, options = {}) {
   console.log(`Kanban: Triggering on-enter prompt for session "${session.name}" entering lane "${lane.name}"`);
 
   try {
-    // Render prompt with session context
-    const parentSummary = sessionSummaries.getBySessionId(sessionId);
-    const rootSession = getRootSession(session);
-    const rootSummary = sessionSummaries.getBySessionId(rootSession.id);
-    const renderedPrompt = await renderTemplatePrompt(
-      lane.onEnterPrompt,
-      { parentSession: session, parentSummary, rootSession, rootSummary }
-    );
-
-    // Get settings and create session
-    const settings = getLaneSessionSettings(lane, session);
-    const newSession = sessions.create(session.projectId, `Lane prompt (lane: ${lane.name})`, renderedPrompt, {
-      ...settings,
-      status: 'starting',
-    });
-
-    // Configure session
-    const sessionUpdates = { parentSessionId: session.id, laneTriggerDepth: depth + 1 };
-    if (lane.onEnterAutoRescheduleEnabled) {
-      Object.assign(sessionUpdates, {
-        autoRescheduleEnabled: true,
-        rescheduleDelayMinutes: lane.onEnterRescheduleDelayMinutes || 15,
-        rescheduleOnTokenLimit: lane.onEnterRescheduleOnTokenLimit ?? true,
-        rescheduleOnServiceError: lane.onEnterRescheduleOnServiceError ?? true,
-        maxRescheduleCount: lane.onEnterMaxRescheduleCount || null,
-        maxTotalTokens: lane.onEnterMaxTotalTokens || null,
-        rescheduleAtTokenCount: lane.onEnterRescheduleAtTokenCount || null,
-      });
-    }
-    sessions.update(newSession.id, sessionUpdates);
+    const { newSession, renderedPrompt, settings } = await buildChildSessionFromPrompt(lane, session, depth);
 
     // Determine working directory
     const { workingDirectory, gitWorktree } = await determineWorkingDirectory(session, project);