circuschief 0.8.0 → 1.1.0

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

@@ -0,0 +1,300 @@
+/**
+ * Migrations for the sessions table and closely related session tables.
+ * Each export is an array of { name, up(db) } migration objects.
+ */
+import { addColumnIfMissing, getColumns, getTableSql } from './migrationUtils.js';
+import { migrateSessionsDefaultModeAndThinking } from './sessionTableRecreate.js';
+
+// Table name constants for migrations
+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 'yolo' CHECK (mode IN ('plan', 'standard', 'yolo')),
+    thinking_enabled INTEGER NOT NULL DEFAULT 1,
+    git_branch TEXT,
+    git_worktree TEXT,
+    pr_url TEXT,
+    pr_url_auto_link_disabled INTEGER NOT NULL DEFAULT 0,
+    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,
+    thinking_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 60, -- keep in sync with DEFAULT_RESCHEDULE_DELAY_MINUTES in shared/constants.js
+    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', 'pr_url_auto_link_disabled', 'error', 'effort_level',
+  'cost_usd', 'claude_session_id', 'model', 'next_template_id',
+  'parent_session_id', 'input_tokens', 'output_tokens', 'thinking_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.
+ */
+function migrateSessionsStatusConstraint(db) {
+  const tableSql = getTableSql(db, TABLE_SESSIONS);
+
+  // If schema already includes 'scheduled', no migration needed
+  if (tableSql?.includes("'scheduled'")) {
+    return;
+  }
+
+  const columnNames = getColumns(db, TABLE_SESSIONS);
+  const selectColumns = SESSIONS_ALL_COLUMNS
+    .filter((col) => columnNames.includes(col))
+    .join(', ');
+
+  db.exec(`
+    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);
+    CREATE INDEX IF NOT EXISTS idx_sessions_starred ON sessions(archived, starred);
+    CREATE INDEX IF NOT EXISTS idx_sessions_next_template ON sessions(next_template_id);
+    CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id);
+    CREATE INDEX IF NOT EXISTS idx_sessions_scheduled ON sessions(scheduled_at) WHERE scheduled_at IS NOT NULL;
+  `);
+}
+
+/** @type {Array<{name: string, up: (db: import('better-sqlite3').Database) => void}>} */
+export const sessionsMigrations = [
+  // --- Initial sessions columns ---
+  {
+    name: 'sessions-add-cost_usd',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'cost_usd', 'REAL DEFAULT 0'); },
+  },
+  {
+    name: 'sessions-add-claude_session_id',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'claude_session_id', 'TEXT'); },
+  },
+  {
+    name: 'sessions-add-model',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'model', 'TEXT'); },
+  },
+  {
+    name: 'sessions-add-provider_id-early',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'provider_id', 'TEXT'); },
+  },
+  {
+    name: 'sessions-add-effort_level',
+    up(db) {
+      addColumnIfMissing(
+        db, TABLE_SESSIONS, 'effort_level',
+        "TEXT CHECK(effort_level IN ('low', 'medium', 'high', 'max', 'auto'))"
+      );
+    },
+  },
+
+  // --- Scheduling columns ---
+  {
+    name: 'sessions-add-scheduled_at',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'scheduled_at', 'INTEGER DEFAULT NULL'); },
+  },
+  {
+    name: 'sessions-add-reschedule_delay_minutes',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'reschedule_delay_minutes', 'INTEGER DEFAULT 60'); /* keep in sync with DEFAULT_RESCHEDULE_DELAY_MINUTES */ },
+  },
+  {
+    name: 'sessions-add-auto_reschedule_enabled',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'auto_reschedule_enabled', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'sessions-add-reschedule_on_token_limit',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'reschedule_on_token_limit', 'INTEGER DEFAULT 1'); },
+  },
+  {
+    name: 'sessions-add-reschedule_on_service_error',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'reschedule_on_service_error', 'INTEGER DEFAULT 1'); },
+  },
+  {
+    name: 'sessions-add-max_reschedule_count',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'max_reschedule_count', 'INTEGER DEFAULT NULL'); },
+  },
+  {
+    name: 'sessions-add-max_total_tokens',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'max_total_tokens', 'INTEGER DEFAULT NULL'); },
+  },
+  {
+    name: 'sessions-add-reschedule_count',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'reschedule_count', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'sessions-add-reschedule_at_token_count',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'reschedule_at_token_count', 'INTEGER DEFAULT NULL'); },
+  },
+
+  // --- Status constraint migration (table recreation) ---
+  {
+    name: 'sessions-migrate-status-constraint',
+    up(db) { migrateSessionsStatusConstraint(db); },
+  },
+
+  // --- Template chaining ---
+  {
+    name: 'sessions-add-next_template_id',
+    up(db) {
+      addColumnIfMissing(
+        db, TABLE_SESSIONS, 'next_template_id',
+        'TEXT REFERENCES session_templates(id) ON DELETE SET NULL'
+      );
+    },
+  },
+  {
+    name: 'sessions-add-parent_session_id',
+    up(db) {
+      addColumnIfMissing(
+        db, TABLE_SESSIONS, 'parent_session_id',
+        'TEXT REFERENCES sessions(id) ON DELETE SET NULL'
+      );
+    },
+  },
+  {
+    name: 'sessions-template-chaining-indexes',
+    up(db) {
+      db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_next_template ON sessions(next_template_id)');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id)');
+    },
+  },
+
+  // --- Token usage columns ---
+  {
+    name: 'sessions-add-input_tokens',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'input_tokens', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'sessions-add-output_tokens',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'output_tokens', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'sessions-add-thinking_tokens',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'thinking_tokens', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'sessions-add-cache_read_input_tokens',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'cache_read_input_tokens', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'sessions-add-cache_creation_input_tokens',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'cache_creation_input_tokens', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'sessions-add-web_search_requests',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'web_search_requests', COL_INTEGER_DEFAULT_0); },
+  },
+  {
+    name: 'sessions-add-context_window',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'context_window', 'INTEGER DEFAULT 200000'); },
+  },
+
+  // --- Archived / starred / manually_named ---
+  {
+    name: 'sessions-add-archived',
+    up(db) {
+      addColumnIfMissing(db, TABLE_SESSIONS, 'archived', 'INTEGER NOT NULL DEFAULT 0');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_archived ON sessions(archived)');
+    },
+  },
+  {
+    name: 'sessions-add-starred',
+    up(db) {
+      addColumnIfMissing(db, TABLE_SESSIONS, 'starred', 'INTEGER NOT NULL DEFAULT 0');
+      db.exec('CREATE INDEX IF NOT EXISTS idx_sessions_starred ON sessions(archived, starred)');
+    },
+  },
+  {
+    name: 'sessions-add-manually_named',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'manually_named', 'INTEGER NOT NULL DEFAULT 0'); },
+  },
+  {
+    name: 'sessions-add-pr_url_auto_link_disabled',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'pr_url_auto_link_disabled', 'INTEGER NOT NULL DEFAULT 0'); },
+  },
+
+  // --- Pending prompt / slash commands / pending model / auto send ---
+  {
+    name: 'sessions-add-pending_prompt',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'pending_prompt', 'TEXT'); },
+  },
+  {
+    name: 'sessions-add-slash_commands',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'slash_commands', 'TEXT'); },
+  },
+  {
+    name: 'sessions-add-pending_model',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'pending_model', 'TEXT'); },
+  },
+  {
+    name: 'sessions-add-auto_send_pending_prompt',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'auto_send_pending_prompt', COL_INTEGER_DEFAULT_0); },
+  },
+
+  // --- Provider ID (from providers table, added later in sequence) ---
+  {
+    name: 'sessions-add-provider_id-from-providers',
+    up(db) {
+      addColumnIfMissing(db, TABLE_SESSIONS, 'provider_id', 'TEXT REFERENCES providers(id)');
+    },
+  },
+
+  // --- Agent type ---
+  {
+    name: 'sessions-add-agent_type',
+    up(db) { addColumnIfMissing(db, TABLE_SESSIONS, 'agent_type', "TEXT DEFAULT 'claude-code'"); },
+  },
+
+  // --- Default mode / thinking changes ---
+  {
+    name: 'sessions-migrate-default-mode-thinking',
+    up(db) { migrateSessionsDefaultModeAndThinking(db); },
+  },
+
+];

package/packages/server/src/db/seedBaselineData.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { OPENAI_MODELS } from '../../../shared/src/index.js';
+import { OPENAI_MODELS, GEMINI_MODELS } from '../../../shared/src/index.js';
 
 export const BUILT_IN_ANTHROPIC_PROVIDER = {
   id: 'anthropic-default',
@@ -13,6 +13,12 @@ export const BUILT_IN_OPENAI_PROVIDER = {
   kind: 'openai',
 };
 
+export const BUILT_IN_GOOGLE_PROVIDER = {
+  id: 'google-default',
+  name: 'Google (Official)',
+  kind: 'google',
+};
+
 export const BUILT_IN_ANTHROPIC_MODELS = [
   { id: 'anthropic-haiku', providerId: BUILT_IN_ANTHROPIC_PROVIDER.id, modelId: 'claude-haiku-4-5-20251001', displayName: 'Haiku 4.5', description: 'Fast & lightweight', tier: 'haiku' },
   { id: 'anthropic-sonnet', providerId: BUILT_IN_ANTHROPIC_PROVIDER.id, modelId: 'claude-sonnet-4-6', displayName: 'Sonnet 4.6', description: 'Balanced', tier: 'sonnet' },
@@ -29,6 +35,15 @@ export const BUILT_IN_OPENAI_MODELS = OPENAI_MODELS.map((model) => ({
   tier: 'custom',
 }));
 
+export const BUILT_IN_GOOGLE_MODELS = GEMINI_MODELS.map((model) => ({
+  id: model.seedId,
+  providerId: BUILT_IN_GOOGLE_PROVIDER.id,
+  modelId: model.id,
+  displayName: model.name,
+  description: model.description,
+  tier: 'custom',
+}));
+
 export const DEFAULT_QUICK_RESPONSES = [
   { label: 'Put a plan on the canvas', content: 'Put a plan on the canvas to get this done', autoSubmit: false, sortOrder: 0 },
   { label: 'Yes', content: 'Yes', autoSubmit: true, sortOrder: 1 },
@@ -87,6 +102,13 @@ function seedBuiltInProviders(db) {
      VALUES (?, ?, ?, ?, ?, ?, ?)`
   );
 
+  // Note: Google provider and models are NOT seeded here because seedBaselineData
+  // runs before migrations. On existing databases the providers table still has
+  // CHECK(kind IN ('anthropic','openai')), so an INSERT with kind='google' would
+  // be silently ignored by INSERT OR IGNORE, and the subsequent model inserts
+  // would fail with a FOREIGN KEY constraint. The 'providers-seed-built-in-google'
+  // migration handles seeding Google for both fresh and existing databases after
+  // the 'providers-widen-kind-check-google' migration has widened the CHECK constraint.
   for (const model of [...BUILT_IN_ANTHROPIC_MODELS, ...BUILT_IN_OPENAI_MODELS]) {
     insertModel.run(model.id, model.providerId, model.modelId, model.displayName, model.description, model.tier, now);
   }

package/packages/server/src/db/session-helpers.js

@@ -7,7 +7,32 @@ import { DEFAULT_RESCHEDULE_DELAY_MINUTES } from '../../../shared/src/index.js';
 
 /** Reusable SQL fragment for computed activity fields on sessions */
 export const ACTIVITY_FIELDS_SQL = `
-  (SELECT MAX(cm.timestamp) FROM conversation_messages cm WHERE cm.session_id = s.id) AS last_activity_at,
+  (
+    SELECT MAX(activity_at)
+    FROM (
+      SELECT cm.timestamp AS activity_at
+      FROM conversation_messages cm
+      WHERE cm.session_id = s.id
+      UNION ALL
+      SELECT ss.generated_at AS activity_at
+      FROM session_summaries ss
+      WHERE ss.session_id = s.id
+      UNION ALL
+      SELECT ss.updated_at AS activity_at
+      FROM session_summaries ss
+      WHERE ss.session_id = s.id
+      UNION ALL
+      SELECT COALESCE(cr.completed_at, cr.started_at) AS activity_at
+      FROM command_runs cr
+      WHERE cr.session_id = s.id
+    )
+    WHERE activity_at IS NOT NULL
+  ) AS last_activity_at,
+  (
+    SELECT MAX(cm.timestamp)
+    FROM conversation_messages cm
+    WHERE cm.session_id = s.id
+  ) AS last_message_at,
   (CAST(
     CASE
       WHEN (SELECT MAX(cm2.timestamp) FROM conversation_messages cm2 WHERE cm2.session_id = s.id) IS NOT NULL

package/packages/server/src/schema.sql

@@ -26,6 +26,10 @@ CREATE TABLE IF NOT EXISTS session_templates (
   mode TEXT DEFAULT 'yolo' CHECK(mode IN ('plan', 'standard', 'yolo')),
   effort_level TEXT CHECK(effort_level IN ('low', 'medium', 'high', 'max', 'auto')),
   target_lane_id TEXT REFERENCES kanban_lanes(id) ON DELETE SET NULL,
+  show_in_quick_responses INTEGER NOT NULL DEFAULT 0,
+  quick_response_auto_submit INTEGER NOT NULL DEFAULT 0,
+  quick_response_sort_order INTEGER NOT NULL DEFAULT 0,
+  legacy_quick_response_id TEXT UNIQUE,
   created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
   updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
 );
@@ -39,7 +43,7 @@ CREATE TABLE IF NOT EXISTS providers (
   additional_env_vars TEXT,
   commit_attribution_override TEXT,
   is_built_in INTEGER NOT NULL DEFAULT 0,
-  kind TEXT NOT NULL DEFAULT 'anthropic' CHECK(kind IN ('anthropic','openai')),
+  kind TEXT NOT NULL DEFAULT 'anthropic' CHECK(kind IN ('anthropic','openai','google')),
   created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
   updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
 );

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

@@ -13,36 +13,38 @@ export function buildCommandButtonApiInstructions(apiUrl, sessionId, projectId)
     return '';
   }
 
-  return `## Commands API
+  return `## Circus Commands
 
-This project has commands configured - reusable shell commands you can execute. Use the Bash tool to run these curl commands.
+This project has Circus Commands configured - reusable shell commands you can execute. Use the Bash tool to run these curl commands.
+
+> When the user asks to "run a command", "what commands are available", "list circus commands", or similar, use the Commands API below to discover and execute them.
 
 ### List Available Commands
 \`\`\`bash
-curl ${apiUrl}/api/sessions/${sessionId}/command-buttons
+curl ${apiUrl}/api/sessions/${sessionId}/circus-commands
 \`\`\`
 
 ### Run a Command
 \`\`\`bash
-curl -X POST ${apiUrl}/api/sessions/${sessionId}/command-buttons/<button_id>/run
+curl -X POST ${apiUrl}/api/sessions/${sessionId}/circus-commands/<button_id>/run
 \`\`\`
 
 Response: { runId, buttonId, status: "running", output: "" }
 
 ### Check Run Status & Output
 \`\`\`bash
-curl ${apiUrl}/api/sessions/${sessionId}/command-buttons/runs/<run_id>
+curl ${apiUrl}/api/sessions/${sessionId}/circus-commands/runs/<run_id>
 \`\`\`
 
 Response: { runId, buttonId, status, exitCode, output, startedAt, completedAt }
 
 ### List Command Runs
 \`\`\`bash
-curl ${apiUrl}/api/sessions/${sessionId}/command-buttons/runs
+curl ${apiUrl}/api/sessions/${sessionId}/circus-commands/runs
 \`\`\`
 
 ### Kill a Running Command
 \`\`\`bash
-curl -X POST ${apiUrl}/api/sessions/${sessionId}/command-buttons/runs/<run_id>/kill
+curl -X POST ${apiUrl}/api/sessions/${sessionId}/circus-commands/runs/<run_id>/kill
 \`\`\``;
 }

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

@@ -49,9 +49,12 @@ export function createCapturedSpawnProcess(agentType) {
     });
   };
 
-  if (agentType === 'claude-code') {
+  if (agentType === 'claude-code' || agentType === 'gemini') {
+    // Claude Code and Gemini don't pass prompts via stdin (they use CLI args).
+    // Complete after a short delay to simulate process execution.
     setTimeout(complete, 10);
   } else {
+    // Codex passes the prompt via stdin; complete when stdin is closed.
     stdin.once('finish', complete);
   }
 
@@ -59,12 +62,15 @@ export function createCapturedSpawnProcess(agentType) {
 }
 
 function summarizeSpawnEnv(env = {}) {
-  if (!Object.prototype.hasOwnProperty.call(env, 'CIRCUSCHIEF_COMMIT_ATTRIBUTION')) {
-    return {};
+  const summary = {};
+  if (Object.prototype.hasOwnProperty.call(env, 'CIRCUSCHIEF_COMMIT_ATTRIBUTION')) {
+    summary.CIRCUSCHIEF_COMMIT_ATTRIBUTION = env.CIRCUSCHIEF_COMMIT_ATTRIBUTION;
   }
-  return {
-    CIRCUSCHIEF_COMMIT_ATTRIBUTION: env.CIRCUSCHIEF_COMMIT_ATTRIBUTION,
-  };
+  if (Object.prototype.hasOwnProperty.call(env, 'GEMINI_CLI_TRUST_WORKSPACE')) {
+    summary.GEMINI_CLI_TRUST_WORKSPACE = env.GEMINI_CLI_TRUST_WORKSPACE;
+  }
+  if (Object.keys(summary).length === 0) return {};
+  return summary;
 }
 
 function summarizeSpawnOptions(agentType, spawnOptions) {
@@ -78,6 +84,15 @@ function summarizeSpawnOptions(agentType, spawnOptions) {
     };
   }
 
+  if (agentType === 'gemini') {
+    return {
+      model: valueAfter(args, '-m'),
+      outputFormat: valueAfter(args, '--output-format'),
+      approvalMode: optionValue(args, '--approval-mode'),
+      prompt: valueAfter(args, '-p'),
+    };
+  }
+
   return {
     model: valueAfter(args, '-m'),
     sandbox: valueAfter(args, '--sandbox'),
@@ -91,6 +106,14 @@ function valueAfter(args, flag) {
   return args[index + 1] ?? null;
 }
 
+function optionValue(args, flag) {
+  const separateValue = valueAfter(args, flag);
+  if (separateValue !== null) return separateValue;
+  const prefix = `${flag}=`;
+  const arg = args.find((value) => value.startsWith(prefix));
+  return arg ? arg.slice(prefix.length) : null;
+}
+
 function valuesAfter(args, flag) {
   const values = [];
   for (let index = 0; index < args.length; index += 1) {
@@ -116,6 +139,24 @@ function writeCapturedAgentEvents(agentType, stdout) {
     return;
   }
 
+  if (agentType === 'gemini') {
+    // Gemini CLI stream-json format: init → message → result
+    writeJsonLine(stdout, {
+      type: 'init',
+      session_id: `e2e-gemini-${Date.now()}`,
+    });
+    writeJsonLine(stdout, {
+      type: 'message',
+      role: 'assistant',
+      content: 'E2E spawn capture response.',
+    });
+    writeJsonLine(stdout, {
+      type: 'result',
+      stats: { input_tokens: 0, output_tokens: 0 },
+    });
+    return;
+  }
+
   writeJsonLine(stdout, {
     type: 'system',
     subtype: 'init',

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

@@ -0,0 +1,47 @@
+import { spawn } from 'child_process';
+import { createRobustEnv } from './nodeSpawnHelper.js';
+import {
+  captureSpawnAttempt,
+  createCapturedSpawnProcess,
+  isE2ESpawnCaptureEnabled,
+} from './e2eSpawnCapture.js';
+
+/**
+ * Create a custom spawn function for the Gemini CLI.
+ *
+ * Mirrors {@link createCodexSpawner} but for the `gemini` command.
+ *
+ * As with other CLI helpers:
+ *   - The command 'node' is replaced with {@link process.execPath} so child
+ *     processes use the same Node binary.
+ *   - `createRobustEnv` guarantees the Node bin directory is on PATH.
+ *
+ * @returns {Function} Spawn function of shape (options) => childProcess
+ */
+export function createGeminiSpawner() {
+  return (options) => {
+    const { command, args, cwd, env, signal } = options;
+    // Replace 'node' with the absolute path to the current Node executable
+    const actualCommand = command === 'node' ? process.execPath : command;
+
+    // Ensure PATH includes the directory containing Node
+    const robustEnv = createRobustEnv(env);
+
+    // Trust the workspace automatically in headless/automated mode.
+    // Without this, Gemini CLI refuses to run in untrusted directories.
+    robustEnv.GEMINI_CLI_TRUST_WORKSPACE = 'true';
+
+    if (isE2ESpawnCaptureEnabled()) {
+      captureSpawnAttempt('gemini', { ...options, env: robustEnv });
+      return createCapturedSpawnProcess('gemini');
+    }
+
+    return spawn(actualCommand, args, {
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      signal,
+      env: robustEnv,
+      windowsHide: true,
+    });
+  };
+}

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

@@ -1,10 +1,38 @@
 import { exec } from 'child_process';
 import { promisify } from 'util';
+import os from 'os';
 import path from 'path';
 import { chmod, mkdir, writeFile } from 'fs/promises';
 
 const execAsync = promisify(exec);
-const MANAGED_HOOKS_PATH = '.circuschief-hooks';
+
+const DEFAULT_MANAGED_HOOKS_PATH = path.join(os.homedir(), '.circuschief', 'hooks');
+let _managedHooksPath = DEFAULT_MANAGED_HOOKS_PATH;
+
+/**
+ * Get the managed hooks directory path.
+ * Production code uses the real home directory; tests can override via _setManagedHooksPath().
+ * @returns {string}
+ */
+export function getManagedHooksPath() {
+  return _managedHooksPath;
+}
+
+/**
+ * Override the managed hooks path (for testing only).
+ * Restores the default when called with no arguments.
+ * @param {string} [overridePath]
+ */
+export function _setManagedHooksPath(overridePath) {
+  _managedHooksPath = overridePath ?? DEFAULT_MANAGED_HOOKS_PATH;
+}
+
+/**
+ * Legacy managed hooks path (pre-migration). Used by ensureWorktreeCommitAttributionHook()
+ * to recognize and auto-upgrade worktrees that still have the old relative path set.
+ */
+const LEGACY_MANAGED_HOOKS_PATH = '.circuschief-hooks';
+
 const ATTRIBUTION_CONFIG_KEY = 'circuschief.commitAttribution';
 const ATTRIBUTION_ENV_KEY = 'CIRCUSCHIEF_COMMIT_ATTRIBUTION';
 
@@ -54,9 +82,10 @@ git interpret-trailers --trailer "$trailer" --in-place "$msg_file"
 }
 
 export async function clearWorktreeCommitAttribution(worktreePath) {
+  const managedHooksPath = getManagedHooksPath();
   const currentAttribution = await gitConfigValue(worktreePath, ATTRIBUTION_CONFIG_KEY);
   const currentHooksPath = await gitConfigValue(worktreePath, 'core.hooksPath');
-  if (!currentAttribution && currentHooksPath !== MANAGED_HOOKS_PATH) {
+  if (!currentAttribution && currentHooksPath !== managedHooksPath) {
     return false;
   }
 
@@ -70,7 +99,7 @@ export async function clearWorktreeCommitAttribution(worktreePath) {
     }
   }
 
-  if (currentHooksPath === MANAGED_HOOKS_PATH) {
+  if (currentHooksPath === managedHooksPath) {
     try {
       await git(worktreePath, 'config --worktree --unset core.hooksPath');
     } catch {
@@ -90,10 +119,12 @@ export async function clearWorktreeCommitAttribution(worktreePath) {
  * @returns {Promise<boolean>} True when a hook is installed or updated
  */
 export async function ensureWorktreeCommitAttributionHook(worktreePath) {
+  const managedHooksPath = getManagedHooksPath();
+
   await git(worktreePath, 'config extensions.worktreeConfig true');
 
   const currentHooksPath = await gitConfigValue(worktreePath, 'core.hooksPath');
-  if (currentHooksPath && currentHooksPath !== MANAGED_HOOKS_PATH) {
+  if (currentHooksPath && currentHooksPath !== managedHooksPath && currentHooksPath !== LEGACY_MANAGED_HOOKS_PATH) {
     throw new Error(
       `Cannot install managed commit attribution hook: worktree already has core.hooksPath set to "${currentHooksPath}"`
     );
@@ -105,11 +136,10 @@ export async function ensureWorktreeCommitAttributionHook(worktreePath) {
     // Unset is idempotent for stale worktrees that never stored attribution.
   }
 
-  await git(worktreePath, `config --worktree core.hooksPath ${shellQuote(MANAGED_HOOKS_PATH)}`);
+  await git(worktreePath, `config --worktree core.hooksPath ${shellQuote(managedHooksPath)}`);
 
-  const hooksDir = path.join(worktreePath, MANAGED_HOOKS_PATH);
-  const hookPath = path.join(hooksDir, 'commit-msg');
-  await mkdir(hooksDir, { recursive: true });
+  const hookPath = path.join(managedHooksPath, 'commit-msg');
+  await mkdir(managedHooksPath, { recursive: true });
   await writeFile(hookPath, buildCommitMsgHook(), 'utf8');
   await chmod(hookPath, 0o755);
   return true;