@proletariat/cli 0.3.58 → 0.3.60

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,10 +381,11 @@ 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 };
@@ -555,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. `;
@@ -563,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`;
@@ -587,6 +603,13 @@ function buildOrchestratorBody(hqName, context) {
     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');
@@ -611,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;
 }
@@ -623,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) {
@@ -662,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`;
     }
@@ -686,6 +712,13 @@ function buildPrompt(context) {
     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
@@ -787,13 +820,23 @@ 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 Codex, we use the codex adapter for deterministic command building (TKT-080)
@@ -811,7 +854,9 @@ export async function runHost(context, executor, config, displayMode = 'terminal
         // 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")"`;
+        // 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.
@@ -845,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"' : ''}
@@ -1695,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} && ` : '';
@@ -1715,7 +1769,9 @@ export function buildDevcontainerCommand(context, executor, promptFile, containe
         const effortFlag = '--effort high ';
         // 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})"`;
+        // 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.
@@ -1806,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;
@@ -1822,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)
@@ -2849,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
@@ -2870,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}"`;
@@ -2884,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');
@@ -2916,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}` };
     }