@proletariat/cli 0.3.57 → 0.3.59

package/dist/lib/execution/runners.js

@@ -2,17 +2,18 @@
 /**
  * Execution Runners
  *
- * Implementations for each execution environment (devcontainer, host, docker, vm).
+ * Implementations for each execution environment (host, sandbox, devcontainer, docker, cloud).
  */
 import { spawn, execSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
 import { fileURLToPath } from 'node:url';
-import { DEFAULT_EXECUTION_CONFIG, } from './types.js';
+import { DEFAULT_EXECUTION_CONFIG, normalizeEnvironment, } from './types.js';
 import { getSetTitleCommands } from '../terminal.js';
 import { readDevcontainerJson, generateOrchestratorDockerfile } from './devcontainer.js';
 import { getCodexCommand, resolveCodexExecutionContext, validateCodexMode } from './codex-adapter.js';
+import { resolveToolsForSpawn } from '../tool-registry/index.js';
 // =============================================================================
 // Terminal Title Helpers
 // =============================================================================
@@ -380,14 +381,84 @@ export function checkExecutorInContainer(executor, containerId) {
  * Run executor preflight checks for the target environment.
  */
 export function runExecutorPreflight(environment, executor, options) {
-    if (environment === 'host') {
+    const env = normalizeEnvironment(environment);
+    if (env === 'host' || env === 'sandbox') {
         return checkExecutorOnHost(executor);
     }
-    if (environment === 'devcontainer' && options?.containerId) {
+    if (env === 'devcontainer' && options?.containerId) {
         return checkExecutorInContainer(executor, options.containerId);
     }
     return { ok: true };
 }
+const INTEGRATION_COMMANDS = [
+    {
+        provider: 'asana',
+        displayName: 'Asana',
+        commands: [
+            'prlt asana connect — authenticate with Asana',
+            'prlt asana sync --ticket TKT-XXX --create-missing --project <gid> — sync a PMO ticket to Asana',
+            'prlt asana import — import Asana tasks into PMO',
+        ],
+    },
+    {
+        provider: 'linear',
+        displayName: 'Linear',
+        commands: [
+            'prlt linear connect — authenticate with Linear',
+            'prlt linear sync --ticket TKT-XXX --create-missing — sync a PMO ticket to Linear',
+            'prlt linear import — import Linear issues into PMO',
+        ],
+    },
+    {
+        provider: 'jira',
+        displayName: 'Jira',
+        commands: [
+            'prlt jira connect — authenticate with Jira',
+            'prlt jira sync --ticket TKT-XXX --create-missing — sync a PMO ticket to Jira',
+            'prlt jira import — import Jira issues into PMO',
+        ],
+    },
+    {
+        provider: 'shortcut',
+        displayName: 'Shortcut',
+        commands: [
+            'prlt shortcut connect — authenticate with Shortcut',
+            'prlt shortcut sync --ticket TKT-XXX --create-missing — sync a PMO ticket to Shortcut',
+            'prlt shortcut import — import Shortcut stories into PMO',
+        ],
+    },
+    {
+        provider: 'monday',
+        displayName: 'Monday.com',
+        commands: [
+            'prlt monday connect — authenticate with Monday.com',
+            'prlt monday sync --ticket TKT-XXX --create-missing — sync a PMO ticket to Monday.com',
+        ],
+    },
+];
+/**
+ * Build the integration commands section for agent prompts.
+ * Only includes integrations that are actually connected/configured.
+ * Returns empty string if no integrations are connected.
+ */
+function buildIntegrationCommandsSection(connectedIntegrations) {
+    if (!connectedIntegrations || connectedIntegrations.length === 0)
+        return '';
+    const connected = INTEGRATION_COMMANDS.filter(ic => connectedIntegrations.includes(ic.provider));
+    if (connected.length === 0)
+        return '';
+    let section = `## Integration Commands\n\n`;
+    section += `The following external integrations are connected. Use these prlt commands to interact with them.\n\n`;
+    for (const integration of connected) {
+        section += `### ${integration.displayName}\n`;
+        for (const cmd of integration.commands) {
+            section += `- \`${cmd.split(' — ')[0]}\` — ${cmd.split(' — ')[1] || ''}\n`;
+        }
+        section += '\n';
+    }
+    section += `**ANTI-PATTERN:** Never use curl, raw API calls, or shell scripts to interact with external services (Asana, Linear, Jira, Shortcut, Monday.com, etc.). Always use the corresponding \`prlt\` commands.\n\n`;
+    return section;
+}
 const ORCHESTRATOR_COMMAND_REGISTRY = [
     {
         title: 'Agent Lifecycle',
@@ -486,6 +557,18 @@ function buildOrchestratorAntiPatterns() {
  */
 function buildOrchestratorBody(hqName, context) {
     let prompt = '';
+    // Dynamic workspace context
+    const prltVersion = getHostPrltVersion();
+    prompt += `## Environment\n`;
+    if (prltVersion) {
+        prompt += `- **prlt version**: ${prltVersion}\n`;
+    }
+    prompt += `- **Available executors**: claude-code, codex\n`;
+    prompt += `- **Agent worktrees**: \`agents/temp/<agent-name>/<repo>\` — each agent gets an isolated git worktree\n`;
+    if (context.hqPath) {
+        prompt += `- **HQ path**: \`${context.hqPath}\`\n`;
+    }
+    prompt += `\n`;
     // Runtime declaration
     prompt += `## prlt Is Your Orchestration Runtime\n\n`;
     prompt += `prlt is your orchestration runtime. NEVER use raw docker exec, tmux send-keys, or direct container access. `;
@@ -494,10 +577,12 @@ function buildOrchestratorBody(hqName, context) {
     prompt += `health monitoring, and creates orphaned processes.\n\n`;
     // Role
     prompt += `## Your Role\n`;
-    prompt += `- Plan and prioritize work across the board\n`;
+    prompt += `- Assess the current state of the board, running agents, and open PRs\n`;
+    prompt += `- Plan and prioritize work — decide what to tackle next and in what order\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 += `- Monitor agent progress via sessions and review completed work\n`;
+    prompt += `- Review and merge completed PRs via \`gh pr merge --squash\`\n`;
+    prompt += `- Coordinate parallel agents — handle rebases after merges\n`;
     prompt += `- Never write code or make changes to source files yourself\n\n`;
     // Command reference (dynamically generated)
     prompt += `## Command Reference\n\n`;
@@ -511,11 +596,20 @@ function buildOrchestratorBody(hqName, context) {
     prompt += `- Fix: \`--action review-fix\`\n\n`;
     // Anti-patterns (dynamically generated)
     prompt += buildOrchestratorAntiPatterns();
+    // Integration commands (only for connected integrations)
+    prompt += buildIntegrationCommandsSection(context.connectedIntegrations);
     // Workflow
     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`;
+    // Tool registry (TKT-083): inject available tools into orchestrator prompt
+    if (context.hqPath) {
+        const toolsResult = resolveToolsForSpawn(context.hqPath, context.toolPolicy, path.join(context.hqPath, '.proletariat', 'scripts'));
+        if (toolsResult.promptSection) {
+            prompt += toolsResult.promptSection;
+        }
+    }
     // Load .orchestrator-context.md from HQ root if it exists
     if (context.hqPath) {
         const contextFilePath = path.join(context.hqPath, '.orchestrator-context.md');
@@ -540,9 +634,12 @@ function buildOrchestratorBody(hqName, context) {
  */
 export function buildOrchestratorSystemPrompt(context) {
     const hqName = context.hqName || 'workspace';
-    let prompt = `You are an orchestrator for the **${hqName}** project. `;
-    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`;
+    let prompt = `# Orchestrator: ${hqName}\n\n`;
+    prompt += `You are the orchestrator for the **${hqName}** headquarters — a technical project manager driving software delivery through delegated AI agents.\n\n`;
+    prompt += `**prlt** is an AI agent orchestration CLI. It manages software development by coordinating autonomous coding agents that work in isolated git worktrees. `;
+    prompt += `Your workspace (HQ) contains a PMO board for tracking tickets, agent worktrees under \`agents/temp/\`, and repo connections. `;
+    prompt += `Agents are spawned to implement, review, and fix code — you never write code yourself. `;
+    prompt += `Your job is to assess the state of the project, plan and prioritize work, delegate to agents, monitor their progress, review results, and merge completed PRs.\n\n`;
     prompt += buildOrchestratorBody(hqName, context);
     return prompt;
 }
@@ -552,7 +649,10 @@ function buildOrchestratorPrompt(context) {
     // 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 += `You are the orchestrator for the **${hqName}** headquarters — a technical project manager driving software delivery through delegated AI agents.\n\n`;
+    prompt += `**prlt** is an AI agent orchestration CLI. It manages software development by coordinating autonomous coding agents that work in isolated git worktrees. `;
+    prompt += `Your workspace (HQ) contains a PMO board for tracking tickets, agent worktrees under \`agents/temp/\`, and repo connections. `;
+    prompt += `Agents are spawned to implement, review, and fix code — you never write code yourself.\n\n`;
     prompt += buildOrchestratorBody(hqName, context);
     // Include user's custom prompt or action content
     if (context.actionPrompt) {
@@ -591,9 +691,6 @@ function buildPrompt(context) {
     if (context.epicTitle) {
         prompt += `**Epic:** ${context.epicTitle}\n`;
     }
-    if (context.specId) {
-        prompt += `**Spec:** ${context.specId}${context.specTitle ? ` - ${context.specTitle}` : ''}\n`;
-    }
     if (context.ticketDescription) {
         prompt += `\n## Description\n\n${context.ticketDescription}\n`;
     }
@@ -606,10 +703,22 @@ function buildPrompt(context) {
     }
     // Note: Branch setup (fetch + checkout/create) is now handled programmatically
     // in work/start.ts before the agent spawns, so no prompt instructions needed
+    // Integration commands (only for connected integrations)
+    const integrationSection = buildIntegrationCommandsSection(context.connectedIntegrations);
+    if (integrationSection) {
+        prompt += `\n${integrationSection}`;
+    }
     // Additional instructions from --message flag (appended to any action)
     if (context.customMessage) {
         prompt += `\n## Additional Instructions\n\n${context.customMessage}\n`;
     }
+    // Tool registry (TKT-083): inject available tools into agent prompt
+    if (context.hqPath) {
+        const toolsResult = resolveToolsForSpawn(context.hqPath, context.toolPolicy, path.join(context.hqPath, '.proletariat', 'scripts'));
+        if (toolsResult.promptSection) {
+            prompt += `\n${toolsResult.promptSection}`;
+        }
+    }
     // END HOOK - Action-specific completion instructions
     prompt += `\n---\n\n## When Complete\n\n`;
     // For revisions, use the revision-specific end prompt
@@ -711,16 +820,27 @@ export async function runHost(context, executor, config, displayMode = 'terminal
         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.';
+            || 'Assess the current state of the project:\n'
+                + '1. Check the board: `prlt board view` — what tickets are in progress, blocked, or ready?\n'
+                + '2. List running agents: `prlt session list` — who is working on what? Any stale sessions?\n'
+                + '3. Check open PRs: `gh pr list` — any PRs ready for review or merge?\n'
+                + '4. Summarize what needs attention and recommend next actions.';
         fs.writeFileSync(promptPath, userMessage, { mode: 0o644 });
     }
     else {
         // Write full prompt (includes role context for non-Claude executors)
         fs.writeFileSync(promptPath, prompt, { mode: 0o644 });
     }
+    // Tool registry (TKT-083): generate MCP config for Claude Code
+    let mcpConfigPath = null;
+    if (context.hqPath && isClaudeExecutor(executor)) {
+        const toolsResult = resolveToolsForSpawn(context.hqPath, context.toolPolicy, baseDir);
+        mcpConfigPath = toolsResult.mcpConfigPath;
+    }
     // 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()
+    // For Codex, we use the codex adapter for deterministic command building (TKT-080)
+    // For other executors, we use the command as-is from getExecutorCommand()
     let executorInvocation;
     if (isClaudeExecutor(executor)) {
         // Build flags based on config - Claude-specific flags
@@ -731,13 +851,28 @@ export async function runHost(context, executor, config, displayMode = 'terminal
         const effortFlag = skipPermissions ? '--effort high ' : '';
         // 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")"`;
+        // TKT-053: Disable plan mode for background agents — prevents silent stalls
+        // when there's no user to approve the plan mode transition
+        const disallowPlanFlag = displayMode === 'background' ? '--disallowedTools EnterPlanMode ' : '';
+        // Tool registry (TKT-083): pass MCP config to Claude Code via --mcp-config flag
+        const mcpConfigFlag = mcpConfigPath ? `--mcp-config "${mcpConfigPath}" ` : '';
+        executorInvocation = `${cmd} ${permissionsFlag}${effortFlag}${printFlag}${disallowPlanFlag}${systemPromptFlag}${mcpConfigFlag}"$(cat "$PROMPT_PATH")"`;
+    }
+    else if (executor === 'codex') {
+        // TKT-080: Use Codex adapter for deterministic command building.
+        // Uses PLACEHOLDER pattern for reliable prompt replacement (same as devcontainer runner).
+        const codexPermission = config.permissionMode;
+        const codexContext = resolveCodexExecutionContext(displayMode, config.outputMode);
+        const codexResult = getCodexCommand('PLACEHOLDER', codexPermission, codexContext);
+        const argsStr = codexResult.args.map(a => a === 'PLACEHOLDER' ? '"$(cat "$PROMPT_PATH")"' : a).join(' ');
+        executorInvocation = `${codexResult.cmd} ${argsStr}`;
     }
     else {
-        // Non-Claude executors: build command from getExecutorCommand() args
-        // Replace the prompt in args with a file read to avoid shell escaping
-        const argsWithFile = args.map(a => a === prompt ? '"$(cat "$PROMPT_PATH")"' : `"${a}"`);
-        executorInvocation = `${cmd} ${argsWithFile.join(' ')}`;
+        // Non-Claude, non-Codex executors: build command from getExecutorCommand() args
+        // Use PLACEHOLDER for reliable prompt replacement instead of fragile string comparison
+        const { cmd: execCmd, args: execArgs } = getExecutorCommand(executor, 'PLACEHOLDER', skipPermissions);
+        const argsWithFile = execArgs.map(a => a === 'PLACEHOLDER' ? '"$(cat "$PROMPT_PATH")"' : `"${a}"`);
+        executorInvocation = `${execCmd} ${argsWithFile.join(' ')}`;
     }
     // Build script that runs executor and keeps shell open after completion
     const setTitleCmds = getSetTitleCommands(windowTitle);
@@ -755,16 +890,25 @@ echo ""
 echo "✅ Agent work complete. Press Enter to close or run more commands."
 exec $SHELL
 `;
+    // Wrap with srt sandbox if running in sandbox environment
+    let finalInvocation = executorInvocation;
+    if (context.executionEnvironment === 'sandbox') {
+        // Build the srt wrapper command
+        // The inner command is the executor invocation that reads from PROMPT_PATH
+        const srtCmd = buildSrtCommand(`bash -c '${executorInvocation.replace(/'/g, "'\\''")}'`, context, config);
+        finalInvocation = srtCmd;
+    }
     const scriptContent = `#!/bin/bash
 # Auto-generated script for ticket ${context.ticketId}
 SCRIPT_PATH="${scriptPath}"
 PROMPT_PATH="${promptPath}"${systemPromptVar}
 ${setTitleCmds}
 echo "🚀 Starting: ${sessionName}"
+${context.executionEnvironment === 'sandbox' ? 'echo "🔒 Running in srt sandbox (filesystem + network isolation)"' : ''}
 echo ""
 cd "${context.worktreePath}"
 # Run executor in subshell with CLAUDECODE unset (prevents nested session error)
-(unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT; ${executorInvocation})
+(unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT; ${finalInvocation})
 
 # Clean up script and prompt files
 rm -f "$SCRIPT_PATH" "$PROMPT_PATH"${systemPromptPath ? ' "$SYSTEM_PROMPT_PATH"' : ''}
@@ -1049,30 +1193,71 @@ export function getGitHubToken() {
 export function isGitHubTokenAvailable() {
     return getGitHubToken() !== null;
 }
-// =============================================================================
-// Docker Status Check
-// =============================================================================
 /**
- * Check if Docker daemon is running.
- * Returns true if Docker is available and responsive.
- * Uses retry logic to handle slow Docker Desktop startup.
+ * Check Docker daemon health with fast detection (TKT-081).
+ *
+ * Uses `docker ps` with a 5-second timeout to quickly detect:
+ * - Docker not installed
+ * - Docker installed but daemon unresponsive (stuck on license, initializing, 500 errors)
+ * - Docker ready
+ *
+ * Total worst-case time: ~5 seconds (single attempt with timeout).
  */
-export function isDockerRunning() {
-    const maxRetries = 3;
-    const timeout = 10000; // 10 seconds
-    for (let attempt = 1; attempt <= maxRetries; attempt++) {
-        try {
-            execSync('docker info', { stdio: 'pipe', timeout });
-            return true;
+export function checkDockerDaemon() {
+    // First: is docker even installed?
+    try {
+        execSync('which docker', { stdio: 'pipe', timeout: 3000 });
+    }
+    catch {
+        return {
+            available: false,
+            reason: 'not-installed',
+            message: 'Docker is not installed.',
+        };
+    }
+    // Second: is the daemon responsive? Use `docker ps` — it's lightweight and
+    // fails fast when the daemon returns 500s or hangs on GUI prompts.
+    const timeout = 5000; // 5 seconds — enough for a healthy daemon, fast fail otherwise
+    try {
+        execSync('docker ps -q --no-trunc', { stdio: 'pipe', timeout });
+        return {
+            available: true,
+            reason: 'ready',
+            message: 'Docker daemon is ready.',
+        };
+    }
+    catch (error) {
+        // Parse the error to give actionable feedback
+        const stderr = error?.stderr?.toString() || '';
+        const isTimeout = error?.killed === true;
+        let message;
+        if (isTimeout) {
+            message = 'Docker daemon is not responding (timed out after 5s). Docker Desktop may be initializing or stuck — check for license/login prompts.';
         }
-        catch {
-            if (attempt === maxRetries) {
-                return false;
-            }
-            // Brief pause before retry
+        else if (stderr.includes('500') || stderr.includes('Internal Server Error')) {
+            message = 'Docker daemon is returning errors (500). Docker Desktop needs attention — check for license/login prompts.';
+        }
+        else if (stderr.includes('connect') || stderr.includes('Cannot connect') || stderr.includes('Is the docker daemon running')) {
+            message = 'Docker daemon is not running. Start Docker Desktop and try again.';
         }
+        else {
+            message = `Docker daemon is not ready: ${stderr.trim() || 'unknown error'}. Check Docker Desktop status.`;
+        }
+        return {
+            available: false,
+            reason: 'daemon-not-ready',
+            message,
+        };
     }
-    return false;
+}
+/**
+ * Check if Docker daemon is running.
+ * Returns true if Docker is available and responsive.
+ *
+ * For detailed diagnostics, use checkDockerDaemon() instead.
+ */
+export function isDockerRunning() {
+    return checkDockerDaemon().available;
 }
 /**
  * Check if the devcontainer CLI is installed.
@@ -1129,7 +1314,7 @@ function getImageName(agentName) {
  */
 export function containerExists(containerName) {
     try {
-        execSync(`docker container inspect ${containerName}`, { stdio: 'pipe' });
+        execSync(`docker container inspect ${containerName}`, { stdio: 'pipe', timeout: 5000 });
         return true;
     }
     catch {
@@ -1141,7 +1326,7 @@ export function containerExists(containerName) {
  */
 export function isContainerRunning(containerName) {
     try {
-        const status = execSync(`docker container inspect -f '{{.State.Running}}' ${containerName}`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const status = execSync(`docker container inspect -f '{{.State.Running}}' ${containerName}`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 5000 }).trim();
         return status === 'true';
     }
     catch {
@@ -1153,7 +1338,7 @@ export function isContainerRunning(containerName) {
  */
 export function getContainerId(containerName) {
     try {
-        const containerId = execSync(`docker container inspect -f '{{.Id}}' ${containerName}`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        const containerId = execSync(`docker container inspect -f '{{.Id}}' ${containerName}`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 5000 }).trim();
         return containerId ? containerId.substring(0, 12) : null;
     }
     catch {
@@ -1189,7 +1374,7 @@ function buildDockerImage(agentDir, imageName, buildArgs = {}) {
  */
 function imageExists(imageName) {
     try {
-        execSync(`docker image inspect ${imageName}`, { stdio: 'pipe' });
+        execSync(`docker image inspect ${imageName}`, { stdio: 'pipe', timeout: 5000 });
         return true;
     }
     catch {
@@ -1420,7 +1605,7 @@ function ensureDockerContainer(context, config, executor = 'claude-code') {
         // Container exists but is stopped - remove and recreate for fresh mounts
         console.debug(`[runners:docker] Removing stopped container ${containerName} to create fresh one`);
         try {
-            execSync(`docker rm -f ${containerName}`, { stdio: 'pipe' });
+            execSync(`docker rm -f ${containerName}`, { stdio: 'pipe', timeout: 10000 });
         }
         catch {
             // Ignore removal errors
@@ -1564,7 +1749,7 @@ function writePromptFile(context) {
  * Uses docker exec for direct container access.
  * Uses a prompt file to avoid shell escaping issues.
  */
-export function buildDevcontainerCommand(context, executor, promptFile, containerId, outputMode = 'interactive', permissionMode = 'safe', displayMode = 'terminal') {
+export function buildDevcontainerCommand(context, executor, promptFile, containerId, outputMode = 'interactive', permissionMode = 'safe', displayMode = 'terminal', mcpConfigFile) {
     // Calculate the relative path from agentDir to worktreePath for cd
     const relativePath = path.relative(context.agentDir, context.worktreePath);
     const cdCmd = relativePath ? `cd /workspace/${relativePath} && ` : '';
@@ -1582,7 +1767,11 @@ export function buildDevcontainerCommand(context, executor, promptFile, containe
         const permissionsFlag = skipPermissions ? '--dangerously-skip-permissions ' : '';
         // --effort high: skips the effort level prompt for automated agents (TKT-1134)
         const effortFlag = '--effort high ';
-        executorCmd = `claude ${bypassTrustFlag}${permissionsFlag}${effortFlag}${printFlag}"$(cat ${promptFile})"`;
+        // TKT-053: Disable plan mode for background agents — prevents silent stalls
+        const disallowPlanFlag = displayMode === 'background' ? '--disallowedTools EnterPlanMode ' : '';
+        // Tool registry (TKT-083): pass MCP config to Claude Code via --mcp-config flag
+        const mcpConfigFlag = mcpConfigFile ? `--mcp-config ${mcpConfigFile} ` : '';
+        executorCmd = `claude ${bypassTrustFlag}${permissionsFlag}${effortFlag}${printFlag}${disallowPlanFlag}${mcpConfigFlag}"$(cat ${promptFile})"`;
     }
     else if (executor === 'codex') {
         // Use Codex adapter for mode validation and deterministic command building.
@@ -1634,11 +1823,12 @@ export async function runDevcontainer(context, executor, config, displayMode = '
         };
     }
     try {
-        // Check if Docker is running
-        if (!isDockerRunning()) {
+        // Check if Docker is running (TKT-081: fast detection with diagnostic info)
+        const dockerStatus = checkDockerDaemon();
+        if (!dockerStatus.available) {
             return {
                 success: false,
-                error: 'Docker is not running. Please start Docker Desktop and try again.',
+                error: `Docker daemon is not available. ${dockerStatus.message}`,
             };
         }
         // Ensure GitHub token is available for git push operations
@@ -1672,6 +1862,16 @@ export async function runDevcontainer(context, executor, config, displayMode = '
         }
         // Write prompt to file in worktree (accessible by container)
         const { hostPath: promptHostPath, containerPath: promptFile } = writePromptFile(context);
+        // Tool registry (TKT-083): generate MCP config file for container
+        let mcpConfigContainerPath;
+        if (context.hqPath && isClaudeExecutor(executor)) {
+            const toolsResult = resolveToolsForSpawn(context.hqPath, context.toolPolicy, context.worktreePath);
+            if (toolsResult.mcpConfigPath) {
+                // Map host path to container path
+                const relativeMcp = path.relative(context.agentDir, toolsResult.mcpConfigPath);
+                mcpConfigContainerPath = `/workspace/${relativeMcp}`;
+            }
+        }
         // Inject fresh GitHub token into container (containers may be reused with stale/empty tokens)
         // This ensures git push works even if the container was created before token was available
         const githubToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
@@ -1688,7 +1888,7 @@ export async function runDevcontainer(context, executor, config, displayMode = '
         }
         // Build the docker exec command (just runs claude directly)
         // tmux session setup is handled by runDevcontainerInTmux, not buildDevcontainerCommand
-        const devcontainerCmd = buildDevcontainerCommand(context, executor, promptFile, containerId, config.outputMode, config.permissionMode, displayMode);
+        const devcontainerCmd = buildDevcontainerCommand(context, executor, promptFile, containerId, config.outputMode, config.permissionMode, displayMode, mcpConfigContainerPath);
         // Execute based on display mode
         // When sessionManager is 'tmux', always use tmux inside container for session persistence
         // (allows reattach via `prlt session attach` even for background mode)
@@ -2333,13 +2533,12 @@ export async function runDocker(context, executor, config) {
     const prompt = buildPrompt(context);
     const containerName = `work-${context.ticketId}-${Date.now()}`;
     try {
-        // Check if docker is available
-        execSync('which docker', { stdio: 'pipe' });
-        // Check if Docker is running
-        if (!isDockerRunning()) {
+        // Check if docker is available and daemon is responsive (TKT-081)
+        const dockerStatus = checkDockerDaemon();
+        if (!dockerStatus.available) {
             return {
                 success: false,
-                error: 'Docker is not running. Please start Docker Desktop and try again.',
+                error: `Docker daemon is not available. ${dockerStatus.message}`,
             };
         }
         // Build docker run command
@@ -2371,7 +2570,8 @@ export async function runDocker(context, executor, config) {
         // Non-Claude executors use their native command format from getExecutorCommand()
         dockerCmd += ` ${config.docker.image}`;
         if (isClaudeExecutor(executor)) {
-            dockerCmd += ` ${cmd} --print '${escapedPrompt}'`;
+            // TKT-053: Disable plan mode — Docker runner is always detached (no user to approve)
+            dockerCmd += ` ${cmd} --print --disallowedTools EnterPlanMode '${escapedPrompt}'`;
         }
         else {
             const argsStr = args.map(a => a === escapedPrompt ? `'${escapedPrompt}'` : a).join(' ');
@@ -2420,11 +2620,12 @@ export async function runOrchestratorInDocker(context, executor, config, options
     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()) {
+        // Check Docker is running (TKT-081: fast detection with diagnostic info)
+        const dockerStatus = checkDockerDaemon();
+        if (!dockerStatus.available) {
             return {
                 success: false,
-                error: 'Docker is not running. Please start Docker Desktop and try again.',
+                error: `Docker daemon is not available. ${dockerStatus.message}`,
             };
         }
         // Check if container already exists and is running
@@ -2584,8 +2785,10 @@ export async function runOrchestratorInDocker(context, executor, config, options
         const skipPermissions = config.permissionMode === 'danger';
         const permissionsFlag = skipPermissions ? '--dangerously-skip-permissions ' : '';
         const effortFlag = skipPermissions ? '--effort high ' : '';
+        // TKT-053: Disable plan mode for background agents — prevents silent stalls
+        const disallowPlanFlag = displayMode === 'background' ? '--disallowedTools EnterPlanMode ' : '';
         const executorCmd = executor === 'claude-code'
-            ? `claude ${permissionsFlag}${effortFlag}"$(cat ${promptPath})"`
+            ? `claude ${permissionsFlag}${effortFlag}${disallowPlanFlag}"$(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;
@@ -2602,7 +2805,7 @@ export async function runOrchestratorInDocker(context, executor, config, options
                 const scriptContent = `#!/bin/bash
 cd /hq
 unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT
-${executor === 'claude-code' ? `claude ${permissionsFlag}${effortFlag}"$(cat ${promptPath})"` : `claude "$(cat ${promptPath})"`}
+${executor === 'claude-code' ? `claude ${permissionsFlag}${effortFlag}${disallowPlanFlag}"$(cat ${promptPath})"` : `claude "$(cat ${promptPath})"`}
 echo ""
 echo "Orchestrator complete. Press Enter to close."
 exec bash
@@ -2712,19 +2915,125 @@ exec $SHELL
     }
 }
 // =============================================================================
-// VM Runner
+// Sandbox Utilities
+// =============================================================================
+/**
+ * Check if srt (sandbox-runtime) is installed on the host.
+ */
+export function isSrtInstalled() {
+    try {
+        execSync('which srt', { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the srt command with filesystem and network restrictions.
+ *
+ * Filesystem policy (read-restriction philosophy from claude-code-sandbox):
+ * - Read/write: agent worktree directory
+ * - Read-only: repo source (if different from worktree)
+ * - Read-only: additional configured read paths
+ * - Deny: home directory, system paths, other repos
+ *
+ * Network policy:
+ * - Allow: configured domains (GitHub, Anthropic API, npm registries, etc.)
+ * - Deny: everything else
+ */
+export function buildSrtCommand(innerCommand, context, config) {
+    const args = ['srt'];
+    // Filesystem: always allow read/write to agent worktree
+    args.push(`--fs-write=${context.worktreePath}`);
+    // Allow read/write to the agent directory (parent of worktree, contains .devcontainer etc.)
+    if (context.agentDir && context.agentDir !== context.worktreePath) {
+        args.push(`--fs-write=${context.agentDir}`);
+    }
+    // Allow read/write to HQ scripts directory (for temp script files)
+    if (context.hqPath) {
+        const scriptsDir = path.join(context.hqPath, '.proletariat', 'scripts');
+        args.push(`--fs-write=${scriptsDir}`);
+    }
+    // Allow read access to additional configured paths
+    for (const readPath of config.sandbox.allowReadPaths) {
+        args.push(`--fs-read=${readPath}`);
+    }
+    // Allow write access to additional configured paths
+    for (const writePath of config.sandbox.allowWritePaths) {
+        args.push(`--fs-write=${writePath}`);
+    }
+    // Allow read to temp directory (needed for script execution)
+    args.push(`--fs-write=${os.tmpdir()}`);
+    // Network: merge sandbox domains with firewall allowlist
+    const allDomains = new Set([
+        ...config.sandbox.networkDomains,
+        ...config.firewall.allowlistDomains,
+    ]);
+    for (const domain of allDomains) {
+        args.push(`--net-allow=${domain}`);
+    }
+    // The inner command to execute inside the sandbox
+    args.push('--');
+    args.push(innerCommand);
+    return args.join(' ');
+}
+// =============================================================================
+// Sandbox Runner - srt-based sandbox on host
+// =============================================================================
+/**
+ * Run command in an srt sandbox on the host machine.
+ * Uses the same tmux session approach as the host runner, but wraps the
+ * executor command with srt for filesystem and network isolation.
+ *
+ * Falls back to host runner with warning if srt is not installed.
+ */
+export async function runSandbox(context, executor, config, displayMode = 'terminal') {
+    // Check if srt is installed
+    if (!isSrtInstalled()) {
+        if (config.sandbox.fallbackToHost) {
+            // Log warning via stderr (will be visible in terminal)
+            process.stderr.write('\x1b[33m⚠️  srt (sandbox-runtime) not installed. Falling back to host execution.\n' +
+                '   Install srt for filesystem + network isolation: https://github.com/anthropic-experimental/sandbox-runtime\x1b[0m\n');
+            // Fall back to host runner
+            return runHost(context, executor, config, displayMode);
+        }
+        return {
+            success: false,
+            error: 'srt (sandbox-runtime) is not installed.\n\n' +
+                'Install it from: https://github.com/anthropic-experimental/sandbox-runtime\n' +
+                'Or set sandbox.fallbackToHost to true in execution config to fall back to host.',
+        };
+    }
+    // Delegate to host runner — the sandbox wrapping happens at the script level
+    // We set a flag on context so the host runner knows to wrap with srt
+    const sandboxContext = {
+        ...context,
+        executionEnvironment: 'sandbox',
+    };
+    return runHost(sandboxContext, executor, config, displayMode);
+}
+// =============================================================================
+// Cloud Runner (was VM Runner)
 // =============================================================================
-export async function runVm(context, executor, config, host) {
-    const targetHost = host || config.vm.defaultHost;
+/**
+ * Run command on a remote machine (cloud) via SSH.
+ * Formerly 'runVm' — renamed to reflect the simplified environment hierarchy.
+ * Uses cloud config with fallback to legacy vm config for backwards compatibility.
+ */
+export async function runCloud(context, executor, config, host) {
+    // Use cloud config, fall back to vm config for backwards compatibility
+    const cloudConfig = config.cloud?.defaultHost ? config.cloud : config.vm;
+    const targetHost = host || cloudConfig.defaultHost;
     if (!targetHost) {
         return {
             success: false,
-            error: 'No VM host specified. Use --host or configure execution.vm.default_host',
+            error: 'No cloud host specified. Use --host or configure execution.cloud.default_host',
         };
     }
     const prompt = buildPrompt(context);
-    const user = config.vm.user;
-    const keyPath = config.vm.keyPath;
+    const user = cloudConfig.user;
+    const keyPath = cloudConfig.keyPath;
     const remoteWorkspace = `/workspace/${context.agentName}`;
     try {
         // Build SSH options
@@ -2733,7 +3042,7 @@ export async function runVm(context, executor, config, host) {
             sshOpts = `-i "${keyPath}"`;
         }
         // Sync worktree to remote
-        if (config.vm.syncMethod === 'rsync') {
+        if (cloudConfig.syncMethod === 'rsync') {
             let rsyncCmd = `rsync -avz`;
             if (keyPath) {
                 rsyncCmd += ` -e "ssh -i ${keyPath}"`;
@@ -2747,7 +3056,7 @@ export async function runVm(context, executor, config, host) {
             const gitPullCmd = `cd ${remoteWorkspace} && git fetch && git checkout ${context.branch}`;
             execSync(`ssh ${sshOpts} ${user}@${targetHost} "${gitPullCmd}"`, { stdio: 'pipe' });
         }
-        // Validate Codex mode: VM runner is always non-tty (SSH + nohup)
+        // Validate Codex mode: Cloud runner is always non-tty (SSH + nohup)
         if (executor === 'codex') {
             const codexPermission = config.permissionMode;
             const modeError = validateCodexMode(codexPermission, 'non-tty');
@@ -2761,7 +3070,8 @@ export async function runVm(context, executor, config, host) {
         // Build the remote command based on executor type
         let remoteCmd;
         if (isClaudeExecutor(executor)) {
-            remoteCmd = `cd ${remoteWorkspace} && ${executorCmd} --print '${escapedPrompt}'`;
+            // TKT-053: Disable plan mode — VM runner is always nohup (no user to approve)
+            remoteCmd = `cd ${remoteWorkspace} && ${executorCmd} --print --disallowedTools EnterPlanMode '${escapedPrompt}'`;
         }
         else {
             const argsStr = executorArgs.map(a => a === escapedPrompt ? `'${escapedPrompt}'` : a).join(' ');
@@ -2778,29 +3088,38 @@ export async function runVm(context, executor, config, host) {
     catch (error) {
         return {
             success: false,
-            error: error instanceof Error ? error.message : 'Failed to execute on VM',
+            error: error instanceof Error ? error.message : 'Failed to execute on cloud',
         };
     }
 }
+/** @deprecated Use runCloud instead */
+export const runVm = runCloud;
 // =============================================================================
 // Runner Dispatcher
 // =============================================================================
 export async function runExecution(environment, context, executor, config = DEFAULT_EXECUTION_CONFIG, options) {
-    // Ensure tmux server has keychain access for OAuth (host only)
+    // Ensure context knows its execution environment
+    if (!context.executionEnvironment) {
+        context.executionEnvironment = environment;
+    }
+    // Normalize environment (maps 'vm' -> 'cloud')
+    const normalizedEnv = normalizeEnvironment(environment);
+    // Ensure tmux server has keychain access for OAuth (host/sandbox only)
     // Docker uses claude-credentials volume, devcontainer runs inside container
-    if (environment === 'host') {
+    if (normalizedEnv === 'host' || normalizedEnv === 'sandbox') {
         await ensureTmuxServerHasKeychainAccess();
     }
-    switch (environment) {
+    switch (normalizedEnv) {
         case 'devcontainer':
             return runDevcontainer(context, executor, config, options?.displayMode, options?.sessionManager);
         case 'host':
-            // Host uses tmux for session persistence (same as devcontainer)
             return runHost(context, executor, config, options?.displayMode);
+        case 'sandbox':
+            return runSandbox(context, executor, config, options?.displayMode);
         case 'docker':
             return runDocker(context, executor, config);
-        case 'vm':
-            return runVm(context, executor, config, options?.host);
+        case 'cloud':
+            return runCloud(context, executor, config, options?.host);
         default:
             return { success: false, error: `Unknown execution environment: ${environment}` };
     }