@proletariat/cli 0.3.56 → 0.3.58

package/dist/lib/execution/runners.js

@@ -8,6 +8,7 @@ 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 { getSetTitleCommands } from '../terminal.js';
 import { readDevcontainerJson, generateOrchestratorDockerfile } from './devcontainer.js';
@@ -387,35 +388,201 @@ export function runExecutorPreflight(environment, executor, options) {
     }
     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 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.
+ * Build the integration commands section for agent prompts.
+ * Only includes integrations that are actually connected/configured.
+ * Returns empty string if no integrations are connected.
  */
-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`;
+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',
+        commands: [
+            { cmd: 'prlt work start <ticket> --ephemeral --skip-permissions --create-pr --display background --action implement --run-on-host --yes', desc: 'Spawn an agent for a ticket', checkPath: 'work/start' },
+            { cmd: 'prlt session list', desc: 'List running sessions', checkPath: 'session/list' },
+            { cmd: 'prlt session inspect <agent>', desc: 'Inspect session details', checkPath: 'session/inspect' },
+            { cmd: 'prlt session poke <agent> \'message\'', desc: 'Send message to agent', checkPath: 'session/poke' },
+            { cmd: 'prlt session peek <agent> --lines 200', desc: 'Read agent output', checkPath: 'session/peek' },
+            { cmd: 'prlt session health', desc: 'Check health of all sessions', checkPath: 'session/health' },
+            { cmd: 'prlt session restart <agent>', desc: 'Restart a stuck agent', checkPath: 'session/restart' },
+            { cmd: 'prlt session exec <agent> -- git status', desc: 'Run command in agent context', checkPath: 'session/exec' },
+            { cmd: 'prlt session prune', desc: 'Clean up dead sessions', checkPath: 'session/prune' },
+        ],
+    },
+    {
+        title: 'Board Management',
+        commands: [
+            { cmd: 'prlt board view', desc: 'View the board', checkPath: 'board/view' },
+            { cmd: 'prlt ticket list', desc: 'List tickets', checkPath: 'ticket/list' },
+            { cmd: 'prlt ticket show <id>', desc: 'Show ticket details', checkPath: 'ticket/show' },
+            { cmd: 'prlt ticket create --title \'x\' --description \'y\'', desc: 'Create a ticket', checkPath: 'ticket/create' },
+            { cmd: 'prlt ticket edit <id> --title \'...\' --add-ac \'...\'', desc: 'Edit ticket fields', checkPath: 'ticket/edit' },
+        ],
+    },
+    {
+        title: 'PR Workflow',
+        commands: [
+            { cmd: 'gh pr list', desc: 'List open PRs' },
+            { cmd: 'gh pr view <num>', desc: 'View PR details' },
+            { cmd: 'gh pr checks <num>', desc: 'Check CI status' },
+            { cmd: 'gh pr merge <num> --squash', desc: 'Merge PR (squash only)' },
+        ],
+    },
+];
+const ORCHESTRATOR_ANTI_PATTERNS = [
+    { bad: 'docker exec <container> ...', good: 'prlt session exec', checkPath: 'session/exec' },
+    { bad: 'tmux send-keys ...', good: 'prlt session poke', checkPath: 'session/poke' },
+    { bad: 'tmux capture-pane ...', good: 'prlt session peek', checkPath: 'session/peek' },
+    { bad: 'Direct git operations on agent worktrees', good: 'prlt session exec', checkPath: 'session/exec' },
+];
+/**
+ * Resolve the commands directory for dynamic command availability checks.
+ * Looks for compiled command files under dist/commands/.
+ */
+let _commandsDir = null;
+function getCommandsDir() {
+    if (_commandsDir === null) {
+        const currentFile = fileURLToPath(import.meta.url);
+        // From dist/lib/execution/runners.js → dist/commands/
+        _commandsDir = path.resolve(path.dirname(currentFile), '..', '..', 'commands');
+    }
+    return _commandsDir;
+}
+function isCommandAvailable(checkPath) {
+    const dir = getCommandsDir();
+    // Check for compiled .js file or directory (which would contain index.js)
+    return fs.existsSync(path.join(dir, `${checkPath}.js`)) || fs.existsSync(path.join(dir, checkPath));
+}
+/**
+ * Build the dynamic command reference section for the orchestrator prompt.
+ * Only includes commands that are actually available in this build.
+ */
+function buildOrchestratorCommandReference() {
+    let ref = '';
+    for (const category of ORCHESTRATOR_COMMAND_REGISTRY) {
+        const available = category.commands.filter(c => !c.checkPath || isCommandAvailable(c.checkPath));
+        if (available.length === 0)
+            continue;
+        ref += `### ${category.title}\n`;
+        for (const cmd of available) {
+            ref += `- \`${cmd.cmd}\` — ${cmd.desc}\n`;
+        }
+        ref += '\n';
+    }
+    return ref;
+}
+/**
+ * Build the anti-patterns section for the orchestrator prompt.
+ * Only includes anti-patterns where the prlt replacement is available.
+ */
+function buildOrchestratorAntiPatterns() {
+    const available = ORCHESTRATOR_ANTI_PATTERNS.filter(ap => !ap.checkPath || isCommandAvailable(ap.checkPath));
+    if (available.length === 0)
+        return '';
+    let section = `## Anti-Patterns — NEVER DO\n\n`;
+    for (const ap of available) {
+        section += `- \`${ap.bad}\` → use \`${ap.good}\` instead\n`;
+    }
+    section += `\n`;
+    return section;
+}
+/**
+ * Build the shared orchestrator prompt body (role, runtime, commands, anti-patterns).
+ * Used by both buildOrchestratorSystemPrompt and buildOrchestratorPrompt.
+ */
+function buildOrchestratorBody(hqName, context) {
+    let prompt = '';
+    // 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. `;
+    prompt += `All orchestration goes through prlt. Every agent interaction, session management, and board operation `;
+    prompt += `has a dedicated prlt command. Using raw infrastructure commands bypasses session tracking, breaks `;
+    prompt += `health monitoring, and creates orphaned processes.\n\n`;
+    // Role
     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`;
+    // Command reference (dynamically generated)
+    prompt += `## Command Reference\n\n`;
+    prompt += buildOrchestratorCommandReference();
+    // Spawning agents (detailed example)
     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`;
+    // 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`;
@@ -437,6 +604,19 @@ export function buildOrchestratorSystemPrompt(context) {
     }
     return prompt;
 }
+/**
+ * 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 += `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 += buildOrchestratorBody(hqName, context);
+    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
@@ -444,43 +624,7 @@ function buildOrchestratorPrompt(context) {
     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 += `- 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
-            }
-        }
-    }
+    prompt += buildOrchestratorBody(hqName, context);
     // Include user's custom prompt or action content
     if (context.actionPrompt) {
         prompt += `## Instructions\n\n${context.actionPrompt}\n`;
@@ -533,6 +677,11 @@ 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`;
@@ -647,7 +796,8 @@ export async function runHost(context, executor, config, displayMode = 'terminal
     }
     // 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
@@ -658,13 +808,26 @@ 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 ' : '';
+        executorInvocation = `${cmd} ${permissionsFlag}${effortFlag}${printFlag}${disallowPlanFlag}${systemPromptFlag}"$(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);
@@ -976,30 +1139,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.
@@ -1056,7 +1260,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 {
@@ -1068,7 +1272,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 {
@@ -1080,7 +1284,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 {
@@ -1116,7 +1320,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 {
@@ -1347,7 +1551,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
@@ -1509,7 +1713,9 @@ 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 ' : '';
+        executorCmd = `claude ${bypassTrustFlag}${permissionsFlag}${effortFlag}${printFlag}${disallowPlanFlag}"$(cat ${promptFile})"`;
     }
     else if (executor === 'codex') {
         // Use Codex adapter for mode validation and deterministic command building.
@@ -1561,11 +1767,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
@@ -2260,13 +2467,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
@@ -2298,7 +2504,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(' ');
@@ -2347,11 +2554,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
@@ -2511,8 +2719,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;
@@ -2529,7 +2739,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
@@ -2688,7 +2898,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(' ');