Auctor — Technical Addendum #5

Desktop Agent: Implementation Guide

Status: Pre-build specification Depends on: Addendum #4 (SDK embedding pattern), Phases 1–3 (MCP server, workspace, activation) Scope: Everything required to package Auctor as a desktop application — framework decision, architecture, file-by-file implementation, build tooling, and deployment

1. Framework Decision: Electron

The case that was made for Tauri — and why Electron still wins for Auctor

Conductor (the inspiration project, com.conductor.app) ships on Tauri 2.0 with bundled sidecars: claude, codex, gh, node, and watchexec. This proved the pattern works. Tauri's advantages are real: ~30 MB bundle vs ~180 MB, near-zero idle CPU, capability-based permissions, compiled Rust binary. For a greenfield project, Tauri would be the stronger choice.

Auctor is not greenfield. Three factors tip the decision:

Factor 1: The @anthropic-ai/claude-code SDK is a Node.js package.

The SDK's query() function — the async-generator-based embedding pattern that handles process lifecycle, stream-json parsing, multi-turn conversation, canUseTool callbacks, hook registration, environment assembly, and session reuse — runs in Node.js. In Electron, this runs directly in the main process. In Tauri, you'd need to either:

Bundle a Node.js sidecar that hosts the SDK, then build a Rust↔Node IPC layer to bridge query() events to the Tauri core. Every canUseTool callback (which must resolve synchronously from Claude Code's perspective) would cross a process boundary. The requestOperatorApproval() flow — which goes SDK → main process → renderer → user click → renderer → main process → SDK — would add a Rust↔Node hop at each step.
Reimplement the SDK's embedding logic in Rust, calling the claude binary directly with Command::new(). This loses the async generator pattern, the canUseTool callback, the hooks integration, accountInfo(), mcpServerStatus(), and session reuse — all of which the SDK provides for free.

Conductor likely takes the second approach (raw sidecar management). Auctor's spec depends on the first (SDK-level embedding). The SDK is the integration surface; Electron is the native host.

Factor 2: The MCP server shares the Node.js runtime.

Auctor's MCP server imports Drizzle ORM, Mastra runtime, DataForSEO adapters, ConsulPublisher, and analytics providers — all TypeScript. In Electron, the MCP server runs in-process in the main thread, sharing the database connection pool with the Next.js dashboard. No sidecar, no IPC, no second Node.js process. In Tauri, the MCP server must run as a Node.js sidecar with its own process, its own DB pool, and an IPC bridge. The "shared runtime" is not elegance — it's a concrete reduction in connection overhead and process management complexity.

Factor 3: The dashboard uses Next.js server components.

The existing dashboard (metrics, pipeline view, agent timeline, memory browser) uses React Server Components for data fetching. In Electron, Next.js runs natively — next start in the main process, BrowserWindow pointed at localhost:3000. In Tauri, you either refactor to a Vite SPA (2–3 weeks of work, loss of RSC patterns) or run Next.js as yet another sidecar. The refactoring cost delays Phase 4 delivery with no functional gain.

The tradeoff accepted: Auctor ships at ~180 MB instead of ~40 MB. It uses ~150 MB idle RAM instead of ~50 MB. Cold start is 2–3 seconds instead of sub-second. These costs are acceptable because Auctor runs on a dedicated machine (not a user's daily driver) and stays open 24/7 (cold start frequency is near-zero). The bundle size difference matters for consumer distribution — Auctor is deployed to one machine per operator.

If conditions change: If the project later needs mobile support, consumer distribution, or multi-operator deployment, the MCP server (Phase 1) and workspace (Phase 2) are framework-agnostic. The migration surface is Layer 4 only — the desktop shell. Phases 1–3 would not change.

2. Architecture: What Gets Built in Phase 4

desktop/
├── package.json                 # Electron + electron-builder + SDK deps
├── tsconfig.json                # TypeScript config for desktop package
├── main.ts                      # Electron entry: orchestrates all subsystems
├── preload.ts                   # Context bridge: window.electron API
├── claude-code-manager.ts       # SDK-based session lifecycle manager
├── mcp-bridge.ts                # In-process MCP server initialization
├── scheduler.ts                 # node-cron autonomous session scheduler
├── file-watcher.ts              # Workspace change observer → IPC emitter
├── sidecar.ts                   # Python/FastAPI child process manager
├── env-assembly.ts              # 6-layer credential assembly
├── ipc-handlers.ts              # All IPC handler registrations
├── auth-verifier.ts             # Pre-session credential + workspace probe
├── types.ts                     # Shared TypeScript interfaces
└── build/
    ├── electron-builder.yml     # Build + packaging config
    ├── entitlements.mac.plist   # macOS sandbox entitlements
    └── notarize.js              # macOS notarization script

Process architecture at runtime

┌─────────────────────────────────────────────────────────────────┐
│  Electron Main Process (Node.js)                                │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  Subsystems (initialized in main.ts, order matters)       │  │
│  │                                                           │  │
│  │  1. Environment loader       (dotenv → process.env)       │  │
│  │  2. MCP server (in-process)  (McpServer + domain tools)   │  │
│  │  3. Next.js server           (next start → :3000)         │  │
│  │  4. Python sidecar           (FastAPI → :8000)            │  │
│  │  5. Claude Code Manager      (SDK query() lifecycle)      │  │
│  │  6. File watcher             (chokidar on workspace)      │  │
│  │  7. Scheduler                (node-cron → manager)        │  │
│  │  8. IPC handlers             (bridge to renderer)         │  │
│  │  9. BrowserWindow            (loads localhost:3000)        │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Child processes managed by main:                               │
│                                                                 │
│  ┌────────────────────┐  ┌──────────────────────────────────┐  │
│  │ Python/FastAPI      │  │ Claude Code (via SDK query())    │  │
│  │ LangExtract :8000   │  │ One process per active session   │  │
│  │ Lifecycle: app      │  │ Lifecycle: session               │  │
│  └────────────────────┘  │ Max 5 idle, 30-min timeout       │  │
│                           │ Parent PID watchdog: 2s interval  │  │
│                           └──────────────────────────────────┘  │
│                                                                 │
│  Shared resources:                                              │
│  • DB connection pool (Drizzle → Supabase Postgres)            │
│  • Environment variables (6-layer assembled)                    │
│  • Workspace path (~/.auctor/workspace/)                       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  Electron Renderer Process (Chromium)                           │
│                                                                 │
│  Next.js app loaded from http://localhost:3000                  │
│                                                                 │
│  Routes:                                                        │
│  /              → Dashboard (metrics, pipeline overview)        │
│  /chat          → Agent Chat Panel (stream-json UI)             │
│  /sessions      → Session timeline (scheduled + interactive)    │
│  /workspace     → File browser for ~/.auctor/workspace/         │
│  /memory        → Memory viewer (observations, decisions, etc.) │
│  /calendar      → Editorial calendar                            │
│  /settings      → Agent config, API keys, schedule              │
│                                                                 │
│  Communication:                                                 │
│  window.electron.invoke()  → main process (request/response)   │
│  window.electron.on()      → main process (event stream)       │
└─────────────────────────────────────────────────────────────────┘

3. File-by-File Implementation

3.1 `desktop/package.json`

{
  "name": "auctor-desktop",
  "version": "0.1.0",
  "description": "Auctor Autonomous Content Operations Agent",
  "main": "dist/main.js",
  "scripts": {
    "dev": "tsc && electron dist/main.js",
    "dev:watch": "concurrently \"tsc -w\" \"nodemon --watch dist --exec electron dist/main.js\"",
    "build": "tsc && electron-builder",
    "build:mac": "tsc && electron-builder --mac",
    "build:win": "tsc && electron-builder --win",
    "build:linux": "tsc && electron-builder --linux"
  },
  "dependencies": {
    "@anthropic-ai/claude-code": "^1.0.0",
    "chokidar": "^4.0.0",
    "dotenv": "^16.4.0",
    "electron-updater": "^6.3.0",
    "node-cron": "^3.0.3"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "@types/node-cron": "^3.0.11",
    "concurrently": "^9.0.0",
    "electron": "^40.0.0",
    "electron-builder": "^25.0.0",
    "nodemon": "^3.0.0",
    "typescript": "^5.7.0"
  },
  "build": {
    "appId": "com.auctor.desktop",
    "productName": "Auctor",
    "directories": {
      "output": "release"
    },
    "files": [
      "dist/**/*",
      "node_modules/**/*",
      "!node_modules/**/README.md"
    ],
    "extraResources": [
      {
        "from": "../frontend/.next/standalone",
        "to": "next-server",
        "filter": ["**/*"]
      }
    ],
    "mac": {
      "category": "public.app-category.productivity",
      "hardenedRuntime": true,
      "gatekeeperAssess": false,
      "entitlements": "build/entitlements.mac.plist",
      "entitlementsInherit": "build/entitlements.mac.plist",
      "target": [
        { "target": "dmg", "arch": ["universal"] },
        { "target": "zip", "arch": ["universal"] }
      ]
    },
    "win": {
      "target": [
        { "target": "nsis", "arch": ["x64"] }
      ]
    },
    "linux": {
      "target": [
        { "target": "AppImage", "arch": ["x64"] },
        { "target": "deb", "arch": ["x64"] }
      ]
    }
  }
}

Key decisions in this config:

extraResources bundles the Next.js standalone output. At runtime, main.ts spawns node next-server/server.js rather than running next start (which requires the full node_modules tree). The standalone output is self-contained.
electron-updater is included for auto-update support (not implemented in Phase 4, but the dependency is present for Phase 5).
@anthropic-ai/claude-code is a runtime dependency, not dev-only. It must be in the packaged app.
Universal macOS builds ensure Apple Silicon and Intel compatibility.

3.2 `desktop/types.ts`

All shared interfaces used across the desktop package. Define these first — everything else imports from here.

// desktop/types.ts

/** Session types map to different Claude Code spawn configurations */
export type SessionType = 'interactive' | 'scheduled' | 'event-triggered'

/** Configuration for starting a new Claude Code session */
export interface SessionConfig {
  type: SessionType
  /** For headless sessions: the single prompt to execute */
  prompt?: string
  /** For resume: reuse an existing session ID */
  sessionId?: string
  /** Model override (default: claude-sonnet-4-20250514) */
  model?: string
  /** Additional system prompt context injected at runtime */
  appendSystemPrompt?: string
  /** Max turns before auto-stop (default: 1000 interactive, 100 scheduled) */
  maxTurns?: number
}

/** Internal session tracking state */
export interface Session {
  id: string
  type: SessionType
  /** The SDK query result — async iterable of events */
  queryResult: AsyncIterableClaudeResult
  /** Pending messages for the async generator to yield */
  messageQueue: string[]
  /** Resolver function: when set, the async generator is awaiting a message */
  resolveNextMessage: ((msg: string) => void) | null
  /** Whether Claude Code is currently processing (between user message and result event) */
  isProcessing: boolean
  /** Timestamp of last activity (message sent or event received) */
  lastActivityAt: number
  /** Settings snapshot for change detection */
  currentSettings: { model: string }
}

/**
 * The return type of the SDK's query() function.
 * Async iterable of events + control methods.
 */
export interface AsyncIterableClaudeResult extends AsyncIterable<ClaudeEvent> {
  interrupt(): void
  accountInfo(): Promise<AccountInfo>
  supportedCommands(): Promise<string[]>
  mcpServerStatus(): Promise<McpServerStatus[]>
}

/** Structured event from Claude Code's stream-json output */
export interface ClaudeEvent {
  type:
    | 'assistant:text'
    | 'assistant:tool_use'
    | 'tool:result'
    | 'system:error'
    | 'result'
  data: unknown
}

export interface AccountInfo {
  email: string
  plan: string
  capabilities: string[]
}

export interface McpServerStatus {
  name: string
  status: 'connected' | 'error' | 'pending'
  toolCount?: number
  error?: string
}

/** IPC channel definitions — type-safe bridge between main and renderer */
export interface IpcChannels {
  // Renderer → Main (invoke/handle)
  'claude:start-session': (config: SessionConfig) => Promise<string>
  'claude:send-message': (args: { sessionId: string; message: string }) => void
  'claude:stop-session': (args: { sessionId: string }) => void
  'claude:get-sessions': () => Promise<SessionSummary[]>
  'claude:verify-auth': () => Promise<AuthResult>
  'workspace:read-file': (args: { relativePath: string }) => Promise<string>
  'workspace:list-dir': (args: { relativePath: string }) => Promise<string[]>
  'settings:get': () => Promise<AppSettings>
  'settings:set': (settings: Partial<AppSettings>) => void

  // Main → Renderer (send/on)
  'claude:event': (payload: { sessionId: string; event: ClaudeEvent }) => void
  'claude:session-ended': (payload: { sessionId: string }) => void
  'claude:session-error': (payload: { sessionId: string; error: string }) => void
  'workspace:file-changed': (payload: { path: string; relative: string; timestamp: number }) => void
}

export interface SessionSummary {
  id: string
  type: SessionType
  isProcessing: boolean
  lastActivityAt: number
}

export interface AuthResult {
  authenticated: boolean
  email?: string
  plan?: string
  error?: string
}

export interface AppSettings {
  /** User-configured env vars (KEY=VALUE per line) */
  claudeEnvVars: string
  /** Model selection */
  model: string
  /** Schedule toggles */
  schedule: {
    morningEnabled: boolean
    morningTime: string    // HH:MM
    middayEnabled: boolean
    middayTime: string
    eveningEnabled: boolean
    eveningTime: string
    weeklyEnabled: boolean
    weeklyDay: number      // 0=Sun, 1=Mon, ...
    weeklyTime: string
  }
  /** Active site key */
  siteKey: string
}

/** Credential keys stripped from shell environment before assembly */
export const STRIPPED_ENV_KEYS = [
  'ANTHROPIC_API_KEY',
  'ANTHROPIC_AUTH_TOKEN',
  'OPENAI_API_KEY',
  'CLAUDE_CODE_USE_BEDROCK',
  'CLAUDE_CODE_USE_VERTEX',
  'AWS_ACCESS_KEY_ID',
  'AWS_SECRET_ACCESS_KEY',
  'GOOGLE_APPLICATION_CREDENTIALS',
] as const

3.3 `desktop/env-assembly.ts`

The 6-layer environment assembly extracted into its own module. This is security-critical — it controls what credentials Claude Code can see.

// desktop/env-assembly.ts

import { STRIPPED_ENV_KEYS } from './types'

/**
 * Assemble the environment for a Claude Code process.
 *
 * Layer priority (highest wins):
 *   6. GitHub token
 *   5. User-configured API keys (from app settings UI)
 *   4. Auctor platform env (DATABASE_URL, Supabase, DataForSEO, etc.)
 *   3. Application-specific flags
 *   2. Node process.env (filtered)
 *   1. Shell environment (with sensitive keys STRIPPED)
 *
 * Why strip shell env first: the operator's shell might have ANTHROPIC_API_KEY
 * set for personal use. Auctor should use the key configured in its settings UI,
 * not whatever happens to be in .bashrc. Stripping first, then layering user
 * config on top, ensures Auctor's auth is deterministic.
 */
export function assembleEnvironment(options: {
  userClaudeEnvVars?: string
  platformEnv: Record<string, string>
  ghToken?: string
}): Record<string, string> {
  const env: Record<string, string> = {}

  // Layer 1: Shell environment with sensitive keys stripped
  for (const [key, value] of Object.entries(process.env)) {
    if (value === undefined) continue
    if ((STRIPPED_ENV_KEYS as readonly string[]).includes(key)) continue
    env[key] = value
  }

  // Layer 2: (merged with Layer 1 above — process.env IS the shell env in Electron)

  // Layer 3: Application-specific flags
  env['CLAUDE_CODE_ENABLE_TASKS'] = 'true'
  // Prevent Claude Code from trying to open a browser for OAuth
  env['CLAUDE_CODE_DISABLE_BROWSER'] = '1'

  // Layer 4: Auctor platform env
  // These are loaded from .env.local at app startup and include:
  //   DATABASE_URL, DIRECT_URL, SUPABASE_URL, SUPABASE_ANON_KEY,
  //   SUPABASE_SERVICE_ROLE_KEY, DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD,
  //   ANTHROPIC_API_KEY (for Mastra agent LLM calls, NOT for Claude Code auth),
  //   GOOGLE_ANALYTICS_*, CONSUL_CMS_*, etc.
  for (const [key, value] of Object.entries(options.platformEnv)) {
    env[key] = value
  }

  // Layer 5: User-configured API keys (highest priority for auth)
  // Parsed from KEY=VALUE format stored in app settings
  if (options.userClaudeEnvVars) {
    for (const line of options.userClaudeEnvVars.split('\n')) {
      const trimmed = line.trim()
      if (!trimmed || trimmed.startsWith('#')) continue
      const eqIndex = trimmed.indexOf('=')
      if (eqIndex === -1) continue
      const key = trimmed.slice(0, eqIndex)
      const value = trimmed.slice(eqIndex + 1)
      if (value === '') {
        delete env[key]  // Empty value = unset the key
      } else {
        env[key] = value
      }
    }
  }

  // Layer 6: GitHub token (if configured)
  if (options.ghToken) {
    env['GH_TOKEN'] = options.ghToken
  }

  return env
}

/**
 * Load Auctor's platform .env file into a plain object.
 * Called once at app startup. Does NOT mutate process.env.
 */
export function loadPlatformEnv(envPath: string): Record<string, string> {
  const dotenv = require('dotenv')
  const result = dotenv.config({ path: envPath })
  if (result.error) {
    console.error(`Failed to load platform env from ${envPath}:`, result.error)
    return {}
  }
  return result.parsed ?? {}
}

3.4 `desktop/claude-code-manager.ts`

This is the most complex file. It wraps the @anthropic-ai/claude-code SDK's query() function with Auctor's session management, lifecycle control, and IPC bridge.

// desktop/claude-code-manager.ts

import { query } from '@anthropic-ai/claude-code'
import { EventEmitter } from 'events'
import path from 'path'
import os from 'os'
import crypto from 'crypto'
import { assembleEnvironment } from './env-assembly'
import type {
  Session, SessionConfig, SessionSummary, ClaudeEvent,
  AsyncIterableClaudeResult, AppSettings,
} from './types'

// ─── Constants ─────────────────────────────────────────────────────────

const WORKSPACE_PATH = path.join(os.homedir(), '.auctor', 'workspace')
const IDLE_TIMEOUT_MS = 30 * 60 * 1000  // 30 minutes
const MAX_IDLE_SESSIONS = 5
const SWEEP_INTERVAL_MS = 60 * 1000     // 1 minute

// ─── System Prompt Template ────────────────────────────────────────────

function buildSystemPrompt(config: SessionConfig, settings: AppSettings): string {
  const lines = [
    `You are running inside Auctor Desktop v0.1.0.`,
    `Working directory: ${WORKSPACE_PATH}`,
    `Active site: ${settings.siteKey}`,
    `Session type: ${config.type}${config.type === 'scheduled' ? ':' + (config.appendSystemPrompt ?? '') : ''}`,
    `Timestamp: ${new Date().toISOString()}`,
    ``,
    `Your CLAUDE.md in the workspace defines your full identity and mission.`,
    `Read it if you need to re-orient.`,
  ]

  if (config.appendSystemPrompt) {
    lines.push('', '--- Additional Context ---', config.appendSystemPrompt)
  }

  return lines.join('\n')
}

// ─── Manager Class ─────────────────────────────────────────────────────

export class ClaudeCodeManager extends EventEmitter {
  private sessions = new Map<string, Session>()
  private sweepTimer: ReturnType<typeof setInterval> | null = null
  private settings: AppSettings
  private platformEnv: Record<string, string>
  private claudeExecutablePath: string

  /**
   * @param claudeExecutablePath - Path to the bundled `claude` binary.
   *   In dev: detected from PATH.
   *   In production: bundled in app resources.
   * @param platformEnv - Loaded from .env.local at app startup.
   * @param settings - Current app settings (model, env vars, schedule).
   */
  constructor(
    claudeExecutablePath: string,
    platformEnv: Record<string, string>,
    settings: AppSettings,
  ) {
    super()
    this.claudeExecutablePath = claudeExecutablePath
    this.platformEnv = platformEnv
    this.settings = settings
    this.sweepTimer = setInterval(() => this.sweepIdleSessions(), SWEEP_INTERVAL_MS)
  }

  /** Update settings (called when operator changes config in UI) */
  updateSettings(settings: AppSettings) {
    this.settings = settings
  }

  /** Get summary of all active sessions */
  getSessions(): SessionSummary[] {
    return [...this.sessions.values()].map(s => ({
      id: s.id,
      type: s.type,
      isProcessing: s.isProcessing,
      lastActivityAt: s.lastActivityAt,
    }))
  }

  // ─── Session Lifecycle ──────────────────────────────────────────────

  /**
   * Start a new Claude Code session.
   *
   * For INTERACTIVE sessions:
   *   Creates an async generator that yields user messages on demand.
   *   The generator blocks (awaits a Promise) when no messages are pending.
   *   Call sendMessage() to push messages into the generator.
   *   The SDK keeps the same Claude Code process alive across messages.
   *
   * For SCHEDULED/EVENT sessions:
   *   Creates a single-yield generator with the prompt.
   *   Claude Code processes the prompt, calls tools, writes to workspace, and exits.
   *   No interaction possible after spawn.
   *
   * Returns the session ID (deterministic UUID or auto-generated).
   */
  async startSession(config: SessionConfig): Promise<string> {
    const sessionId = config.sessionId ?? crypto.randomUUID()
    const model = config.model ?? this.settings.model ?? 'claude-sonnet-4-20250514'

    // ── Check for session reuse ─────────────────────────────────────
    // If an interactive session with this ID already exists and settings
    // haven't changed, push the new message into the existing process
    // rather than spawning a new one.
    const existing = this.sessions.get(sessionId)
    if (existing && existing.currentSettings.model === model) {
      if (config.prompt) {
        this.sendMessage(sessionId, config.prompt)
      }
      return sessionId
    }

    // ── Assemble environment ────────────────────────────────────────
    const env = assembleEnvironment({
      userClaudeEnvVars: this.settings.claudeEnvVars,
      platformEnv: this.platformEnv,
    })

    // ── Build prompt input (async generator) ────────────────────────
    const messageQueue: string[] = []
    let resolveNextMessage: ((msg: string) => void) | null = null

    let promptInput: AsyncGenerator<any>

    if (config.type === 'interactive') {
      // Multi-turn: generator blocks waiting for messages
      promptInput = (async function* () {
        // If there's an initial prompt, yield it first
        if (config.prompt) {
          yield {
            type: 'user' as const,
            message: { role: 'user' as const, content: config.prompt },
          }
        }

        // Then enter the message loop
        while (true) {
          const message = messageQueue.length > 0
            ? messageQueue.shift()!
            : await new Promise<string>(resolve => {
                resolveNextMessage = resolve
              })
          resolveNextMessage = null
          yield {
            type: 'user' as const,
            message: { role: 'user' as const, content: message },
          }
        }
      })()
    } else {
      // Headless: single prompt, then generator returns
      promptInput = (async function* () {
        yield {
          type: 'user' as const,
          message: { role: 'user' as const, content: config.prompt! },
        }
      })()
    }

    // ── Build SDK options ───────────────────────────────────────────
    const sdkOptions = {
      maxTurns: config.maxTurns ?? (config.type === 'interactive' ? 1000 : 100),
      model,
      cwd: WORKSPACE_PATH,
      pathToClaudeCodeExecutable: this.claudeExecutablePath,
      systemPrompt: buildSystemPrompt(config, this.settings),
      settingSources: ['user', 'project', 'local'] as const,
      env,

      // ── Runtime tool approval ───────────────────────────────────
      // This callback fires BEFORE every tool execution inside the
      // Claude Code process. It's the primary permission gate.
      canUseTool: async (
        toolName: string,
        toolInput: Record<string, unknown>,
      ) => {
        return this.handleToolApproval(sessionId, toolName, toolInput)
      },

      // ── Blocked tools ───────────────────────────────────────────
      // AskUserQuestion: Auctor provides its own UI for user interaction.
      // Claude Code's terminal-based question prompts would hang in headless mode.
      disallowedTools: ['AskUserQuestion'],

      permissionMode: 'default' as const,

      // ── MCP servers ─────────────────────────────────────────────
      // The auctor MCP server is defined inline. In Electron, it runs
      // in-process (via mcp-bridge.ts). The SDK connects to it via
      // the configuration provided here.
      mcpServers: this.getMcpServerConfig(),

      // ── Hooks ───────────────────────────────────────────────────
      hooks: {
        UserPromptSubmit: [
          {
            type: 'command' as const,
            command: `cd ${WORKSPACE_PATH} && git add -A && git stash create "checkpoint-$(date +%s)" || true`,
          },
        ],
        Stop: [
          {
            type: 'command' as const,
            command: `cd ${WORKSPACE_PATH} && git add -A && git stash create "checkpoint-$(date +%s)" || true`,
          },
          {
            type: 'command' as const,
            command: `cd ${WORKSPACE_PATH} && git add -A && git commit -m "session: auto-commit on stop" --allow-empty || true`,
          },
        ],
        PostToolUse: [
          {
            type: 'command' as const,
            command: `echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) $TOOL_NAME" >> ${path.join(os.homedir(), '.auctor', 'logs', 'tool-audit.log')}`,
          },
        ],
      },
    }

    // ── Execute query ───────────────────────────────────────────────
    const queryResult = query({
      prompt: promptInput,
      options: sdkOptions,
    }) as AsyncIterableClaudeResult

    // ── Register session ────────────────────────────────────────────
    const session: Session = {
      id: sessionId,
      type: config.type,
      queryResult,
      messageQueue,
      resolveNextMessage: null,
      isProcessing: true,
      lastActivityAt: Date.now(),
      currentSettings: { model },
    }

    // The resolveNextMessage pointer is managed by the async generator
    // closure. We need to keep a live reference on the session object
    // so sendMessage() can resolve it.
    Object.defineProperty(session, 'resolveNextMessage', {
      get: () => resolveNextMessage,
      set: (v: ((msg: string) => void) | null) => { resolveNextMessage = v },
      enumerable: true,
      configurable: true,
    })

    this.sessions.set(sessionId, session)

    // ── Consume events in background ────────────────────────────────
    this.consumeEvents(sessionId, queryResult)

    return sessionId
  }

  /**
   * Send a message to an active interactive session.
   *
   * If the async generator is currently awaiting (resolveNextMessage is set),
   * the message is delivered immediately by resolving the Promise.
   * Otherwise, it's queued — the generator will pick it up on next yield.
   *
   * This is how multi-turn conversation works without spawning a new process.
   */
  sendMessage(sessionId: string, message: string): void {
    const session = this.sessions.get(sessionId)
    if (!session) {
      throw new Error(`No active session: ${sessionId}`)
    }

    if (session.resolveNextMessage) {
      // Generator is awaiting — deliver immediately
      session.resolveNextMessage(message)
    } else {
      // Generator is busy processing — queue for next iteration
      session.messageQueue.push(message)
    }

    session.lastActivityAt = Date.now()
    session.isProcessing = true
  }

  /**
   * Gracefully stop a session.
   * The SDK's interrupt() sends SIGTERM with a 5-second grace period,
   * then SIGKILL if the process hasn't exited.
   */
  stopSession(sessionId: string): void {
    const session = this.sessions.get(sessionId)
    if (session) {
      session.queryResult.interrupt()
      // consumeEvents() will handle cleanup when the iterator completes
    }
  }

  /**
   * Stop all sessions. Called on app quit.
   */
  stopAll(): void {
    for (const [id] of this.sessions) {
      this.stopSession(id)
    }
    if (this.sweepTimer) {
      clearInterval(this.sweepTimer)
    }
  }

  // ─── Event Consumption ──────────────────────────────────────────────

  /**
   * Consume the async iterable of events from a query result.
   *
   * This runs as a background async loop for the lifetime of the session.
   * Each event is forwarded to the Electron renderer via EventEmitter.
   * When the iterable completes (session ends), cleanup is performed.
   */
  private async consumeEvents(
    sessionId: string,
    queryResult: AsyncIterable<ClaudeEvent>,
  ): Promise<void> {
    try {
      for await (const event of queryResult) {
        const session = this.sessions.get(sessionId)
        if (session) {
          session.lastActivityAt = Date.now()
        }

        // Forward to renderer
        this.emit('session-event', { sessionId, event })

        // Track processing state
        if (event.type === 'result') {
          const session = this.sessions.get(sessionId)
          if (session) {
            session.isProcessing = false
          }
        }
      }
    } catch (err: unknown) {
      const message = err instanceof Error ? err.message : String(err)
      this.emit('session-error', { sessionId, error: message })
    } finally {
      this.sessions.delete(sessionId)
      this.emit('session-ended', { sessionId })
    }
  }

  // ─── Tool Approval ──────────────────────────────────────────────────

  /**
   * Handle runtime tool approval.
   *
   * This is the canUseTool callback passed to the SDK. It fires synchronously
   * from Claude Code's perspective — the process blocks until this resolves.
   *
   * For most tools: auto-approve (fast path).
   * For publish tools: emit an event to the renderer, await operator decision.
   * For file writes: validate path is within workspace.
   */
  private async handleToolApproval(
    sessionId: string,
    toolName: string,
    toolInput: Record<string, unknown>,
  ): Promise<{ allowed: boolean; reason?: string }> {

    // ── Publish gate ────────────────────────────────────────────────
    // upload-to-cms is the most dangerous operation. It pushes content
    // to the live CMS. Require explicit operator approval every time.
    if (toolName === 'mcp__auctor__upload-to-cms') {
      return this.requestOperatorApproval(sessionId, toolName, toolInput)
    }

    // ── File path validation ────────────────────────────────────────
    // Prevent Claude Code from writing outside the workspace.
    // This catches path traversal (../../etc/passwd) and absolute paths.
    if (['Edit', 'Write', 'MultiEdit'].includes(toolName)) {
      const filePath = toolInput.file_path as string
      if (filePath) {
        const resolved = path.resolve(WORKSPACE_PATH, filePath)
        if (!resolved.startsWith(WORKSPACE_PATH)) {
          return {
            allowed: false,
            reason: `Path '${filePath}' resolves outside workspace`,
          }
        }
      }
    }

    // ── All other tools: auto-approve ───────────────────────────────
    return { allowed: true }
  }

  /**
   * Request operator approval for a dangerous tool call.
   *
   * Emits an event to the renderer, which shows an approval card in the
   * chat panel. Returns a Promise that resolves when the operator clicks
   * Approve or Reject.
   *
   * IMPORTANT: This blocks the Claude Code process. The SDK will not
   * proceed with the tool call until this Promise resolves. Keep the
   * timeout reasonable (5 minutes) — if the operator doesn't respond,
   * auto-reject.
   */
  private requestOperatorApproval(
    sessionId: string,
    toolName: string,
    toolInput: Record<string, unknown>,
  ): Promise<{ allowed: boolean; reason?: string }> {
    const approvalId = crypto.randomUUID()

    return new Promise((resolve) => {
      // Emit approval request to renderer
      this.emit('approval-requested', {
        approvalId,
        sessionId,
        toolName,
        toolInput,
      })

      // Listen for operator decision
      const handler = (decision: {
        approvalId: string
        approved: boolean
        reason?: string
      }) => {
        if (decision.approvalId === approvalId) {
          this.removeListener('approval-decision', handler)
          clearTimeout(timeout)
          resolve({
            allowed: decision.approved,
            reason: decision.reason ?? (decision.approved ? undefined : 'Rejected by operator'),
          })
        }
      }
      this.on('approval-decision', handler)

      // Auto-reject after 5 minutes of no response
      const timeout = setTimeout(() => {
        this.removeListener('approval-decision', handler)
        resolve({ allowed: false, reason: 'Approval timed out (5 minutes)' })
      }, 5 * 60 * 1000)
    })
  }

  // ─── Idle Session Management ────────────────────────────────────────

  /**
   * Sweep idle sessions.
   * Runs every 60 seconds via setInterval.
   *
   * 1. Kill sessions that have been idle > 30 minutes
   * 2. If more than 5 idle sessions remain, kill oldest first
   */
  private sweepIdleSessions(): void {
    const now = Date.now()

    // Find idle sessions (not processing, past timeout)
    const idle = [...this.sessions.entries()]
      .filter(([, s]) => !s.isProcessing && (now - s.lastActivityAt) > IDLE_TIMEOUT_MS)
      .sort((a, b) => a[1].lastActivityAt - b[1].lastActivityAt)

    for (const [id] of idle) {
      this.stopSession(id)
    }

    // Enforce max idle count
    const remainingIdle = [...this.sessions.entries()]
      .filter(([, s]) => !s.isProcessing)
      .sort((a, b) => a[1].lastActivityAt - b[1].lastActivityAt)

    while (remainingIdle.length > MAX_IDLE_SESSIONS) {
      const [id] = remainingIdle.shift()!
      this.stopSession(id)
    }
  }

  // ─── MCP Server Config ──────────────────────────────────────────────

  /**
   * Build the MCP server configuration passed to the SDK.
   *
   * In Electron, the auctor MCP server runs in-process via mcp-bridge.ts.
   * The SDK connects to it via stdio transport.
   *
   * In dev mode (no Electron), this points to the same .mcp.json that
   * Claude Code reads from the workspace.
   */
  private getMcpServerConfig(): Record<string, unknown> {
    // The MCP server is started in-process by mcp-bridge.ts.
    // Here we configure the SDK to connect to it via stdio.
    return {
      auctor: {
        type: 'stdio',
        command: 'npx',
        args: [
          'tsx',
          '--import', './mcp-server/register.mjs',
          './mcp-server/index.ts',
        ],
        cwd: path.resolve(__dirname, '..', 'frontend'),
        env: {
          DOTENV_CONFIG_PATH: path.resolve(__dirname, '..', '.env.local'),
        },
      },
    }
  }

  // ─── Helper: Platform Env ───────────────────────────────────────────

  /** Exposed for env-assembly to access platform env */
  getPlatformEnv(): Record<string, string> {
    return { ...this.platformEnv }
  }
}

Implementation notes for the builder:

The Object.defineProperty trick for resolveNextMessage is necessary because the async generator closure captures resolveNextMessage by reference in its own scope. The getter/setter on the session object bridges the gap — when sendMessage() reads session.resolveNextMessage, it actually reads the variable from the generator's closure. Without this, the session object and the generator would have independent copies of the variable.
The canUseTool callback is async but blocks Claude Code — the SDK awaits its resolution before allowing the tool to execute. This is by design and documented in the SDK. Do not add artificial delays.
Hook commands use || true at the end because git operations (stash, commit) will fail if there are no changes. Without || true, the hook failure would propagate to Claude Code as an error event.
The MCP server config in getMcpServerConfig() launches the MCP server as a stdio child of Claude Code. In the Electron production build, the path resolution (__dirname) will point to the dist/ directory. The cwd must resolve to the frontend/ directory where the MCP server code lives. If the frontend is bundled as extraResources, adjust the path accordingly. During development, __dirname resolves correctly because tsc outputs to desktop/dist/ and the frontend is at ../frontend/.

3.5 `desktop/mcp-bridge.ts`

Initializes the MCP server in-process so it shares Electron's Node.js runtime and database pool.

// desktop/mcp-bridge.ts

import path from 'path'

/**
 * Initialize the Auctor MCP server in the Electron main process.
 *
 * This is the "shared runtime" advantage of Electron: the MCP server's
 * Drizzle ORM, Mastra runtime, and database pool live in the same
 * Node.js process as the main thread. No sidecar, no IPC, no second
 * connection pool.
 *
 * IMPORTANT: This must be called BEFORE ClaudeCodeManager.startSession()
 * so the MCP server is ready when Claude Code connects to it.
 *
 * The MCP server is registered as a stdio transport in Claude Code's
 * config. When Claude Code calls mcp__auctor__*, the request goes
 * through stdin/stdout pipes to THIS process.
 *
 * In practice for Phase 4 initial build:
 *   The MCP server still runs as a spawned process (via the .mcp.json
 *   config). The in-process optimization is a Phase 5 enhancement.
 *   This module exists as a placeholder and initialization checkpoint.
 */

interface McpBridgeOptions {
  /** Path to .env.local for the MCP server */
  envPath: string
  /** Path to the frontend directory (where mcp-server/ lives) */
  frontendPath: string
}

export async function initMcpBridge(options: McpBridgeOptions): Promise<void> {
  // Phase 4: Verify the MCP server can start
  // The MCP server runs as a stdio child of Claude Code (spawned by the SDK).
  // Here we validate that the required files and env exist.

  const fs = await import('fs')

  const serverEntry = path.join(options.frontendPath, 'mcp-server', 'index.ts')
  if (!fs.existsSync(serverEntry)) {
    throw new Error(
      `MCP server entry not found: ${serverEntry}\n` +
      `Ensure Phase 1 is complete: the MCP server must exist at frontend/mcp-server/index.ts`
    )
  }

  if (!fs.existsSync(options.envPath)) {
    throw new Error(
      `Environment file not found: ${options.envPath}\n` +
      `Auctor requires a .env.local with DATABASE_URL, Supabase keys, and API credentials.`
    )
  }

  console.log('[mcp-bridge] MCP server validated:', serverEntry)
  console.log('[mcp-bridge] Environment file:', options.envPath)

  // Phase 5 enhancement: import the MCP server directly and run it in-process
  // using the McpServer's request() method instead of stdio transport.
  // This eliminates the child process and shares the DB pool.
}

3.6 `desktop/scheduler.ts`

// desktop/scheduler.ts

import cron from 'node-cron'
import fs from 'fs'
import path from 'path'
import os from 'os'
import type { ClaudeCodeManager } from './claude-code-manager'
import type { AppSettings, ClaudeEvent } from './types'

const LOGS_DIR = path.join(os.homedir(), '.auctor', 'logs')

// ─── Schedule Prompts ──────────────────────────────────────────────────
// Each prompt is a complete instruction for a headless Claude Code session.
// The agent reads its workspace CLAUDE.md (auto-loaded), then follows
// these cycle-specific instructions.

const PROMPTS = {
  morning: [
    'Run your morning cycle.',
    '1. Read memory/current-focus.md for today\'s priorities.',
    '2. Check intelligence/*/_last-sync.txt timestamps.',
    '3. If any data is older than 24 hours, sync it using the appropriate MCP tools.',
    '4. Review intelligence/analytics/content-performance.json for overnight changes.',
    '5. Check content/drafts/_queue.json for items needing attention.',
    '6. Write your observations to memory/observations.md.',
    '7. Update memory/current-focus.md with today\'s plan.',
    '8. Commit all changes.',
  ].join('\n'),

  midday: [
    'Quick midday check.',
    '1. Read memory/current-focus.md — are you on track?',
    '2. Check content/drafts/_queue.json — any drafts needing review?',
    '3. Look for performance anomalies in intelligence/analytics/.',
    '4. If anything urgent, append to memory/observations.md.',
    '5. Commit any changes.',
  ].join('\n'),

  evening: [
    'End of day review.',
    '1. Summarize what was accomplished today in memory/observations.md.',
    '2. Log any decisions made to memory/decisions.md with reasoning.',
    '3. If you learned something generalizable, add it to memory/learnings.md.',
    '4. Update memory/current-focus.md with tomorrow\'s priorities.',
    '5. Commit all changes with a summary message.',
  ].join('\n'),

  weekly: [
    'Weekly deep analysis.',
    '1. Sync ALL data sources (analytics, search, competitors, content).',
    '2. Compare this week\'s intelligence/analytics/ with last week\'s.',
    '3. Review memory/learnings.md — are the patterns still holding?',
    '4. Review memory/mistakes.md — are we repeating errors?',
    '5. Analyze content/published/ performance trends.',
    '6. Check intelligence/competitors/ for new competitive moves.',
    '7. Update the editorial calendar based on what\'s working.',
    '8. Write a weekly summary in memory/observations.md.',
    '9. Distill any new insights to memory/learnings.md.',
    '10. Commit all changes.',
  ].join('\n'),
}

// ─── Scheduler ─────────────────────────────────────────────────────────

export function initScheduler(
  manager: ClaudeCodeManager,
  settings: AppSettings,
): { updateSchedule: (settings: AppSettings) => void; stop: () => void } {
  const tasks: cron.ScheduledTask[] = []

  function clearTasks() {
    for (const task of tasks) {
      task.stop()
    }
    tasks.length = 0
  }

  function buildSchedule(settings: AppSettings) {
    clearTasks()

    // Ensure logs directory exists
    if (!fs.existsSync(LOGS_DIR)) {
      fs.mkdirSync(LOGS_DIR, { recursive: true })
    }

    const { schedule } = settings

    if (schedule.morningEnabled) {
      const [h, m] = schedule.morningTime.split(':')
      tasks.push(cron.schedule(`${m} ${h} * * *`, () => {
        runScheduledSession(manager, PROMPTS.morning, 'morning')
      }))
    }

    if (schedule.middayEnabled) {
      const [h, m] = schedule.middayTime.split(':')
      tasks.push(cron.schedule(`${m} ${h} * * *`, () => {
        runScheduledSession(manager, PROMPTS.midday, 'midday')
      }))
    }

    if (schedule.eveningEnabled) {
      const [h, m] = schedule.eveningTime.split(':')
      tasks.push(cron.schedule(`${m} ${h} * * *`, () => {
        runScheduledSession(manager, PROMPTS.evening, 'evening')
      }))
    }

    if (schedule.weeklyEnabled) {
      const [h, m] = schedule.weeklyTime.split(':')
      tasks.push(cron.schedule(`${m} ${h} * * ${schedule.weeklyDay}`, () => {
        runScheduledSession(manager, PROMPTS.weekly, 'weekly')
      }))
    }

    console.log(`[scheduler] ${tasks.length} scheduled tasks configured`)
  }

  // Initial build
  buildSchedule(settings)

  return {
    updateSchedule: (newSettings: AppSettings) => buildSchedule(newSettings),
    stop: () => clearTasks(),
  }
}

// ─── Session Runner ────────────────────────────────────────────────────

async function runScheduledSession(
  manager: ClaudeCodeManager,
  prompt: string,
  logSuffix: string,
): Promise<void> {
  const date = new Date().toISOString().split('T')[0]
  const logFile = path.join(LOGS_DIR, `${date}-${logSuffix}.json`)
  const events: string[] = []

  console.log(`[scheduler] Starting ${logSuffix} session`)

  try {
    const sessionId = await manager.startSession({
      type: 'scheduled',
      prompt,
      appendSystemPrompt: `scheduled:${logSuffix}`,
      maxTurns: 100,
    })

    // Collect events for log file
    const onEvent = ({ sessionId: sid, event }: { sessionId: string; event: ClaudeEvent }) => {
      if (sid === sessionId) {
        events.push(JSON.stringify({
          timestamp: new Date().toISOString(),
          ...event,
        }))
      }
    }

    const onEnded = ({ sessionId: sid }: { sessionId: string }) => {
      if (sid === sessionId) {
        manager.removeListener('session-event', onEvent)
        manager.removeListener('session-ended', onEnded)

        // Write log file
        try {
          fs.writeFileSync(logFile, events.join('\n'))
          console.log(`[scheduler] ${logSuffix} session complete. Log: ${logFile}`)
        } catch (err) {
          console.error(`[scheduler] Failed to write log: ${err}`)
        }
      }
    }

    manager.on('session-event', onEvent)
    manager.on('session-ended', onEnded)
  } catch (err) {
    console.error(`[scheduler] Failed to start ${logSuffix} session:`, err)
  }
}

3.7 `desktop/file-watcher.ts`

// desktop/file-watcher.ts

import chokidar from 'chokidar'
import path from 'path'
import os from 'os'
import type { BrowserWindow } from 'electron'

const WORKSPACE_PATH = path.join(os.homedir(), '.auctor', 'workspace')

/**
 * Watch the Auctor workspace for file changes.
 *
 * When Claude Code writes to memory/observations.md, edits a draft,
 * or updates intelligence data, the file watcher detects the change
 * and notifies the renderer. Dashboard components can then refetch
 * to show the latest state.
 *
 * Debouncing: chokidar fires on write close, not on every byte.
 * For large files (analytics JSON), this means one event per write,
 * not thousands. No additional debouncing needed.
 */
export function initFileWatcher(mainWindow: BrowserWindow): {
  close: () => Promise<void>
} {
  const watcher = chokidar.watch(WORKSPACE_PATH, {
    ignored: [
      /(^|[\/\\])\../,       // dotfiles (.git, .claude, etc.)
      /node_modules/,
      /\.git\//,
    ],
    persistent: true,
    ignoreInitial: true,      // Don't fire for existing files on startup
    awaitWriteFinish: {       // Wait for writes to complete
      stabilityThreshold: 300,
      pollInterval: 100,
    },
  })

  watcher.on('change', (filePath: string) => {
    if (mainWindow.isDestroyed()) return

    const relative = path.relative(WORKSPACE_PATH, filePath)
    mainWindow.webContents.send('workspace:file-changed', {
      path: filePath,
      relative,
      timestamp: Date.now(),
    })
  })

  watcher.on('add', (filePath: string) => {
    if (mainWindow.isDestroyed()) return

    const relative = path.relative(WORKSPACE_PATH, filePath)
    mainWindow.webContents.send('workspace:file-changed', {
      path: filePath,
      relative,
      timestamp: Date.now(),
    })
  })

  watcher.on('error', (error: Error) => {
    console.error('[file-watcher] Error:', error)
  })

  console.log(`[file-watcher] Watching: ${WORKSPACE_PATH}`)

  return {
    close: () => watcher.close(),
  }
}

3.8 `desktop/sidecar.ts`

// desktop/sidecar.ts

import { spawn, ChildProcess } from 'child_process'
import path from 'path'

/**
 * Manage the Python/FastAPI sidecar for LangExtract.
 *
 * LangExtract provides content extraction capabilities (HTML → structured data)
 * that the Mastra agents use during content analysis workflows.
 *
 * Lifecycle: starts with the app, stops on app quit.
 * Health check: GET http://localhost:8000/health every 30 seconds.
 * Restart: auto-restart on crash, max 3 retries then give up.
 */
export class SidecarManager {
  private process: ChildProcess | null = null
  private restartCount = 0
  private maxRestarts = 3
  private healthCheckTimer: ReturnType<typeof setInterval> | null = null
  private pythonPath: string
  private scriptPath: string

  constructor(options: {
    /** Path to python3 or the bundled Python executable */
    pythonPath: string
    /** Path to the FastAPI entry script (backend/main.py) */
    scriptPath: string
  }) {
    this.pythonPath = options.pythonPath
    this.scriptPath = options.scriptPath
  }

  start(): void {
    if (this.process) return

    console.log(`[sidecar] Starting FastAPI: ${this.pythonPath} ${this.scriptPath}`)

    this.process = spawn(this.pythonPath, [this.scriptPath], {
      stdio: ['ignore', 'pipe', 'pipe'],
      env: {
        ...process.env,
        PORT: '8000',
        HOST: '127.0.0.1',
      },
    })

    this.process.stdout?.on('data', (data: Buffer) => {
      console.log(`[sidecar:stdout] ${data.toString().trim()}`)
    })

    this.process.stderr?.on('data', (data: Buffer) => {
      console.error(`[sidecar:stderr] ${data.toString().trim()}`)
    })

    this.process.on('exit', (code, signal) => {
      console.log(`[sidecar] Exited with code ${code}, signal ${signal}`)
      this.process = null

      if (this.restartCount < this.maxRestarts) {
        this.restartCount++
        console.log(`[sidecar] Restarting (attempt ${this.restartCount}/${this.maxRestarts})`)
        setTimeout(() => this.start(), 2000)
      } else {
        console.error('[sidecar] Max restarts exceeded. LangExtract is down.')
      }
    })

    // Health check every 30 seconds
    this.healthCheckTimer = setInterval(async () => {
      try {
        const response = await fetch('http://127.0.0.1:8000/health')
        if (!response.ok) throw new Error(`Status ${response.status}`)
      } catch {
        console.warn('[sidecar] Health check failed')
      }
    }, 30_000)
  }

  stop(): void {
    if (this.healthCheckTimer) {
      clearInterval(this.healthCheckTimer)
      this.healthCheckTimer = null
    }
    if (this.process) {
      this.process.kill('SIGTERM')
      // Force kill after 5 seconds
      setTimeout(() => {
        if (this.process) {
          this.process.kill('SIGKILL')
          this.process = null
        }
      }, 5000)
    }
  }
}

3.9 `desktop/preload.ts`

// desktop/preload.ts

import { contextBridge, ipcRenderer } from 'electron'

/**
 * Electron preload script.
 *
 * Exposes a safe, typed API on window.electron that the renderer
 * (Next.js React components) can use to communicate with the main process.
 *
 * Security: contextBridge ensures the renderer cannot access Node.js
 * directly. All communication goes through these explicitly defined channels.
 */
contextBridge.exposeInMainWorld('electron', {
  // ── Request/Response (invoke → handle) ─────────────────────────────

  invoke: (channel: string, args?: unknown) => {
    const validChannels = [
      'claude:start-session',
      'claude:send-message',
      'claude:stop-session',
      'claude:get-sessions',
      'claude:verify-auth',
      'claude:approve-tool',
      'workspace:read-file',
      'workspace:list-dir',
      'settings:get',
      'settings:set',
    ]
    if (validChannels.includes(channel)) {
      return ipcRenderer.invoke(channel, args)
    }
    throw new Error(`Invalid IPC channel: ${channel}`)
  },

  // ── Event Stream (send → on) ───────────────────────────────────────

  on: (channel: string, callback: (...args: unknown[]) => void) => {
    const validChannels = [
      'claude:event',
      'claude:session-ended',
      'claude:session-error',
      'claude:approval-requested',
      'workspace:file-changed',
    ]
    if (validChannels.includes(channel)) {
      // Wrap to strip the IpcRendererEvent — renderer doesn't need it
      const wrappedCallback = (_event: Electron.IpcRendererEvent, ...args: unknown[]) => {
        callback(...args)
      }
      ipcRenderer.on(channel, wrappedCallback)

      // Return cleanup function
      return () => {
        ipcRenderer.removeListener(channel, wrappedCallback)
      }
    }
    throw new Error(`Invalid IPC channel: ${channel}`)
  },

  // ── One-time Event ─────────────────────────────────────────────────

  once: (channel: string, callback: (...args: unknown[]) => void) => {
    const validChannels = [
      'claude:session-ended',
    ]
    if (validChannels.includes(channel)) {
      ipcRenderer.once(channel, (_event, ...args) => callback(...args))
    }
  },
})

// TypeScript declaration for the renderer
declare global {
  interface Window {
    electron: {
      invoke: (channel: string, args?: unknown) => Promise<unknown>
      on: (channel: string, callback: (...args: unknown[]) => void) => () => void
      once: (channel: string, callback: (...args: unknown[]) => void) => void
    }
  }
}

3.10 `desktop/ipc-handlers.ts`

All IPC handler registrations in one file. Imported by main.ts.

// desktop/ipc-handlers.ts

import { ipcMain, BrowserWindow } from 'electron'
import fs from 'fs/promises'
import path from 'path'
import os from 'os'
import type { ClaudeCodeManager } from './claude-code-manager'
import type { AppSettings } from './types'

const WORKSPACE_PATH = path.join(os.homedir(), '.auctor', 'workspace')
const SETTINGS_PATH = path.join(os.homedir(), '.auctor', 'state', 'settings.json')

/**
 * Register all IPC handlers.
 *
 * This bridges the renderer (React) ↔ main process (Claude Code Manager).
 * Each handler maps to a window.electron.invoke() call in the renderer.
 */
export function registerIpcHandlers(
  mainWindow: BrowserWindow,
  manager: ClaudeCodeManager,
  onSettingsChanged: (settings: AppSettings) => void,
): void {

  // ── Claude Code Session Management ─────────────────────────────────

  ipcMain.handle('claude:start-session', async (_event, config) => {
    return manager.startSession(config)
  })

  ipcMain.handle('claude:send-message', async (_event, { sessionId, message }) => {
    manager.sendMessage(sessionId, message)
  })

  ipcMain.handle('claude:stop-session', async (_event, { sessionId }) => {
    manager.stopSession(sessionId)
  })

  ipcMain.handle('claude:get-sessions', async () => {
    return manager.getSessions()
  })

  // ── Tool Approval ──────────────────────────────────────────────────
  // When canUseTool() in the manager emits an approval request,
  // we forward it to the renderer. When the operator clicks Approve/Reject,
  // the renderer calls this handler, which resolves the canUseTool() Promise.

  ipcMain.handle('claude:approve-tool', async (_event, decision) => {
    manager.emit('approval-decision', decision)
  })

  // Forward approval requests from manager → renderer
  manager.on('approval-requested', (payload) => {
    if (!mainWindow.isDestroyed()) {
      mainWindow.webContents.send('claude:approval-requested', payload)
    }
  })

  // Forward Claude Code events from manager → renderer
  manager.on('session-event', (payload) => {
    if (!mainWindow.isDestroyed()) {
      mainWindow.webContents.send('claude:event', payload)
    }
  })

  manager.on('session-ended', (payload) => {
    if (!mainWindow.isDestroyed()) {
      mainWindow.webContents.send('claude:session-ended', payload)
    }
  })

  manager.on('session-error', (payload) => {
    if (!mainWindow.isDestroyed()) {
      mainWindow.webContents.send('claude:session-error', payload)
    }
  })

  // ── Auth Verification ──────────────────────────────────────────────

  ipcMain.handle('claude:verify-auth', async () => {
    try {
      // Spawn a throwaway Claude Code process just to check credentials
      const sessionId = await manager.startSession({
        type: 'scheduled',
        prompt: 'Echo "auth-check-ok"',
        maxTurns: 1,
      })

      // Wait for it to complete (or timeout)
      return new Promise((resolve) => {
        const timeout = setTimeout(() => {
          manager.stopSession(sessionId)
          resolve({ authenticated: false, error: 'Auth check timed out' })
        }, 15_000)

        const onEnd = ({ sessionId: sid }: { sessionId: string }) => {
          if (sid === sessionId) {
            clearTimeout(timeout)
            manager.removeListener('session-ended', onEnd)
            resolve({ authenticated: true })
          }
        }
        manager.on('session-ended', onEnd)

        const onError = ({ sessionId: sid, error }: { sessionId: string; error: string }) => {
          if (sid === sessionId) {
            clearTimeout(timeout)
            manager.removeListener('session-error', onError)
            resolve({ authenticated: false, error })
          }
        }
        manager.on('session-error', onError)
      })
    } catch (err: unknown) {
      return { authenticated: false, error: err instanceof Error ? err.message : String(err) }
    }
  })

  // ── Workspace File Access ──────────────────────────────────────────

  ipcMain.handle('workspace:read-file', async (_event, { relativePath }) => {
    const fullPath = path.join(WORKSPACE_PATH, relativePath)
    // Security: prevent path traversal
    if (!fullPath.startsWith(WORKSPACE_PATH)) {
      throw new Error('Path traversal detected')
    }
    return fs.readFile(fullPath, 'utf-8')
  })

  ipcMain.handle('workspace:list-dir', async (_event, { relativePath }) => {
    const fullPath = path.join(WORKSPACE_PATH, relativePath)
    if (!fullPath.startsWith(WORKSPACE_PATH)) {
      throw new Error('Path traversal detected')
    }
    const entries = await fs.readdir(fullPath, { withFileTypes: true })
    return entries.map(e => ({
      name: e.name,
      isDirectory: e.isDirectory(),
    }))
  })

  // ── App Settings ───────────────────────────────────────────────────

  ipcMain.handle('settings:get', async () => {
    try {
      const raw = await fs.readFile(SETTINGS_PATH, 'utf-8')
      return JSON.parse(raw)
    } catch {
      return getDefaultSettings()
    }
  })

  ipcMain.handle('settings:set', async (_event, partialSettings) => {
    let current: AppSettings
    try {
      const raw = await fs.readFile(SETTINGS_PATH, 'utf-8')
      current = JSON.parse(raw)
    } catch {
      current = getDefaultSettings()
    }

    const updated = { ...current, ...partialSettings }
    await fs.mkdir(path.dirname(SETTINGS_PATH), { recursive: true })
    await fs.writeFile(SETTINGS_PATH, JSON.stringify(updated, null, 2))

    // Notify manager and scheduler of settings change
    manager.updateSettings(updated)
    onSettingsChanged(updated)
  })
}

function getDefaultSettings(): AppSettings {
  return {
    claudeEnvVars: '',
    model: 'claude-sonnet-4-20250514',
    schedule: {
      morningEnabled: true,
      morningTime: '07:00',
      middayEnabled: true,
      middayTime: '12:00',
      eveningEnabled: true,
      eveningTime: '18:00',
      weeklyEnabled: true,
      weeklyDay: 1,
      weeklyTime: '08:00',
    },
    siteKey: 'consul',
  }
}

3.11 `desktop/auth-verifier.ts`

// desktop/auth-verifier.ts

import { query } from '@anthropic-ai/claude-code'
import os from 'os'
import path from 'path'
import { assembleEnvironment } from './env-assembly'

/**
 * Pre-session verification probes.
 *
 * Before the first interactive session, Auctor runs two lightweight
 * "probe" queries to verify:
 *   1. API credentials are valid
 *   2. MCP servers are accessible
 *   3. Workspace exists and is readable
 *
 * These are ephemeral processes — spawned, queried for metadata, killed.
 * No actual prompts are sent to the LLM.
 */
export async function verifyAuth(options: {
  claudeExecutablePath: string
  platformEnv: Record<string, string>
  userClaudeEnvVars?: string
}): Promise<{
  authenticated: boolean
  email?: string
  plan?: string
  mcpServers?: { name: string; status: string }[]
  error?: string
}> {
  const env = assembleEnvironment({
    userClaudeEnvVars: options.userClaudeEnvVars,
    platformEnv: options.platformEnv,
  })

  const workspacePath = path.join(os.homedir(), '.auctor', 'workspace')

  try {
    // Empty generator — no prompts
    const emptyPrompt = (async function* () {
      // yield nothing — we only want metadata
    })()

    const probeResult = query({
      prompt: emptyPrompt,
      options: {
        maxTurns: 0,
        model: 'claude-sonnet-4-20250514',
        cwd: workspacePath,
        pathToClaudeCodeExecutable: options.claudeExecutablePath,
        systemPrompt: 'Auth verification probe. No action needed.',
        env,
        permissionMode: 'default',
      },
    }) as any  // SDK types may not expose all methods

    // Query for account info
    const accountInfo = await Promise.race([
      probeResult.accountInfo(),
      new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 10_000)),
    ]) as { email: string; plan: string }

    // Query for MCP server status
    let mcpServers: { name: string; status: string }[] = []
    try {
      mcpServers = await Promise.race([
        probeResult.mcpServerStatus(),
        new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 10_000)),
      ]) as any[]
    } catch {
      // MCP status is nice-to-have, not critical
    }

    // Kill the probe process
    probeResult.interrupt()

    return {
      authenticated: true,
      email: accountInfo.email,
      plan: accountInfo.plan,
      mcpServers,
    }
  } catch (err: unknown) {
    return {
      authenticated: false,
      error: err instanceof Error ? err.message : String(err),
    }
  }
}

3.12 `desktop/main.ts`

The main process — Electron's entry point. Orchestrates all subsystems in order.

// desktop/main.ts
// Electron main process entry point

import { app, BrowserWindow, shell } from 'electron'
import path from 'path'
import os from 'os'
import fs from 'fs'
import { loadPlatformEnv } from './env-assembly'
import { ClaudeCodeManager } from './claude-code-manager'
import { initMcpBridge } from './mcp-bridge'
import { initScheduler } from './scheduler'
import { initFileWatcher } from './file-watcher'
import { SidecarManager } from './sidecar'
import { registerIpcHandlers } from './ipc-handlers'
import type { AppSettings } from './types'

// ─── Paths ─────────────────────────────────────────────────────────────

const IS_DEV = process.env.NODE_ENV === 'development'

const WORKSPACE_PATH = path.join(os.homedir(), '.auctor', 'workspace')
const LOGS_PATH = path.join(os.homedir(), '.auctor', 'logs')
const STATE_PATH = path.join(os.homedir(), '.auctor', 'state')

// In production, resources are at process.resourcesPath
// In dev, they're relative to the project root
const RESOURCES = IS_DEV
  ? path.resolve(__dirname, '..')
  : process.resourcesPath!

const FRONTEND_PATH = IS_DEV
  ? path.resolve(__dirname, '..', 'frontend')
  : path.join(RESOURCES, 'next-server')

const ENV_PATH = IS_DEV
  ? path.resolve(__dirname, '..', '.env.local')
  : path.join(RESOURCES, '.env.local')

// Claude Code executable: use system PATH in dev, bundled in production
const CLAUDE_EXECUTABLE = IS_DEV
  ? 'claude'
  : path.join(RESOURCES, 'bin', 'claude')

const PYTHON_PATH = IS_DEV
  ? 'python3'
  : path.join(RESOURCES, 'bin', 'python3')

const FASTAPI_SCRIPT = IS_DEV
  ? path.resolve(__dirname, '..', 'backend', 'main.py')
  : path.join(RESOURCES, 'backend', 'main.py')

// ─── Global references ─────────────────────────────────────────────────

let mainWindow: BrowserWindow | null = null
let claudeManager: ClaudeCodeManager | null = null
let scheduler: ReturnType<typeof initScheduler> | null = null
let fileWatcher: { close: () => Promise<void> } | null = null
let sidecar: SidecarManager | null = null
let nextServerProcess: ReturnType<typeof import('child_process').spawn> | null = null

// ─── App Lifecycle ─────────────────────────────────────────────────────

app.whenReady().then(async () => {
  try {
    await startup()
  } catch (err) {
    console.error('[main] Startup failed:', err)
    app.quit()
  }
})

app.on('window-all-closed', () => {
  shutdown()
  app.quit()
})

app.on('before-quit', () => {
  shutdown()
})

// ─── Startup Sequence ──────────────────────────────────────────────────
// Order matters. Each step depends on the previous.

async function startup(): Promise<void> {
  console.log('[main] Starting Auctor Desktop...')
  console.log(`[main] Mode: ${IS_DEV ? 'development' : 'production'}`)
  console.log(`[main] Workspace: ${WORKSPACE_PATH}`)

  // ── Step 0: Ensure directories exist ─────────────────────────────
  for (const dir of [WORKSPACE_PATH, LOGS_PATH, STATE_PATH]) {
    if (!fs.existsSync(dir)) {
      fs.mkdirSync(dir, { recursive: true })
    }
  }

  // ── Step 1: Load environment ──────────────────────────────────────
  const platformEnv = loadPlatformEnv(ENV_PATH)
  console.log(`[main] Platform env loaded: ${Object.keys(platformEnv).length} vars`)

  // ── Step 2: Validate MCP server ──────────────────────────────────
  await initMcpBridge({
    envPath: ENV_PATH,
    frontendPath: FRONTEND_PATH,
  })

  // ── Step 3: Start Next.js server ─────────────────────────────────
  const nextPort = 3000
  if (IS_DEV) {
    console.log(`[main] Dev mode: expecting Next.js at http://localhost:${nextPort}`)
    console.log(`[main] Run 'pnpm dev' in frontend/ if not already running`)
  } else {
    const { spawn } = await import('child_process')
    nextServerProcess = spawn(
      'node',
      [path.join(FRONTEND_PATH, 'server.js')],
      {
        env: {
          ...process.env,
          ...platformEnv,
          PORT: String(nextPort),
          HOSTNAME: '127.0.0.1',
        },
        stdio: ['ignore', 'pipe', 'pipe'],
      },
    )
    nextServerProcess.stdout?.on('data', (d: Buffer) =>
      console.log(`[next] ${d.toString().trim()}`))
    nextServerProcess.stderr?.on('data', (d: Buffer) =>
      console.error(`[next:err] ${d.toString().trim()}`))

    // Wait for Next.js to be ready
    await waitForServer(`http://127.0.0.1:${nextPort}`, 30_000)
    console.log(`[main] Next.js ready at :${nextPort}`)
  }

  // ── Step 4: Start Python sidecar ─────────────────────────────────
  sidecar = new SidecarManager({
    pythonPath: PYTHON_PATH,
    scriptPath: FASTAPI_SCRIPT,
  })
  sidecar.start()

  // ── Step 5: Load settings ────────────────────────────────────────
  let settings: AppSettings
  try {
    const raw = fs.readFileSync(path.join(STATE_PATH, 'settings.json'), 'utf-8')
    settings = JSON.parse(raw)
  } catch {
    settings = getDefaultSettings()
  }

  // ── Step 6: Initialize Claude Code Manager ───────────────────────
  claudeManager = new ClaudeCodeManager(
    CLAUDE_EXECUTABLE,
    platformEnv,
    settings,
  )
  console.log('[main] Claude Code Manager initialized')

  // ── Step 7: Create window ────────────────────────────────────────
  mainWindow = new BrowserWindow({
    width: 1440,
    height: 900,
    minWidth: 1024,
    minHeight: 600,
    title: 'Auctor',
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false,
      sandbox: false,  // Required for preload contextBridge
    },
    // macOS
    titleBarStyle: process.platform === 'darwin' ? 'hiddenInset' : undefined,
    trafficLightPosition: { x: 16, y: 16 },
  })

  // Open external links in system browser
  mainWindow.webContents.setWindowOpenHandler(({ url }) => {
    shell.openExternal(url)
    return { action: 'deny' }
  })

  mainWindow.loadURL(`http://127.0.0.1:${nextPort}`)

  if (IS_DEV) {
    mainWindow.webContents.openDevTools({ mode: 'detach' })
  }

  // ── Step 8: Start file watcher ───────────────────────────────────
  fileWatcher = initFileWatcher(mainWindow)

  // ── Step 9: Start scheduler ──────────────────────────────────────
  scheduler = initScheduler(claudeManager, settings)
  console.log('[main] Scheduler started')

  // ── Step 10: Register IPC handlers ───────────────────────────────
  registerIpcHandlers(mainWindow, claudeManager, (newSettings) => {
    scheduler?.updateSchedule(newSettings)
    claudeManager?.updateSettings(newSettings)
  })

  console.log('[main] Auctor Desktop ready')
}

// ─── Shutdown Sequence ─────────────────────────────────────────────────

function shutdown(): void {
  console.log('[main] Shutting down...')

  scheduler?.stop()
  claudeManager?.stopAll()
  fileWatcher?.close()
  sidecar?.stop()

  if (nextServerProcess) {
    nextServerProcess.kill('SIGTERM')
    nextServerProcess = null
  }
}

// ─── Helpers ───────────────────────────────────────────────────────────

async function waitForServer(url: string, timeoutMs: number): Promise<void> {
  const start = Date.now()
  while (Date.now() - start < timeoutMs) {
    try {
      const res = await fetch(url)
      if (res.ok) return
    } catch {
      // Server not ready yet
    }
    await new Promise(r => setTimeout(r, 500))
  }
  throw new Error(`Server at ${url} did not start within ${timeoutMs}ms`)
}

function getDefaultSettings(): AppSettings {
  return {
    claudeEnvVars: '',
    model: 'claude-sonnet-4-20250514',
    schedule: {
      morningEnabled: true,
      morningTime: '07:00',
      middayEnabled: true,
      middayTime: '12:00',
      eveningEnabled: true,
      eveningTime: '18:00',
      weeklyEnabled: true,
      weeklyDay: 1,
      weeklyTime: '08:00',
    },
    siteKey: 'consul',
  }
}

4. Renderer Components (Chat Panel + Dashboard Routes)

These live in the existing Next.js frontend/ codebase, not in desktop/. They render in Electron's BrowserWindow.

4.1 Agent Chat Panel

The chat panel is the primary interaction surface. It renders Claude Code's stream-json events as structured UI, not terminal text.

File: frontend/src/components/agent-chat/agent-chat-panel.tsx

'use client'

import { useState, useEffect, useRef, useCallback } from 'react'
import { AgentMessage } from './agent-message'
import { ToolCallCard } from './tool-call-card'
import { ApprovalCard } from './approval-card'
import { ChatInput } from './chat-input'

interface StreamEvent {
  type: string
  data: any
}

interface ChatEntry {
  id: string
  type: 'user' | 'assistant' | 'tool-call' | 'tool-result' | 'error' | 'approval'
  content: string
  metadata?: Record<string, unknown>
  timestamp: number
}

export function AgentChatPanel() {
  const [entries, setEntries] = useState<ChatEntry[]>([])
  const [sessionId, setSessionId] = useState<string | null>(null)
  const [isProcessing, setIsProcessing] = useState(false)
  const [streamingText, setStreamingText] = useState('')
  const scrollRef = useRef<HTMLDivElement>(null)

  // ── Event listener ────────────────────────────────────────────────
  useEffect(() => {
    if (typeof window === 'undefined' || !window.electron) return

    const cleanupEvent = window.electron.on('claude:event', (payload: any) => {
      const { event } = payload as { sessionId: string; event: StreamEvent }

      switch (event.type) {
        case 'assistant:text': {
          // Stream text into the current message bubble
          setStreamingText(prev => prev + (event.data?.text ?? ''))
          break
        }

        case 'assistant:tool_use': {
          // Flush any accumulated streaming text as a message
          flushStreamingText()

          setEntries(prev => [...prev, {
            id: crypto.randomUUID(),
            type: 'tool-call',
            content: event.data?.name ?? 'Unknown tool',
            metadata: {
              toolName: event.data?.name,
              input: event.data?.input,
              status: 'running',
            },
            timestamp: Date.now(),
          }])
          break
        }

        case 'tool:result': {
          // Update the most recent tool-call entry with the result
          setEntries(prev => {
            const updated = [...prev]
            const lastToolCall = [...updated].reverse().find(e => e.type === 'tool-call')
            if (lastToolCall) {
              lastToolCall.metadata = {
                ...lastToolCall.metadata,
                result: event.data?.result,
                status: 'complete',
              }
            }
            return updated
          })
          break
        }

        case 'result': {
          // Turn complete — flush text, mark not processing
          flushStreamingText()
          setIsProcessing(false)
          break
        }

        case 'system:error': {
          setEntries(prev => [...prev, {
            id: crypto.randomUUID(),
            type: 'error',
            content: event.data?.message ?? 'Unknown error',
            timestamp: Date.now(),
          }])
          setIsProcessing(false)
          break
        }
      }
    })

    const cleanupApproval = window.electron.on('claude:approval-requested', (payload: any) => {
      setEntries(prev => [...prev, {
        id: payload.approvalId,
        type: 'approval',
        content: `${payload.toolName} requires approval`,
        metadata: {
          approvalId: payload.approvalId,
          toolName: payload.toolName,
          toolInput: payload.toolInput,
        },
        timestamp: Date.now(),
      }])
    })

    const cleanupEnded = window.electron.on('claude:session-ended', () => {
      flushStreamingText()
      setIsProcessing(false)
      setSessionId(null)
    })

    return () => {
      cleanupEvent?.()
      cleanupApproval?.()
      cleanupEnded?.()
    }
  }, [])

  // ── Auto-scroll ───────────────────────────────────────────────────
  useEffect(() => {
    scrollRef.current?.scrollTo({
      top: scrollRef.current.scrollHeight,
      behavior: 'smooth',
    })
  }, [entries, streamingText])

  // ── Flush accumulated streaming text into a message entry ─────────
  const flushStreamingText = useCallback(() => {
    setStreamingText(prev => {
      if (prev.trim()) {
        setEntries(entries => [...entries, {
          id: crypto.randomUUID(),
          type: 'assistant',
          content: prev,
          timestamp: Date.now(),
        }])
      }
      return ''
    })
  }, [])

  // ── Send message ──────────────────────────────────────────────────
  const handleSend = useCallback(async (text: string) => {
    // Add user message to entries
    setEntries(prev => [...prev, {
      id: crypto.randomUUID(),
      type: 'user',
      content: text,
      timestamp: Date.now(),
    }])
    setIsProcessing(true)

    let sid = sessionId
    if (!sid) {
      // First message: start a new interactive session
      sid = await window.electron.invoke('claude:start-session', {
        type: 'interactive',
        prompt: text,
      }) as string
      setSessionId(sid)
    } else {
      // Subsequent messages: push into existing session
      await window.electron.invoke('claude:send-message', {
        sessionId: sid,
        message: text,
      })
    }
  }, [sessionId])

  // ── Approval handler ──────────────────────────────────────────────
  const handleApproval = useCallback(async (approvalId: string, approved: boolean) => {
    await window.electron.invoke('claude:approve-tool', {
      approvalId,
      approved,
      reason: approved ? undefined : 'Rejected by operator',
    })

    // Update the approval card to show the decision
    setEntries(prev => prev.map(e =>
      e.id === approvalId
        ? { ...e, metadata: { ...e.metadata, decided: true, approved } }
        : e
    ))
  }, [])

  // ── Render ────────────────────────────────────────────────────────
  return (
    <div className="flex flex-col h-full bg-background">
      {/* Scrollable message area */}
      <div ref={scrollRef} className="flex-1 overflow-y-auto p-4 space-y-3">
        {entries.map(entry => {
          switch (entry.type) {
            case 'user':
              return <AgentMessage key={entry.id} role="user" content={entry.content} />
            case 'assistant':
              return <AgentMessage key={entry.id} role="assistant" content={entry.content} />
            case 'tool-call':
              return <ToolCallCard key={entry.id} entry={entry} />
            case 'approval':
              return (
                <ApprovalCard
                  key={entry.id}
                  entry={entry}
                  onApprove={() => handleApproval(entry.id, true)}
                  onReject={() => handleApproval(entry.id, false)}
                />
              )
            case 'error':
              return (
                <div key={entry.id} className="bg-destructive/10 text-destructive text-sm p-3 rounded-lg">
                  {entry.content}
                </div>
              )
          }
        })}

        {/* Currently streaming text */}
        {streamingText && (
          <AgentMessage role="assistant" content={streamingText} isStreaming />
        )}

        {/* Processing indicator */}
        {isProcessing && !streamingText && (
          <div className="flex items-center gap-2 text-muted-foreground text-sm">
            <span className="animate-pulse">●</span> Agent is thinking...
          </div>
        )}
      </div>

      {/* Input area */}
      <ChatInput onSend={handleSend} disabled={isProcessing} />
    </div>
  )
}

4.2 Supporting Components (Stubs)

These are referenced by the chat panel. Implement during build:

agent-message.tsx — Renders a message bubble. User messages right-aligned, assistant messages left-aligned. Assistant content rendered through a markdown renderer (use react-markdown + rehype-highlight for code blocks).

tool-call-card.tsx — Collapsible card showing tool name, input arguments (JSON, syntax-highlighted), and result (when available). Shows a loading spinner while status === 'running'. Color-coded by tool category: blue for data queries, yellow for mutations, red for publish operations.

approval-card.tsx — Full-width card with the tool name, input summary, and two buttons: Approve (green) and Reject (red). Disabled after decision. Shows the decision result inline.

chat-input.tsx — Text input with send button. Supports Shift+Enter for newlines, Enter to send. Disabled prop greys out during processing.

5. Dashboard Route Additions

Three new routes for Claude Code observability. These are Next.js pages in the existing frontend.

`/sessions` — Session Timeline

Reads ~/.auctor/logs/ directory. Each .json file is a session log (array of stream-json events). Renders a timeline with session cards showing: timestamp, type (morning/midday/evening/weekly/interactive), duration, tool call count, key observations.

Data source: File system via workspace:list-dir + workspace:read-file IPC calls.

`/workspace` — Workspace File Browser

Tree view of ~/.auctor/workspace/. Clicking a file shows its content (markdown rendered, JSON syntax-highlighted). Real-time updates via workspace:file-changed events — when Claude Code writes to a file, the browser highlights the change.

Data source: workspace:list-dir for tree, workspace:read-file for content.

`/memory` — Memory Timeline

Parses memory/observations.md, memory/decisions.md, memory/learnings.md, and memory/mistakes.md into a unified timeline. Each entry shows the date, source file, and content. The timeline is reverse-chronological.

This is the operator's primary window into the agent's thinking. They can see what the agent noticed today, what decisions it made and why, and what strategic insights it has accumulated.

Data source: workspace:read-file for each memory file, parsed by date headers.

6. Build and Packaging

Development Workflow

# Terminal 1: Next.js dashboard (hot reload)
cd frontend && pnpm dev

# Terminal 2: Python sidecar
cd backend && python main.py

# Terminal 3: Electron app (watches for TS changes)
cd desktop && pnpm dev:watch

The Electron app in dev mode expects Next.js at :3000 and FastAPI at :8000. It does NOT start them — that's the operator's job in dev mode. In production, main.ts starts both.

Production Build

# 1. Build Next.js standalone output
cd frontend && pnpm build
# This produces .next/standalone/ — a self-contained Node.js server

# 2. Build desktop package
cd desktop && pnpm build
# This:
#   a. Compiles TypeScript to dist/
#   b. Copies .next/standalone to extraResources/next-server
#   c. Packages with electron-builder into release/

Bundling Claude Code

The claude binary must be available at runtime. Two approaches:

Approach A: Require system installation (Phase 4)

Auctor checks PATH for claude on startup. If not found, shows a setup screen instructing the operator to install Claude Code globally (npm i -g @anthropic-ai/claude-code). This is the simplest approach and avoids bundling license-sensitive binaries.

Approach B: Bundle as extraResource (Phase 5)

Extract the claude binary from node_modules/@anthropic-ai/claude-code/ during build and include it in extraResources/bin/claude. Update CLAUDE_EXECUTABLE path accordingly. This makes the app fully self-contained.

Recommendation: Start with Approach A. The operator running Auctor on a dedicated machine can easily install Claude Code globally. Move to Approach B when preparing for distribution.

macOS Entitlements

<!-- desktop/build/entitlements.mac.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <!-- Required for network access (Supabase, DataForSEO, GSC, etc.) -->
  <key>com.apple.security.network.client</key>
  <true/>
  <!-- Required for spawning child processes (Claude Code, Python) -->
  <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
  <true/>
  <!-- Required for hardened runtime + spawning binaries -->
  <key>com.apple.security.cs.disable-library-validation</key>
  <true/>
</dict>
</plist>

7. Verification Checklist

Run these checks after Phase 4 build is complete. Each maps to a spec requirement.

Core Functionality

#	Test	Expected	Verified
1	`pnpm dev:watch` in desktop/	Electron window opens, loads Next.js dashboard	☐
2	Type a message in chat panel	Claude Code spawns (check Activity Monitor/Task Manager for `claude` process), streams response	☐
3	Send second message in same session	No new process spawned. Same session continues. Check `session-event` events in DevTools console.	☐
4	Claude Code calls `mcp__auctor__read-domain-summary`	Tool call card appears in chat UI with tool name, arguments, and result	☐
5	Claude Code attempts `mcp__auctor__upload-to-cms`	Approval card appears. Clicking Reject blocks the publish. Clicking Approve allows it.	☐
6	Close and reopen Electron app	Previous session ID is recoverable. `--resume` works.	☐
7	Idle for 30+ minutes	Session auto-terminates (check `session-ended` event).	☐

Scheduled Sessions

#	Test	Expected	Verified
8	Wait for morning schedule (or manually trigger)	New `claude` process spawns with scheduled prompt.	☐
9	Check `~/.auctor/logs/` after scheduled session	JSON log file exists with session events.	☐
10	Check `memory/observations.md` after morning session	New dated entry appended by agent.	☐
11	Check git log in workspace	Auto-commit with `session:` prefix message.	☐

File Watcher

#	Test	Expected	Verified
12	Manually edit `memory/observations.md`	`workspace:file-changed` event fires in renderer.	☐
13	Navigate to /workspace route	File tree renders. Clicking a file shows its content.	☐
14	Agent writes to workspace during session	Dashboard updates within 1–2 seconds.	☐

Security

#	Test	Expected	Verified
15	Agent attempts `Write(brand/voice.md)`	Blocked by `.claude/settings.json` deny rule.	☐
16	Agent attempts to write outside workspace	`canUseTool` returns `{ allowed: false }`. Agent sees error.	☐
17	Check `~/.auctor/logs/tool-audit.log`	Every tool call logged with timestamp and tool name.	☐

8. Known Risks and Mitigations

Risk: SDK API surface changes

The @anthropic-ai/claude-code SDK is pre-1.0. The query() function signature, event types, and metadata methods (accountInfo, mcpServerStatus) may change between releases.

Mitigation: Pin the SDK version in package.json (exact version, not range). Test against each new release before upgrading. The types.ts file acts as an adapter layer — if SDK types change, update the adapter, not every consumer.

Risk: MCP server process lifecycle

Claude Code spawns the MCP server as a child process. If the MCP server crashes mid-session, Claude Code's tool calls fail silently or with opaque errors.

Mitigation: Phase 5 moves the MCP server in-process (shared runtime). For Phase 4, add health-check logic: if mcp__auctor__* tools fail 3 times consecutively, the chat panel shows a "MCP server may be down" warning and offers a restart button.

Risk: Git conflicts from concurrent sessions

If a scheduled session and an interactive session both write to memory/observations.md simultaneously, git may encounter merge conflicts on the next commit.

Mitigation: The scheduler should check for active interactive sessions before spawning. If an interactive session is active, defer the scheduled session by 15 minutes. Add this check to scheduler.ts:

// Before spawning scheduled session
if (manager.getSessions().some(s => s.type === 'interactive' && s.isProcessing)) {
  console.log(`[scheduler] Deferring ${logSuffix} — interactive session active`)
  setTimeout(() => runScheduledSession(manager, prompt, logSuffix), 15 * 60 * 1000)
  return
}

Risk: Electron memory pressure on dedicated machine

Electron + Next.js + Claude Code + Python sidecar can consume 400–800 MB combined during active sessions. On a dedicated machine with 8 GB RAM, this leaves headroom. On a shared machine, it may compete with other processes.

Mitigation: Document minimum system requirements: 8 GB RAM, 4 cores, 20 GB disk. The 30-minute idle timeout and max-5-sessions limit prevent unbounded memory growth.

9. What's Deferred to Phase 5

These are documented but intentionally not built in Phase 4:

In-process MCP server — Currently runs as a stdio child of Claude Code. Phase 5 moves it in-process for shared DB pool and lower latency.
Auto-updater — electron-updater dependency is included but not wired. Phase 5 adds GitHub Releases or custom update server.
Bundled Claude Code — Phase 4 requires system claude installation. Phase 5 bundles it.
Session resume across app restarts — --session-id and --resume are supported by the SDK but the UI for "resume previous session?" is Phase 5.
Event-triggered sessions — Webhook receiver for competitor alerts, analytics anomalies. Phase 5.
Multi-site support — Current spec hardcodes siteKey: 'consul'. Phase 5 adds site switching.

Appendix A: Workspace Initialization Script

Run this once to set up a fresh workspace for a new Auctor installation:

#!/bin/bash
# scripts/init-workspace.sh

WORKSPACE="$HOME/.auctor/workspace"

echo "Initializing Auctor workspace at $WORKSPACE"

# Create directory structure
mkdir -p "$WORKSPACE"/{brand,content/{published,drafts,ideas},intelligence/{analytics,search,competitors,market},memory,calendar,operations/{sync,generate},config,.claude}

# Create log and state directories
mkdir -p "$HOME/.auctor"/{logs,state}

# Initialize git repo
cd "$WORKSPACE"
git init
echo "logs/" > .gitignore
echo "*.tmp" >> .gitignore

# Copy template files (from the Auctor repo)
# These would be populated from the project's templates/ directory
touch brand/voice.md brand/audience.md brand/style-guide.md
touch memory/observations.md memory/decisions.md memory/learnings.md memory/mistakes.md memory/current-focus.md
touch calendar/editorial-calendar.md calendar/deadlines.json
touch content/drafts/_queue.json content/ideas/backlog.md
touch config/endpoints.json config/thresholds.json

# Create .claude/settings.json with permission rules
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(operations/*)",
      "Write(content/*)",
      "Write(memory/*)",
      "Edit(content/*)",
      "Edit(memory/*)",
      "Write(calendar/*)",
      "Edit(calendar/*)"
    ],
    "deny": [
      "Write(operations/*)",
      "Write(config/*)",
      "Write(brand/*)",
      "Write(CLAUDE.md)"
    ]
  }
}
EOF

# Initial commit
git add -A
git commit -m "init: workspace scaffolding"

echo "Workspace initialized. Copy CLAUDE.md from the Auctor repo to $WORKSPACE/CLAUDE.md"

Appendix B: Dependency Matrix

Package	Version	Used In	Purpose
`electron`	^40.0.0	desktop/	Desktop shell, BrowserWindow, IPC
`electron-builder`	^25.0.0	desktop/ build	Packaging (.dmg, .exe, .AppImage)
`@anthropic-ai/claude-code`	^1.0.0	desktop/ runtime	SDK `query()` for embedding Claude Code
`node-cron`	^3.0.3	desktop/ runtime	Scheduled session triggers
`chokidar`	^4.0.0	desktop/ runtime	Workspace file watching
`dotenv`	^16.4.0	desktop/ runtime	.env.local loading
`electron-updater`	^6.3.0	desktop/ runtime	Auto-update (Phase 5)
`concurrently`	^9.0.0	desktop/ dev	Run tsc + electron in parallel
`nodemon`	^3.0.0	desktop/ dev	Restart electron on file changes
`typescript`	^5.7.0	desktop/ dev	Type checking

End of Addendum #5. This document provides the complete implementation specification for Auctor's Phase 4 desktop shell. All code in this document is implementation-ready — copy into the project and adjust paths as needed for your repository structure.