@proletariat/cli 0.3.55 → 0.3.56

package/dist/lib/execution/runners.js

@@ -10,7 +10,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import { DEFAULT_EXECUTION_CONFIG, } from './types.js';
 import { getSetTitleCommands } from '../terminal.js';
-import { readDevcontainerJson } from './devcontainer.js';
+import { readDevcontainerJson, generateOrchestratorDockerfile } from './devcontainer.js';
 import { getCodexCommand, resolveCodexExecutionContext, validateCodexMode } from './codex-adapter.js';
 // =============================================================================
 // Terminal Title Helpers
@@ -388,23 +388,84 @@ export function runExecutorPreflight(environment, executor, options) {
     return { ok: true };
 }
 /**
- * Build a role-specific prompt for orchestrator sessions.
- * Unlike ticket workers, orchestrators are long-running managers that delegate work.
+ * Build the system prompt for orchestrator sessions.
+ * This is injected via Claude Code's --system-prompt flag so the orchestrator
+ * knows its role immediately without relying on CLAUDE.md.
  */
+export function buildOrchestratorSystemPrompt(context) {
+    const hqName = context.hqName || 'workspace';
+    let prompt = `You are an orchestrator for the **${hqName}** project. `;
+    prompt += `Use \`prlt\` to view what's running — board, sessions, tickets, PRs. `;
+    prompt += `Do not implement any work yourself. `;
+    prompt += `Your job is to review, plan, investigate, delegate (via \`prlt work start\`), and review completed work.\n\n`;
+    prompt += `## Your Role\n`;
+    prompt += `- Plan and prioritize work across the board\n`;
+    prompt += `- Delegate implementation to agents via \`prlt work start\`\n`;
+    prompt += `- Monitor agent progress and review completed work\n`;
+    prompt += `- Merge completed PRs via \`gh pr merge --squash\`\n`;
+    prompt += `- Never write code or make changes to source files yourself\n\n`;
+    prompt += `## Discovering State\n`;
+    prompt += `Always discover current state dynamically — do NOT rely on static context files:\n`;
+    prompt += `- **Board**: \`prlt board view\`, \`prlt ticket list\`, \`prlt ticket show <id>\`\n`;
+    prompt += `- **Agents**: \`prlt session list\`, \`prlt session peek <session>\`, \`prlt work status\`\n`;
+    prompt += `- **PRs/CI**: \`gh pr list\`, \`gh pr view <num>\`, \`gh pr checks <num>\`\n`;
+    prompt += `- All prlt MCP tools are also available\n\n`;
+    prompt += `## Spawning Agents\n`;
+    prompt += `\`\`\`\n`;
+    prompt += `script -q /dev/null prlt work start TKT-XXXX --ephemeral --skip-permissions --create-pr --display background --action implement --run-on-host --yes\n`;
+    prompt += `\`\`\`\n`;
+    prompt += `- Review: \`--action review-comment\`\n`;
+    prompt += `- Fix: \`--action review-fix\`\n\n`;
+    prompt += `## Workflow\n`;
+    prompt += `- Squash merge only: \`gh pr merge --squash\`\n`;
+    prompt += `- After merging: subsequent PRs from parallel agents will need rebase\n`;
+    prompt += `- Kill stale sessions after their PRs are merged\n\n`;
+    // Load .orchestrator-context.md from HQ root if it exists
+    if (context.hqPath) {
+        const contextFilePath = path.join(context.hqPath, '.orchestrator-context.md');
+        if (fs.existsSync(contextFilePath)) {
+            try {
+                const contextContent = fs.readFileSync(contextFilePath, 'utf-8').trim();
+                if (contextContent) {
+                    prompt += `## Workspace Context\n\n${contextContent}\n\n`;
+                }
+            }
+            catch {
+                // Ignore read errors
+            }
+        }
+    }
+    return prompt;
+}
 function buildOrchestratorPrompt(context) {
+    // Full prompt including role context — used for non-Claude executors that
+    // don't support --system-prompt. For Claude Code, runHost() splits this into
+    // a system prompt (role/tools) + a shorter user message.
     const hqName = context.hqName || 'workspace';
     let prompt = `# Orchestrator: ${hqName}\n\n`;
     prompt += `You are the orchestrator for the **${hqName}** workspace using the prlt ecosystem.\n\n`;
     prompt += `## Your Role\n`;
-    prompt += `- View and manage work using \`prlt\` CLI commands or MCP tools\n`;
-    prompt += `- Delegate tasks to agents — do NOT implement work yourself\n`;
-    prompt += `- Monitor agent progress, review completed work, and manage the board\n`;
-    prompt += `- Spawn agents for Ready tickets, review PRs, merge completed work\n\n`;
-    prompt += `## Available Tools\n`;
-    prompt += `- Board: \`prlt board\`, \`prlt ticket list\`, \`prlt ticket show <id>\`, \`prlt work status\`\n`;
-    prompt += `- Agents: \`prlt work start <ticket-id>\`, \`prlt session list\`, \`prlt session peek <session>\`, \`prlt session poke <session> "message"\`\n`;
-    prompt += `- PRs: \`gh pr list\`, \`gh pr view\`, \`gh pr merge\`\n`;
-    prompt += `- MCP: All prlt MCP tools are available\n\n`;
+    prompt += `- Plan and prioritize work across the board\n`;
+    prompt += `- Delegate implementation to agents via \`prlt work start\`\n`;
+    prompt += `- Monitor agent progress and review completed work\n`;
+    prompt += `- Merge completed PRs via \`gh pr merge --squash\`\n`;
+    prompt += `- Never write code or make changes to source files yourself\n\n`;
+    prompt += `## Discovering State\n`;
+    prompt += `Always discover current state dynamically — do NOT rely on static context files:\n`;
+    prompt += `- **Board**: \`prlt board view\`, \`prlt ticket list\`, \`prlt ticket show <id>\`\n`;
+    prompt += `- **Agents**: \`prlt session list\`, \`prlt session peek <session>\`, \`prlt work status\`\n`;
+    prompt += `- **PRs/CI**: \`gh pr list\`, \`gh pr view <num>\`, \`gh pr checks <num>\`\n`;
+    prompt += `- All prlt MCP tools are also available\n\n`;
+    prompt += `## Spawning Agents\n`;
+    prompt += `\`\`\`\n`;
+    prompt += `script -q /dev/null prlt work start TKT-XXXX --ephemeral --skip-permissions --create-pr --display background --action implement --run-on-host --yes\n`;
+    prompt += `\`\`\`\n`;
+    prompt += `- Review: \`--action review-comment\`\n`;
+    prompt += `- Fix: \`--action review-fix\`\n\n`;
+    prompt += `## Workflow\n`;
+    prompt += `- Squash merge only: \`gh pr merge --squash\`\n`;
+    prompt += `- After merging: subsequent PRs from parallel agents will need rebase\n`;
+    prompt += `- Kill stale sessions after their PRs are merged\n\n`;
     // Load .orchestrator-context.md from HQ root if it exists
     if (context.hqPath) {
         const contextFilePath = path.join(context.hqPath, '.orchestrator-context.md');
@@ -566,8 +627,24 @@ export async function runHost(context, executor, config, displayMode = 'terminal
     const timestamp = Date.now();
     const scriptPath = path.join(baseDir, `exec-${context.ticketId}-${timestamp}.sh`);
     const promptPath = path.join(baseDir, `prompt-${context.ticketId}-${timestamp}.txt`);
-    // Write prompt to separate file to avoid any shell escaping issues
-    fs.writeFileSync(promptPath, prompt, { mode: 0o644 });
+    // For orchestrator sessions with Claude Code, split the prompt:
+    // - System prompt (role/tools/context) → injected via --system-prompt flag
+    // - User message (action instructions or default) → passed as the initial message
+    // Non-Claude executors get the full combined prompt as the user message.
+    let systemPromptPath = null;
+    if (context.isOrchestrator && isClaudeExecutor(executor)) {
+        const systemPrompt = buildOrchestratorSystemPrompt(context);
+        systemPromptPath = path.join(baseDir, `system-prompt-${context.ticketId}-${timestamp}.txt`);
+        fs.writeFileSync(systemPromptPath, systemPrompt, { mode: 0o644 });
+        // Override user message: just action instructions or a default startup message
+        const userMessage = context.actionPrompt
+            || 'You are now running as the orchestrator. Check the board status and report what you see.';
+        fs.writeFileSync(promptPath, userMessage, { mode: 0o644 });
+    }
+    else {
+        // Write full prompt (includes role context for non-Claude executors)
+        fs.writeFileSync(promptPath, prompt, { mode: 0o644 });
+    }
     // Build the executor command using getExecutorCommand() output
     // For Claude Code, we also support outputMode and additional flags
     // For non-Claude executors, we use the command as-is from getExecutorCommand()
@@ -579,7 +656,9 @@ export async function runHost(context, executor, config, displayMode = 'terminal
         const printFlag = config.outputMode === 'print' ? '-p ' : '';
         // --effort high: skips the effort level prompt for automated agents (TKT-1134)
         const effortFlag = skipPermissions ? '--effort high ' : '';
-        executorInvocation = `${cmd} ${permissionsFlag}${effortFlag}${printFlag}"$(cat "$PROMPT_PATH")"`;
+        // Orchestrator sessions inject their role via --system-prompt
+        const systemPromptFlag = systemPromptPath ? '--system-prompt "$(cat "$SYSTEM_PROMPT_PATH")" ' : '';
+        executorInvocation = `${cmd} ${permissionsFlag}${effortFlag}${printFlag}${systemPromptFlag}"$(cat "$PROMPT_PATH")"`;
     }
     else {
         // Non-Claude executors: build command from getExecutorCommand() args
@@ -589,10 +668,24 @@ export async function runHost(context, executor, config, displayMode = 'terminal
     }
     // Build script that runs executor and keeps shell open after completion
     const setTitleCmds = getSetTitleCommands(windowTitle);
+    const systemPromptVar = systemPromptPath ? `\nSYSTEM_PROMPT_PATH="${systemPromptPath}"` : '';
+    // Ephemeral agents auto-close after completion instead of dropping to interactive shell
+    const postExecBlock = context.isEphemeral
+        ? `
+echo ""
+echo "✅ Ephemeral agent work complete. Session will auto-close in 5s..."
+sleep 5
+exit 0
+`
+        : `
+echo ""
+echo "✅ Agent work complete. Press Enter to close or run more commands."
+exec $SHELL
+`;
     const scriptContent = `#!/bin/bash
 # Auto-generated script for ticket ${context.ticketId}
 SCRIPT_PATH="${scriptPath}"
-PROMPT_PATH="${promptPath}"
+PROMPT_PATH="${promptPath}"${systemPromptVar}
 ${setTitleCmds}
 echo "🚀 Starting: ${sessionName}"
 echo ""
@@ -601,12 +694,8 @@ cd "${context.worktreePath}"
 (unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT; ${executorInvocation})
 
 # Clean up script and prompt files
-rm -f "$SCRIPT_PATH" "$PROMPT_PATH"
-
-echo ""
-echo "✅ Agent work complete. Press Enter to close or run more commands."
-exec $SHELL
-`;
+rm -f "$SCRIPT_PATH" "$PROMPT_PATH"${systemPromptPath ? ' "$SYSTEM_PROMPT_PATH"' : ''}
+${postExecBlock}`;
     fs.writeFileSync(scriptPath, scriptContent, { mode: 0o755 });
     try {
         // Check if tmux is available
@@ -640,8 +729,10 @@ exec $SHELL
         if (displayMode === 'foreground') {
             try {
                 // Clear screen and attach - this blocks until user detaches or claude exits
-                // Use -CC for iTerm when control mode is enabled
-                const fgTmuxAttach = buildTmuxAttachCommand(useControlMode);
+                // Never use -CC in foreground mode: control mode sends raw tmux protocol
+                // sequences (%begin, %output, %end) that render as garbled text unless
+                // iTerm's native CC handler is active (only happens in new tabs opened via AppleScript)
+                const fgTmuxAttach = buildTmuxAttachCommand(false);
                 execSync(`clear && ${fgTmuxAttach} -t "${sessionName}"`, { stdio: 'inherit' });
                 return {
                     success: true,
@@ -1617,6 +1708,14 @@ async function runDevcontainerInTerminal(context, devcontainerCmd, config) {
     // Write script - run the command directly
     // No auth check needed - if auth is required, Claude will show "Invalid API key"
     // and user can run /login from there
+    // Ephemeral agents auto-close after completion
+    const postExecBlock = context.isEphemeral
+        ? `echo ""
+echo "✅ Ephemeral agent work complete. Session will auto-close in 5s..."
+sleep 5
+exit 0`
+        : `# Keep shell open after completion
+exec $SHELL`;
     const scriptContent = `#!/bin/bash
 # Auto-generated script for ticket ${context.ticketId}
 ${setTitleCmds}
@@ -1629,8 +1728,7 @@ ${devcontainerCmd}
 # Clean up script file
 rm -f "${scriptPath}"
 
-# Keep shell open after completion
-exec $SHELL
+${postExecBlock}
 `;
     fs.writeFileSync(scriptPath, scriptContent, { mode: 0o755 });
     // Check if we should open in background (don't steal focus)
@@ -1855,6 +1953,15 @@ async function runDevcontainerInTmux(context, devcontainerCmd, config, displayMo
         // Unset CI to prevent Claude from detecting CI environment which suppresses TUI output
         // Unset CLAUDECODE to allow Claude Code to run (prevents nested session error)
         // Note: We keep DEVCONTAINER set so prlt workspace detection works correctly
+        // Ephemeral agents auto-close after completion
+        const containerPostExec = context.isEphemeral
+            ? `echo ""
+echo "✅ Ephemeral agent work complete. Session will auto-close in 5s..."
+sleep 5
+exit 0`
+            : `echo ""
+echo "✅ Agent work complete. Press Enter to close or run more commands."
+exec bash`;
         const tmuxScript = `#!/bin/bash
 export TERM=xterm-256color
 export COLORTERM=truecolor
@@ -1863,9 +1970,7 @@ unset CLAUDECODE
 echo "🚀 Starting: ${sessionName}"
 echo ""
 ${claudeCmd}
-echo ""
-echo "✅ Agent work complete. Press Enter to close or run more commands."
-exec bash
+${containerPostExec}
 `;
         const scriptPath = `/tmp/prlt-${sessionName}.sh`;
         // Write script and start tmux session inside container
@@ -1945,8 +2050,10 @@ exec bash
         if (displayMode === 'foreground') {
             try {
                 // Clear screen and attach - this blocks until user detaches or claude exits
-                // Use -CC for iTerm when control mode is enabled
-                const fgTmuxAttach = buildTmuxAttachCommand(useControlMode, true);
+                // Never use -CC in foreground mode: control mode sends raw tmux protocol
+                // sequences (%begin, %output, %end) that render as garbled text unless
+                // iTerm's native CC handler is active (only happens in new tabs opened via AppleScript)
+                const fgTmuxAttach = buildTmuxAttachCommand(false, true);
                 execSync(`clear && docker exec -it ${actualContainerId} ${fgTmuxAttach} -t "${sessionName}"`, { stdio: 'inherit' });
                 return {
                     success: true,
@@ -2211,6 +2318,327 @@ export async function runDocker(context, executor, config) {
     }
 }
 // =============================================================================
+// Orchestrator Docker Runner (Sibling Container Pattern)
+// =============================================================================
+/**
+ * Run orchestrator in a Docker container using the sibling container pattern.
+ *
+ * Architecture:
+ * ```
+ * Host Docker daemon
+ * ├── orchestrator container (has /var/run/docker.sock mounted)
+ * ├── agent-1 container (spawned by orchestrator, sibling)
+ * ├── agent-2 container (spawned by orchestrator, sibling)
+ * ```
+ *
+ * The orchestrator container needs:
+ * - HQ directory mounted (proletariat-hq)
+ * - Docker socket mounted (/var/run/docker.sock) — so it can spawn agent containers as siblings
+ * - prlt CLI installed in the container
+ * - OAuth credentials for Claude Code (via Docker volume)
+ * - tmux for session persistence inside the container
+ */
+export async function runOrchestratorInDocker(context, executor, config, options) {
+    const displayMode = options?.displayMode || 'background';
+    const hqPath = context.hqPath || context.worktreePath;
+    const hqName = context.hqName || 'default';
+    const orchestratorName = context.agentName || 'main';
+    // Container name matches tmux session name for consistency
+    const containerName = `prlt-orchestrator-${(hqName).replace(/[^a-zA-Z0-9._-]/g, '-')}-${(orchestratorName).replace(/[^a-zA-Z0-9._-]/g, '-')}`;
+    const imageName = `prlt-orchestrator-${(hqName).replace(/[^a-zA-Z0-9._-]/g, '-')}:latest`;
+    try {
+        // Check Docker is running
+        if (!isDockerRunning()) {
+            return {
+                success: false,
+                error: 'Docker is not running. Please start Docker Desktop and try again.',
+            };
+        }
+        // Check if container already exists and is running
+        if (containerExists(containerName)) {
+            if (isContainerRunning(containerName)) {
+                return {
+                    success: false,
+                    error: `Orchestrator container "${containerName}" is already running. Use "prlt orchestrator attach" to reattach.`,
+                };
+            }
+            // Remove stopped container
+            try {
+                execSync(`docker rm -f ${containerName}`, { stdio: 'pipe' });
+            }
+            catch {
+                // Ignore removal errors
+            }
+        }
+        // Generate Dockerfile
+        const orchestratorDockerOptions = {
+            orchestratorName,
+            hqPath,
+            executor,
+        };
+        const dockerfileContent = generateOrchestratorDockerfile(orchestratorDockerOptions);
+        // Write Dockerfile to temp directory
+        const buildDir = path.join(hqPath, '.proletariat', 'orchestrator-docker');
+        fs.mkdirSync(buildDir, { recursive: true });
+        const dockerfilePath = path.join(buildDir, 'Dockerfile');
+        fs.writeFileSync(dockerfilePath, dockerfileContent);
+        // Build the image
+        const hostPrltVersion = getHostPrltVersion();
+        const buildArgs = {
+            PRLT_VERSION: hostPrltVersion || 'latest',
+        };
+        const buildArgFlags = Object.entries(buildArgs)
+            .map(([key, value]) => `--build-arg ${key}="${value}"`)
+            .join(' ');
+        console.debug(`[runners:orchestrator-docker] Building image: ${imageName}`);
+        try {
+            execSync(`docker build -t ${imageName} -f "${dockerfilePath}" ${buildArgFlags} "${buildDir}"`, { stdio: 'pipe' });
+        }
+        catch (buildError) {
+            return {
+                success: false,
+                error: `Failed to build orchestrator Docker image: ${buildError instanceof Error ? buildError.message : buildError}`,
+            };
+        }
+        // Build mount flags for docker run
+        const mounts = [
+            // Mount HQ directory
+            `-v "${hqPath}:/hq:cached"`,
+            // Docker socket for sibling container pattern
+            `-v /var/run/docker.sock:/var/run/docker.sock`,
+            // Claude credentials volume (shared with agent containers)
+            ...(executor === 'claude-code' ? ['-v "claude-credentials:/home/node/.claude"'] : []),
+            // Persistent bash history
+            '-v "claude-bash-history:/commandhistory"',
+        ];
+        // Build environment variables
+        const envVars = [
+            `-e PRLT_HQ_PATH=/hq`,
+            `-e PRLT_AGENT_NAME="orchestrator-${orchestratorName}"`,
+            `-e PRLT_HOST_PATH="${hqPath}"`,
+            // Pass through GitHub tokens for agent spawning
+            ...(process.env.GITHUB_TOKEN ? [`-e GITHUB_TOKEN="${process.env.GITHUB_TOKEN}"`] : []),
+            ...(process.env.GH_TOKEN ? [`-e GH_TOKEN="${process.env.GH_TOKEN}"`] : []),
+            // Pass ANTHROPIC_API_KEY if available (for cases where OAuth is not set up)
+            ...(process.env.ANTHROPIC_API_KEY ? [`-e ANTHROPIC_API_KEY="${process.env.ANTHROPIC_API_KEY}"`] : []),
+        ];
+        // Create and start container
+        const createCmd = [
+            'docker run -d',
+            `--name ${containerName}`,
+            '--user node',
+            '-w /hq',
+            ...mounts,
+            ...envVars,
+            `--memory=${config.devcontainer.memory}`,
+            `--cpus=${config.devcontainer.cpus}`,
+            imageName,
+            'sleep infinity', // Keep container running
+        ].join(' ');
+        console.debug(`[runners:orchestrator-docker] Creating container: ${createCmd}`);
+        execSync(createCmd, { stdio: 'pipe' });
+        const containerId = getContainerId(containerName);
+        if (!containerId) {
+            return {
+                success: false,
+                error: 'Failed to get container ID after creation',
+            };
+        }
+        // Fix Docker socket permissions inside the container
+        // The socket is owned by root on the host; we need the node user to access it
+        try {
+            execSync(`docker exec --user root ${containerId} chmod 666 /var/run/docker.sock`, { stdio: 'pipe' });
+        }
+        catch {
+            console.debug('[runners:orchestrator-docker] Failed to fix Docker socket permissions (may already be accessible)');
+        }
+        // Copy Claude Code settings to container (for bypassing prompts)
+        if (executor === 'claude-code') {
+            try {
+                const hostClaudeJson = path.join(os.homedir(), '.claude.json');
+                let settings = {};
+                if (fs.existsSync(hostClaudeJson)) {
+                    try {
+                        settings = JSON.parse(fs.readFileSync(hostClaudeJson, 'utf-8'));
+                    }
+                    catch {
+                        // Use empty settings
+                    }
+                }
+                if (config.permissionMode === 'danger') {
+                    settings.bypassPermissionsModeAccepted = true;
+                }
+                settings.numStartups = settings.numStartups || 1;
+                settings.hasCompletedOnboarding = true;
+                settings.theme = settings.theme || 'dark';
+                if (!settings.tipsHistory || typeof settings.tipsHistory !== 'object') {
+                    settings.tipsHistory = {};
+                }
+                const tips = settings.tipsHistory;
+                tips['new-user-warmup'] = tips['new-user-warmup'] || 1;
+                settings.effortCalloutDismissed = true;
+                if (!settings.projects || typeof settings.projects !== 'object') {
+                    settings.projects = {};
+                }
+                const projects = settings.projects;
+                for (const projectPath of ['/hq', '/']) {
+                    if (!projects[projectPath])
+                        projects[projectPath] = {};
+                    projects[projectPath].hasTrustDialogAccepted = true;
+                    projects[projectPath].hasCompletedProjectOnboarding = true;
+                }
+                execSync(`docker exec -i ${containerId} bash -c 'cat > /home/node/.claude.json'`, { input: JSON.stringify(settings), stdio: ['pipe', 'pipe', 'pipe'] });
+                const claudeSettings = JSON.stringify({ skipDangerousModePermissionPrompt: true });
+                execSync(`docker exec -i ${containerId} bash -c 'mkdir -p /home/node/.claude && cat > /home/node/.claude/settings.json'`, { input: claudeSettings, stdio: ['pipe', 'pipe', 'pipe'] });
+            }
+            catch (error) {
+                console.debug('[runners:orchestrator-docker] Failed to copy Claude settings:', error);
+            }
+        }
+        // Build the prompt and write to temp file inside container
+        const prompt = buildPrompt(context);
+        const promptPath = `/tmp/orchestrator-prompt-${Date.now()}.txt`;
+        try {
+            execSync(`docker exec -i ${containerId} bash -c 'cat > ${promptPath}'`, { input: prompt, stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch {
+            return {
+                success: false,
+                error: 'Failed to write prompt to container',
+            };
+        }
+        // Build executor command
+        const skipPermissions = config.permissionMode === 'danger';
+        const permissionsFlag = skipPermissions ? '--dangerously-skip-permissions ' : '';
+        const effortFlag = skipPermissions ? '--effort high ' : '';
+        const executorCmd = executor === 'claude-code'
+            ? `claude ${permissionsFlag}${effortFlag}"$(cat ${promptPath})"`
+            : `claude ${permissionsFlag}${effortFlag}"$(cat ${promptPath})"`;
+        // Build tmux session name (reuses the same name as host tmux for consistency)
+        const tmuxSessionName = options?.sessionName || containerName;
+        // Create tmux session inside container with the executor command
+        const tmuxCmd = `tmux new-session -d -s "${tmuxSessionName}" -n "${tmuxSessionName}" bash -c '(unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT; cd /hq && ${executorCmd}); echo ""; echo "Orchestrator complete. Press Enter to close."; exec bash'`;
+        try {
+            execSync(`docker exec ${containerId} bash -c '${tmuxCmd.replace(/'/g, "'\\''")}'`, { stdio: 'pipe' });
+        }
+        catch (tmuxError) {
+            // Fallback: try simpler command without subshell
+            console.debug('[runners:orchestrator-docker] tmux creation failed, trying simpler approach:', tmuxError);
+            try {
+                // Write a script inside the container
+                const scriptContent = `#!/bin/bash
+cd /hq
+unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT
+${executor === 'claude-code' ? `claude ${permissionsFlag}${effortFlag}"$(cat ${promptPath})"` : `claude "$(cat ${promptPath})"`}
+echo ""
+echo "Orchestrator complete. Press Enter to close."
+exec bash
+`;
+                execSync(`docker exec -i ${containerId} bash -c 'cat > /tmp/orchestrator-start.sh && chmod +x /tmp/orchestrator-start.sh'`, { input: scriptContent, stdio: ['pipe', 'pipe', 'pipe'] });
+                execSync(`docker exec ${containerId} tmux new-session -d -s "${tmuxSessionName}" /tmp/orchestrator-start.sh`, { stdio: 'pipe' });
+            }
+            catch (fallbackError) {
+                return {
+                    success: false,
+                    error: `Failed to create tmux session in container: ${fallbackError instanceof Error ? fallbackError.message : fallbackError}`,
+                };
+            }
+        }
+        // Handle display mode
+        if (displayMode === 'foreground') {
+            // Attach to tmux inside the container in current terminal
+            try {
+                const child = spawn('docker', ['exec', '-it', containerId, 'tmux', 'attach', '-t', tmuxSessionName], {
+                    stdio: 'inherit',
+                });
+                await new Promise((resolve) => {
+                    child.on('close', () => resolve());
+                });
+            }
+            catch {
+                // User detached - that's fine
+            }
+        }
+        else if (displayMode === 'terminal' && process.platform === 'darwin') {
+            // Open a new terminal tab that attaches to the container's tmux
+            const baseDir = path.join(hqPath, '.proletariat', 'scripts');
+            fs.mkdirSync(baseDir, { recursive: true });
+            const scriptPath = path.join(baseDir, `orch-docker-attach-${Date.now()}.sh`);
+            const scriptContent = `#!/bin/bash
+echo -ne "\\033]0;Orchestrator (Docker)\\007"
+echo -ne "\\033]1;Orchestrator (Docker)\\007"
+docker exec -it ${containerId} tmux attach -t "${tmuxSessionName}"
+rm -f "${scriptPath}"
+exec $SHELL
+`;
+            fs.writeFileSync(scriptPath, scriptContent, { mode: 0o755 });
+            const terminalApp = config.terminal.app;
+            try {
+                switch (terminalApp) {
+                    case 'iTerm':
+                        execSync(`osascript -e '
+              tell application "iTerm"
+                activate
+                tell current window
+                  set newTab to (create tab with default profile)
+                  tell current session of newTab
+                    set name to "Orchestrator (Docker)"
+                    write text "${scriptPath}"
+                  end tell
+                end tell
+              end tell
+            '`);
+                        break;
+                    case 'Ghostty':
+                        execSync(`osascript -e '
+              tell application "Ghostty"
+                activate
+              end tell
+              tell application "System Events"
+                tell process "Ghostty"
+                  keystroke "t" using command down
+                  delay 0.3
+                  keystroke "${scriptPath}"
+                  keystroke return
+                end tell
+              end tell
+            '`);
+                        break;
+                    default:
+                        execSync(`osascript -e '
+              tell application "Terminal"
+                activate
+                tell application "System Events"
+                  tell process "Terminal"
+                    keystroke "t" using command down
+                  end tell
+                end tell
+                delay 0.3
+                do script "${scriptPath}" in front window
+              end tell
+            '`);
+                        break;
+                }
+            }
+            catch {
+                console.debug('[runners:orchestrator-docker] Failed to open terminal tab, running in background');
+            }
+        }
+        // 'background' display mode: container is already running, nothing more to do
+        return {
+            success: true,
+            containerId,
+            sessionId: tmuxSessionName,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to start orchestrator in Docker',
+        };
+    }
+}
+// =============================================================================
 // VM Runner
 // =============================================================================
 export async function runVm(context, executor, config, host) {