ContextStudioWizard/HANDOVER.md

Handover — Context Studio Wizard

Last updated: 2026-03-09

Current status

Fully working end-to-end. The wizard generates a project, ./start.sh starts the container, registers the project, launches the Electron UI, agents start cleanly, and kai's terminal opens and primes without any trust dialog or startup errors.

What was fixed this session (newest first)

1. Trust dialog bypass

File: lib/workflow.sh → agent .claude/settings.json Symptom: Claude Code shows "Quick safety check — do you trust this folder?" on every start, blocking /prime injection. Fix: Added "hasTrustDialogAccepted": true to every generated agent's .claude/settings.json.

2. CLI ready marker — container/host gap

File: lib/container.sh → generated bin/claude Symptom: [CLI] Timeout waiting for CLI ready marker for kai (10000ms) — 10s delay before /prime. Root cause: CS Core polls /tmp/cs-ready-<agentId> on the host. Claude runs inside the container, so it can't create this file on the host. Fix: bin/claude detects when it's being invoked interactively from an agent PTY ($PWD == $PROJECT_DIR/workflow/agents/*), extracts the agent ID from basename "$PWD", and spawns a background job (sleep 3 && touch /tmp/cs-ready-<agentId>) before running podman exec.

3. Project not registered → localhost:null for all agents

File: lib/container.sh → generated start.sh Symptom: All agent SSE URLs are http://localhost:null/... → DOMException, no agent communication. Root cause (deep):

• waitForServers() in server-management.js polls runtimeConfig.findRuntimeByWorkflowDir()
• That function maps workflowDir → project UUID → lock file at ~/.config/context-studio/projects/locks/<uuid>.json
• acquireProjectLock() in launcher.js writes the lock file — but silently skips it if the project is not registered in ~/.config/context-studio/projects/<uuid>.json
• Without the lock file, waitForServers() always times out → applyRuntimePorts() never called → all agent ports remain null Fix: start.sh now auto-registers the project before launching Electron. It scans ~/.config/context-studio/projects/ for an existing entry matching $PROJECT_DIR/workflow, and if none is found, writes a new <uuid>.json registration file using python3.

4. serverStartupTimeout is in electron-config.js, not system.json

File: ~/.context-studio/core/config/electron-config.js Symptom: 30s startup timeout even when servers start in ~3s. Root cause: The timeout is read from ctx.getElectronConfig()?.startup.serverStartupTimeout. This comes from electron-config.js in the core config dir, NOT from the workflow's system.json. Fix: Changed serverStartupTimeout from 30000 to 90000 in electron-config.js. Note: electron-config.js is a config file (not source), so editing it is appropriate.

5. Credential mounts — ~/.claude/.credentials.json not mounted

File: lib/container.sh → generated start.sh Symptom: Claude Code inside container can't authenticate to Anthropic. Root cause: start.sh was only mounting ~/.anthropic (empty on this system). Actual credentials are at ~/.claude/.credentials.json (or $CLAUDE_CONFIG_DIR/.credentials.json, ~/.claude.json, $CLAUDE_CONFIG_DIR/.claude.json). Fix: start.sh now builds _CREDS_ARGS array and conditionally mounts whichever credential files exist on the host. All known Claude Code credential locations are checked.

6. API key check in wizard

File: lib/prereqs.sh → ensure_api_key() Symptom: Agents fail if ANTHROPIC_API_KEY not set and no credentials file mounted. Fix: Added ensure_api_key() called from check_prerequisites(). Checks in order: ANTHROPIC_API_KEY env var → $CLAUDE_CONFIG_DIR/.credentials.json → ~/.claude/.credentials.json → ~/.claude.json → $CLAUDE_CONFIG_DIR/.claude.json → ~/.anthropic/.credentials.json. If none found, prompts for API key with masked input and offers to save to shell profile.

7. Ctrl+C graceful abort with cleanup

File: wizard.sh Fix: trap 'handle_sigint' INT in main(). On Ctrl+C: shows gum confirm popup. If confirmed: removes $PROJECT_DIR (if created) and $CS_CORE_DIR (if cloned this session). State flags: _WIZARD_PROJECT_CREATED and _WIZARD_CORE_CLONED (set at moment of action). Installed packages (git, podman) are never reverted.

Key architecture facts

Lock file mechanism (critical for startup)

• Lock file: ~/.config/context-studio/projects/locks/<uuid>.json
• Project registration: ~/.config/context-studio/projects/<uuid>.json
• start.sh auto-registers the project before launching Electron
• Without registration, acquireProjectLock() silently skips writing the lock file
• Without the lock file, all agent ports remain null → localhost:null errors

How CS Core + Electron work together

• start.sh starts the container, registers the project, then launches Electron
• Electron's server-management.js spawns node core/start.js --ui-mode=headless
• That process starts all A2A agent servers on the host (not in container)
• Servers register with the registry (port 8000), write the lock file
• waitForServers() polls until lock file appears + health check passes
• applyRuntimePorts() is called → agent ports loaded from lock file
• CLI ready marker (/tmp/cs-ready-<agentId>) created by bin/claude after 3s delay

Credential lookup order (container mounts)

1. ANTHROPIC_API_KEY env var (passed via -e)
2. ~/.anthropic/ (mounted read-only, always)
3. $CLAUDE_CONFIG_DIR/.credentials.json or ~/.claude/.credentials.json (mounted if exists)
4. ~/.claude.json (mounted if exists)
5. $CLAUDE_CONFIG_DIR/.claude.json (mounted if exists)

What runs where

• Container: Claude Code binary only (sleep infinity + podman exec)
• Host: Electron UI, CS Core, all A2A agent server processes (node)
• bin/claude: bridges host agent calls → container claude

Generated files per project

• bin/claude — wrapper: workdir fallback, credential routing, ready marker creation
• start.sh — starts container, mounts credentials, registers project, launches Electron
• stop.sh — force-removes container
• update.sh — git pull core, npm update claude-code in container, apt upgrade

File locations

• Wizard: /home/elmar/Projects/ContextStudioWizard/
• Core config (editable): /home/elmar/.context-studio/core/config/electron-config.js
• Core (read-only source): /home/elmar/.context-studio/core/ (never modify source, never push)
• CS settings: ~/.config/context-studio/projects/
• Lock files: ~/.config/context-studio/projects/locks/

What NOT to do

• Never modify ~/.context-studio/core/ source files — read-only
• electron-config.js in core/config/ is an exception — it is a config file, safe to edit
• Never commit or push to the core repo