circuschief 0.7.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circuschief",
-  "version": "0.7.0",
+  "version": "1.0.0",
   "description": "Local-first web UI for managing Claude Code sessions",
   "type": "module",
   "bin": {

package/packages/server/src/agents/adapters/CodexAdapter.js

@@ -14,16 +14,17 @@ let codexCliUnavailable = false;
  *
  * Two execution paths:
  *
- *   1. CLI path (default) — spawns the `codex --json ...` CLI and parses its
+ *   1. CLI path (default) — spawns `codex exec --json ...` and parses its
  *      line-delimited JSON stdout. Uses {@link createCodexEventMapper} to
  *      normalize events into the SDK-shaped envelope the rest of the app
  *      already understands.
  *
  *   2. Direct-API path — activated by {@code USE_CODEX_DIRECT_API=1}. Uses
  *      the official {@code openai} SDK with Chat Completions streaming
- *      against the provider's configured baseURL/apiKey. Intended for
- *      environments where the Codex CLI isn't installable and for the
- *      Step-0 contingency path in the implementation plan.
+ *      against the provider's configured baseURL/apiKey. It bypasses
+ *      CLI-specific behavior such as sandbox enforcement and Codex
+ *      commit-attribution config. Intended for
+ *      environments where the Codex CLI isn't installable.
  *
  * Capabilities in v1:
  *   - streaming:   true

package/packages/server/src/api/canvas.js

@@ -2,10 +2,11 @@ import { Router } from 'express';
 import { readFileSync, existsSync, statSync } from 'fs';
 import { mkdir } from 'fs/promises';
 import { extname, join, basename } from 'path';
-import { sessions, canvasItems } from '../database.js';
+import { canvasItems } from '../database.js';
 import { broadcastToSession } from '../websocket.js';
 import { WS_MESSAGE_TYPES, UpdateCanvasItemRequest } from '../../../shared/src/index.js';
 import { upload, handleUploadError } from '../middleware/upload.js';
+import { requireRootSessionAndProject } from '../middleware/sessionLookup.js';
 import {
   isBinaryContent,
   getTypeFromExtension,
@@ -19,8 +20,6 @@ import {
 import trashRoutes from './canvas-trash-routes.js';
 
 // Error message constants
-const ERR_SESSION_NOT_FOUND = 'Session not found';
-
 /**
  * Process multipart file upload (Mode 1)
  * @param {Express.Multer.File} file - The uploaded file from multer
@@ -84,12 +83,7 @@ router.use('/', trashRoutes);
 // 1. Multipart mode: FormData with 'file' field - from browser file uploads
 // 2. File mode: { filePath } - reads file from disk
 // 3. Inline mode: { type, content, filename } - uses provided content directly
-router.post('/:id/canvas', upload.single('file'), handleUploadError, (req, res) => {
-  const session = sessions.getById(req.params.id);
-  if (!session) {
-    return res.status(404).json({ error: ERR_SESSION_NOT_FOUND });
-  }
-
+router.post('/:id/canvas', requireRootSessionAndProject, upload.single('file'), handleUploadError, (req, res) => {
   const { filePath, type, content, filename } = req.body;
   let result;
 
@@ -110,21 +104,16 @@ router.post('/:id/canvas', upload.single('file'), handleUploadError, (req, res)
     return res.status(400).json({ error: result.error });
   }
 
-  const item = canvasItems.create(req.params.id, result.itemData);
+  const item = canvasItems.create(req.rootSessionId, result.itemData);
 
   // Broadcast to session subscribers
-  broadcastCanvasUpdate(req.params.id, item);
+  broadcastCanvasUpdate(req.rootSessionId, item);
 
   res.status(201).json(item);
 });
 
 // PUT /api/sessions/:id/canvas/:itemId - Update canvas item content in-place
-router.put('/:id/canvas/:itemId', (req, res) => {
-  const session = sessions.getById(req.params.id);
-  if (!session) {
-    return res.status(404).json({ error: ERR_SESSION_NOT_FOUND });
-  }
-
+router.put('/:id/canvas/:itemId', requireRootSessionAndProject, (req, res) => {
   const parsed = UpdateCanvasItemRequest.safeParse(req.body);
   if (!parsed.success) {
     return res.status(400).json({ error: 'Invalid request body', details: parsed.error.issues });
@@ -135,7 +124,7 @@ router.put('/:id/canvas/:itemId', (req, res) => {
     return res.status(404).json({ error: 'Canvas item not found' });
   }
 
-  if (item.sessionId !== req.params.id) {
+  if (item.sessionId !== req.rootSessionId) {
     return res.status(400).json({ error: 'Canvas item does not belong to this session' });
   }
 
@@ -144,20 +133,15 @@ router.put('/:id/canvas/:itemId', (req, res) => {
   }
 
   const updatedItem = canvasItems.updateContent(req.params.itemId, parsed.data.content);
-  broadcastToSession(req.params.id, WS_MESSAGE_TYPES.CANVAS_UPDATE, { item: updatedItem });
+  broadcastToSession(req.rootSessionId, WS_MESSAGE_TYPES.CANVAS_UPDATE, { item: updatedItem });
   res.json(updatedItem);
 });
 
 // GET /api/sessions/:id/canvas - List canvas items
 // Returns only latest version of each file (no version metadata exposed)
-router.get('/:id/canvas', (req, res) => {
-  const session = sessions.getById(req.params.id);
-  if (!session) {
-    return res.status(404).json({ error: ERR_SESSION_NOT_FOUND });
-  }
-
+router.get('/:id/canvas', requireRootSessionAndProject, (req, res) => {
   // Get only latest versions (one per filename)
-  const items = canvasItems.getLatestVersionsBySessionId(req.params.id);
+  const items = canvasItems.getLatestVersionsBySessionId(req.rootSessionId);
 
   // Strip content/data from list responses to reduce payload size.
   // Clients should use GET /canvas/file/:filename/content for inline content.
@@ -166,14 +150,9 @@ router.get('/:id/canvas', (req, res) => {
 
 // GET /api/sessions/:id/canvas/all - List ALL canvas items (including all versions)
 // Returns all versions of each file for the frontend UI
-router.get('/:id/canvas/all', (req, res) => {
-  const session = sessions.getById(req.params.id);
-  if (!session) {
-    return res.status(404).json({ error: ERR_SESSION_NOT_FOUND });
-  }
-
+router.get('/:id/canvas/all', requireRootSessionAndProject, (req, res) => {
   // Get ALL versions (not just latest)
-  const items = canvasItems.getBySessionId(req.params.id);
+  const items = canvasItems.getBySessionId(req.rootSessionId);
 
   // Strip content/data from list responses to reduce payload size.
   res.json(items.map(({ content: _content, data: _data, ...meta }) => meta));
@@ -182,15 +161,11 @@ router.get('/:id/canvas/all', (req, res) => {
 // GET /api/sessions/:id/canvas/file/:filename/history/:version - Get historical version of canvas file
 // Uses standard versioning: version 1 = oldest, version N = latest (where N = totalVersions)
 // NOTE: This route must be defined BEFORE the main file route to match correctly
-router.get('/:id/canvas/file/:filename/history/:version', async (req, res) => {
-  const { id: sessionId, filename, version } = req.params;
+router.get('/:id/canvas/file/:filename/history/:version', requireRootSessionAndProject, async (req, res) => {
+  const { filename, version } = req.params;
+  const sessionId = req.rootSessionId;
   const versionNum = parseInt(version, 10);
 
-  const session = sessions.getById(sessionId);
-  if (!session) {
-    return res.status(404).json({ error: ERR_SESSION_NOT_FOUND });
-  }
-
   // Get all versions of this file (newest first)
   const allVersions = canvasItems.getAllVersionsByFilename(sessionId, filename);
   if (allVersions.length === 0) {
@@ -247,11 +222,8 @@ router.get('/:id/canvas/file/:filename/history/:version', async (req, res) => {
 // GET /api/sessions/:id/canvas/file/:filename/content - Get canvas file content inline
 // Returns content/data inline in JSON for browser consumption (unlike the temp-file endpoint below)
 // Supports ?version=N query param (1-based, 1 = oldest)
-router.get('/:id/canvas/file/:filename/content', (req, res) => {
-  const session = sessions.getById(req.params.id);
-  if (!session) return res.status(404).json({ error: ERR_SESSION_NOT_FOUND });
-
-  const allVersions = canvasItems.getAllVersionsByFilename(req.params.id, req.params.filename);
+router.get('/:id/canvas/file/:filename/content', requireRootSessionAndProject, (req, res) => {
+  const allVersions = canvasItems.getAllVersionsByFilename(req.rootSessionId, req.params.filename);
   if (allVersions.length === 0) return res.status(404).json({ error: 'File not found' });
 
   // Support ?version=N (1-based, 1 = oldest)
@@ -280,13 +252,10 @@ router.get('/:id/canvas/file/:filename/content', (req, res) => {
 });
 
 // GET /api/sessions/:id/canvas/:itemId/content - Get one canvas item content inline
-router.get('/:id/canvas/:itemId/content', (req, res) => {
-  const session = sessions.getById(req.params.id);
-  if (!session) return res.status(404).json({ error: ERR_SESSION_NOT_FOUND });
-
+router.get('/:id/canvas/:itemId/content', requireRootSessionAndProject, (req, res) => {
   const item = canvasItems.getById(req.params.itemId);
   if (!item) return res.status(404).json({ error: 'Canvas item not found' });
-  if (item.sessionId !== req.params.id) {
+  if (item.sessionId !== req.rootSessionId) {
     return res.status(400).json({ error: 'Canvas item does not belong to this session' });
   }
 
@@ -302,13 +271,9 @@ router.get('/:id/canvas/:itemId/content', (req, res) => {
 // GET /api/sessions/:id/canvas/file/:filename - Get canvas file by filename
 // Writes the file to /tmp and returns the file path for Claude's Read tool
 // Always returns the latest version
-router.get('/:id/canvas/file/:filename', async (req, res) => {
-  const { id: sessionId, filename } = req.params;
-
-  const session = sessions.getById(sessionId);
-  if (!session) {
-    return res.status(404).json({ error: ERR_SESSION_NOT_FOUND });
-  }
+router.get('/:id/canvas/file/:filename', requireRootSessionAndProject, async (req, res) => {
+  const { filename } = req.params;
+  const sessionId = req.rootSessionId;
 
   // Get all versions of this file (newest first)
   const allVersions = canvasItems.getAllVersionsByFilename(sessionId, filename);

package/packages/server/src/api/commandButtons.js

@@ -8,6 +8,7 @@ import { databaseManager } from '../db/DatabaseManager.js';
 
 // Error message constants
 const ERR_SESSION_NOT_FOUND = 'Session not found';
+const ERR_BUTTON_NOT_FOUND = 'Circus Command not found';
 
 const router = Router({ mergeParams: true });
 
@@ -64,14 +65,14 @@ function broadcastCommandRunError({ sessionId, projectId, runId, buttonId, error
   });
 }
 
-// GET /api/projects/:projectId/command-buttons - List all command buttons for project
+// GET /api/projects/:projectId/circus-commands - List all command buttons for project
 router.get('/', (req, res) => {
   const { projectId } = req.params;
   const buttons = commandButtons.getByProjectId(projectId);
   res.json(buttons);
 });
 
-// GET /api/projects/:projectId/command-buttons/latest-runs - Get latest run for each button per session in project
+// GET /api/projects/:projectId/circus-commands/latest-runs - Get latest run for each button per session in project
 router.get('/latest-runs', (req, res) => {
   const { projectId } = req.params;
 
@@ -85,7 +86,7 @@ router.get('/latest-runs', (req, res) => {
   res.json(latestRuns);
 });
 
-// POST /api/projects/:projectId/command-buttons - Create new command button
+// POST /api/projects/:projectId/circus-commands - Create new command button
 router.post('/', (req, res) => {
   const result = CreateCommandButtonRequest.safeParse(req.body);
   if (!result.success) {
@@ -103,20 +104,20 @@ router.post('/', (req, res) => {
   res.status(201).json(button);
 });
 
-// GET /api/projects/:projectId/command-buttons/:id - Get single button
+// GET /api/projects/:projectId/circus-commands/:id - Get single button
 router.get('/:id', (req, res) => {
   const button = commandButtons.getById(req.params.id);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
   res.json(button);
 });
 
-// PATCH /api/projects/:projectId/command-buttons/:id - Update button
+// PATCH /api/projects/:projectId/circus-commands/:id - Update button
 router.patch('/:id', (req, res) => {
   const button = commandButtons.getById(req.params.id);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
 
   const result = UpdateCommandButtonRequest.safeParse(req.body);
@@ -135,18 +136,18 @@ router.patch('/:id', (req, res) => {
   res.json(updated);
 });
 
-// DELETE /api/projects/:projectId/command-buttons/:id - Delete button
+// DELETE /api/projects/:projectId/circus-commands/:id - Delete button
 router.delete('/:id', (req, res) => {
   const button = commandButtons.getById(req.params.id);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
 
   commandButtons.delete(req.params.id);
   res.status(204).send();
 });
 
-// POST /api/sessions/:sessionId/command-buttons/:buttonId/run - Execute button command
+// POST /api/sessions/:sessionId/circus-commands/:buttonId/run - Execute button command
 router.post('/run/:buttonId', (req, res) => {
   const { sessionId, buttonId } = req.params;
 
@@ -157,7 +158,7 @@ router.post('/run/:buttonId', (req, res) => {
 
   const button = commandButtons.getById(buttonId);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
 
   const workingDirectory = session.gitWorktree || session.project?.workingDirectory || process.cwd();
@@ -181,7 +182,7 @@ router.post('/run/:buttonId', (req, res) => {
   })();
 });
 
-// GET /api/sessions/:sessionId/command-buttons/runs - Get active runs for session
+// GET /api/sessions/:sessionId/circus-commands/runs - Get active runs for session
 router.get('/runs', (req, res) => {
   const { sessionId } = req.params;
 
@@ -221,7 +222,7 @@ router.get('/runs', (req, res) => {
   res.json(Array.from(runMap.values()));
 });
 
-// GET /api/sessions/:sessionId/command-buttons/runs/:runId - Get single run by ID
+// GET /api/sessions/:sessionId/circus-commands/runs/:runId - Get single run by ID
 router.get('/runs/:runId', (req, res) => {
   const { sessionId, runId } = req.params;
 
@@ -256,7 +257,7 @@ router.get('/runs/:runId', (req, res) => {
   });
 });
 
-// DELETE /api/sessions/:sessionId/command-buttons/runs/:runId - Delete a command run record
+// DELETE /api/sessions/:sessionId/circus-commands/runs/:runId - Delete a command run record
 router.delete('/runs/:runId', (req, res) => {
   const { sessionId, runId } = req.params;
 
@@ -292,7 +293,7 @@ router.delete('/runs/:runId', (req, res) => {
   res.status(204).send();
 });
 
-// POST /api/sessions/:sessionId/command-buttons/runs/:runId/kill - Kill running command
+// POST /api/sessions/:sessionId/circus-commands/runs/:runId/kill - Kill running command
 router.post('/runs/:runId/kill', (req, res) => {
   const { sessionId, runId } = req.params;
 

package/packages/server/src/api/index.js

@@ -14,6 +14,7 @@ import kanbanRouter from './kanban.js';
 import agentsRouter from './agents.js';
 import { getDbPath } from '../database.js';
 import { schedulerService } from '../services/schedulerService.js';
+import { isE2ESpawnCaptureEnabled } from '../services/e2eSpawnCapture.js';
 
 const router = Router();
 
@@ -29,6 +30,7 @@ router.get('/server-info', (_req, res) => {
     dbPath: getDbPath(),
     vcrMode: vcr && vcr.length > 0 ? vcr : null,
     schedulerRunning: schedulerService.isRunning(),
+    e2eSpawnCaptureEnabled: isE2ESpawnCaptureEnabled(),
   });
 });
 

package/packages/server/src/api/kanban.js

@@ -11,6 +11,7 @@ import {
   ReorderKanbanCardsRequest,
 } from '../../../shared/src/contracts/kanban.js';
 import { moveCard as moveCardService } from '../services/kanbanService.js';
+import { resolveBodyRootSessionForProject } from '../middleware/sessionLookup.js';
 
 const router = Router({ mergeParams: true });
 
@@ -215,7 +216,7 @@ router.put('/lanes/reorder', (req, res) => {
  * POST /api/projects/:projectId/kanban/cards
  * Add a session to the board (create card in a lane)
  */
-router.post('/cards', (req, res) => {
+router.post('/cards', resolveBodyRootSessionForProject('projectId'), (req, res) => {
   const { projectId } = req.params;
 
   const result = CreateKanbanCardRequest.safeParse(req.body);
@@ -223,7 +224,8 @@ router.post('/cards', (req, res) => {
     return res.status(400).json({ error: result.error.issues[0].message });
   }
 
-  const { sessionId, laneId } = result.data;
+  const { laneId } = result.data;
+  const sessionId = req.bodyRootSessionId;
 
   // Check if session already has a card
   const existingCard = kanbanCards.getBySessionId(sessionId);

package/packages/server/src/api/projects-commandButtons.js

@@ -4,11 +4,11 @@ import { CreateCommandButtonRequest, UpdateCommandButtonRequest } from '../../..
 
 // Error message constants
 const ERR_PROJECT_NOT_FOUND = 'Project not found';
-const ERR_BUTTON_NOT_FOUND = 'Command button not found';
+const ERR_BUTTON_NOT_FOUND = 'Circus Command not found';
 
 const router = Router({ mergeParams: true });
 
-// GET /api/projects/:id/command-buttons - List all command buttons for project
+// GET /api/projects/:id/circus-commands - List all command buttons for project
 router.get('/', (req, res) => {
   const project = projects.getById(req.params.id);
   if (!project) {
@@ -19,7 +19,7 @@ router.get('/', (req, res) => {
   res.json(buttons);
 });
 
-// POST /api/projects/:id/command-buttons - Create new command button
+// POST /api/projects/:id/circus-commands - Create new command button
 router.post('/', (req, res) => {
   const project = projects.getById(req.params.id);
   if (!project) {
@@ -42,7 +42,7 @@ router.post('/', (req, res) => {
   res.status(201).json(button);
 });
 
-// GET /api/projects/:id/command-buttons/:buttonId - Get single button
+// GET /api/projects/:id/circus-commands/:buttonId - Get single button
 router.get('/:buttonId', (req, res) => {
   const project = projects.getById(req.params.id);
   if (!project) {
@@ -56,7 +56,7 @@ router.get('/:buttonId', (req, res) => {
   res.json(button);
 });
 
-// PATCH /api/projects/:id/command-buttons/:buttonId - Update button
+// PATCH /api/projects/:id/circus-commands/:buttonId - Update button
 router.patch('/:buttonId', (req, res) => {
   const project = projects.getById(req.params.id);
   if (!project) {
@@ -77,7 +77,7 @@ router.patch('/:buttonId', (req, res) => {
   res.json(updated);
 });
 
-// DELETE /api/projects/:id/command-buttons/:buttonId - Delete button
+// DELETE /api/projects/:id/circus-commands/:buttonId - Delete button
 router.delete('/:buttonId', (req, res) => {
   const project = projects.getById(req.params.id);
   if (!project) {

package/packages/server/src/api/projects-helpers.js

@@ -1,22 +1,39 @@
+import { generateWorktreeBranch } from '../../../shared/src/index.js';
 import { isGitRepo } from '../services/gitService.js';
 
 /**
  * Validate and default git settings for git-backed projects.
  * If gitMode or gitBranch are missing for a git project, defaults are applied
- * (gitMode: 'none', gitBranch: 'main') instead of rejecting the request.
+ * instead of rejecting the request. Worktree sessions receive a generated branch
+ * so they never try to check out an already-active branch such as main.
+ * Current-mode sessions skip branch generation entirely.
  * @param {Object} config - The session configuration
  * @param {Object} project - The project object
  * @returns {Promise<{config: Object, error: string|null}>} Updated config and error message if validation fails.
  */
 export async function validateGitSettings(config, project) {
+  // Current mode: no branch needed, pass through as-is
+  if (config.gitMode === 'current') {
+    return {
+      config: {
+        ...config,
+        gitBranch: null,
+      },
+      error: null,
+    };
+  }
+
   if (!config.gitMode || !config.gitBranch) {
     const isGit = await isGitRepo(project.workingDirectory);
     if (isGit) {
+      const gitMode = config.gitMode || 'none';
       return {
         config: {
           ...config,
-          gitMode: config.gitMode || 'none',
-          gitBranch: config.gitBranch || 'main',
+          gitMode,
+          gitBranch: config.gitBranch || (gitMode === 'worktree'
+            ? generateWorktreeBranch(config.name, config.prompt)
+            : 'main'),
         },
         error: null,
       };

package/packages/server/src/api/projects-session-create.js

@@ -0,0 +1,109 @@
+import { sessions, projectDefaults } from '../database.js';
+import { ProjectDefaultsRepository } from '../db/ProjectDefaultsRepository.js';
+import { broadcastToProject } from '../websocket.js';
+import { WS_MESSAGE_TYPES } from '../../../shared/src/index.js';
+import {
+  generateInitialName,
+  prepareSessionConfig,
+  applyTemplateOverrides,
+  resolveNextTemplateId,
+  buildSchedulingUpdate,
+  setupAndStartSession,
+} from './projects-session-helpers.js';
+import { validateGitSettings } from './projects-helpers.js';
+
+/**
+ * Validate and prepare the session configuration from the request body.
+ * Returns { config, nextTemplateId } on success, or { error, status } on failure.
+ */
+export async function validateAndPrepareSessionConfig(reqBody, reqFiles, projectId, project) {
+  const projectDefs = projectDefaults.getByProjectId(projectId);
+  const systemDefaults = ProjectDefaultsRepository.getSystemDefaults();
+  const config = prepareSessionConfig(reqBody, projectDefs, systemDefaults);
+  config.files = reqFiles || [];
+
+  if (!config.prompt) {
+    return { error: 'Prompt is required', status: 400 };
+  }
+
+  if (config.schedulingError) {
+    return { error: config.schedulingError, status: 400 };
+  }
+
+  if (config.parentSessionId) {
+    const parentSession = sessions.getById(config.parentSessionId);
+    if (!parentSession) {
+      return { error: 'Parent session not found', status: 404 };
+    }
+    if (parentSession.projectId !== projectId) {
+      return { error: 'Parent session does not belong to this project', status: 400 };
+    }
+  }
+
+  // Apply template overrides and resolve nextTemplateId
+  applyTemplateOverrides(config);
+  const { nextTemplateId, error: nextTemplateError } = resolveNextTemplateId(reqBody, config.nextTemplateId || null);
+  if (nextTemplateError) {
+    return { error: nextTemplateError, status: 400 };
+  }
+  config.nextTemplateId = nextTemplateId;
+
+  // Validate git settings for git repos
+  const { config: updatedConfig, error: gitError } = await validateGitSettings(config, project);
+  if (gitError) {
+    return { error: gitError, status: 400 };
+  }
+  Object.assign(config, updatedConfig);
+
+  return { config, nextTemplateId };
+}
+
+/**
+ * Create the session row and apply any post-create updates.
+ * Returns the created session (already persisted in DB).
+ */
+export function createSessionRow(projectId, config, nextTemplateId, initialStatus) {
+  const sessionName = config.name || generateInitialName(config.prompt);
+  const session = sessions.create(projectId, sessionName, config.prompt, {
+    mode: config.mode,
+    thinkingEnabled: config.thinkingEnabled,
+    gitBranch: config.gitBranch,
+    parentSessionId: config.parentSessionId,
+    status: initialStatus,
+    model: config.model,
+    providerId: config.providerId,
+    effortLevel: config.effortLevel,
+    agentType: config.agentType,
+  });
+
+  const postCreateUpdate = {
+    ...(nextTemplateId ? { nextTemplateId } : {}),
+    ...buildSchedulingUpdate(config, initialStatus),
+  };
+  if (Object.keys(postCreateUpdate).length > 0) {
+    sessions.update(session.id, postCreateUpdate);
+  }
+  return session;
+}
+
+/**
+ * Run setupAndStartSession and translate any failure into an error response,
+ * marking the session as errored and broadcasting the update.
+ */
+export async function startSessionOrFail(req, res, { session, config, project }) {
+  try {
+    const { updatedSession } = await setupAndStartSession({
+      session, config, project, projectId: req.params.id, files: config.files,
+    });
+    return res.status(201).json(updatedSession);
+  } catch (error) {
+    console.error('Git setup error:', error);
+    const updatedSession = sessions.update(session.id, { status: 'error', error: error.message });
+    broadcastToProject(req.params.id, WS_MESSAGE_TYPES.SESSION_UPDATED, {
+      projectId: req.params.id,
+      sessionId: session.id,
+      session: updatedSession,
+    });
+    return res.status(500).json({ error: `Git setup failed: ${error.message}` });
+  }
+}

package/packages/server/src/api/projects-session-defaults.js

@@ -0,0 +1,51 @@
+import { Router } from 'express';
+import { projects, projectDefaults } from '../database.js';
+import { ProjectSessionDefaultsRequest } from '../../../shared/src/contracts/projects.js';
+
+const ERR_PROJECT_NOT_FOUND = 'Project not found';
+
+const router = Router({ mergeParams: true });
+
+// GET /api/projects/:id/session-defaults - Get session defaults for project
+router.get('/', (req, res) => {
+  const project = projects.getById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: ERR_PROJECT_NOT_FOUND });
+  }
+
+  const defaults = projectDefaults.getByProjectId(req.params.id);
+  if (!defaults) {
+    return res.json(null);
+  }
+
+  res.json(defaults);
+});
+
+// POST /api/projects/:id/session-defaults - Update/create session defaults for project
+router.post('/', (req, res) => {
+  const project = projects.getById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: ERR_PROJECT_NOT_FOUND });
+  }
+
+  const result = ProjectSessionDefaultsRequest.safeParse(req.body);
+  if (!result.success) {
+    return res.status(400).json({ error: result.error.issues[0].message });
+  }
+
+  const updated = projectDefaults.upsert(req.params.id, result.data);
+  res.status(200).json(updated);
+});
+
+// DELETE /api/projects/:id/session-defaults - Reset session defaults for project
+router.delete('/', (req, res) => {
+  const project = projects.getById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: ERR_PROJECT_NOT_FOUND });
+  }
+
+  projectDefaults.resetToDefaults(req.params.id);
+  res.json({ message: 'Session defaults reset to system defaults' });
+});
+
+export default router;