@proletariat/cli 0.3.13 → 0.3.15

package/dist/lib/execution/devcontainer.js

@@ -17,6 +17,7 @@ import { parseChannel } from '../workspace-config.js';
  */
 export function generateDevcontainerJson(options, config) {
     const cfg = config || DEFAULT_EXECUTION_CONFIG;
+    const mountMode = options.mountMode || 'worktree'; // Default to worktree mode
     // Parse the channel to determine registry and version
     const channel = parseChannel(options.prltChannel || 'npm');
     const useMount = channel.registry === 'mount';
@@ -34,6 +35,34 @@ export function generateDevcontainerJson(options, config) {
     if (channel.registry === 'gh') {
         buildArgs.GITHUB_TOKEN = '${localEnv:GITHUB_TOKEN}';
     }
+    // Build mounts array - parent repo mounts only needed for worktree mode
+    const mounts = [
+        'source=${localWorkspaceFolder},target=/workspace,type=bind',
+        'source=claude-bash-history,target=/commandhistory,type=volume',
+        'source=claude-credentials,target=/home/node/.claude,type=volume',
+        // NOTE: ~/.claude.json is COPIED (not mounted) to /workspace/.claude.json
+        // to avoid corruption from concurrent writes by multiple containers
+        // NOTE: SSH agent socket mounting doesn't work reliably on Docker Desktop for Mac
+        // So we use HTTPS + token approach instead. The token is fetched fresh at spawn time.
+        'source=${localEnv:PRLT_HQ_PATH}/.proletariat,target=/hq/.proletariat,type=bind',
+        // PMO path can be anywhere (e.g., /hq/pmo or /hq/repos/myrepo/pmo)
+        // Use PRLT_PMO_PATH env var to mount the actual location to /hq/pmo
+        'source=${localEnv:PRLT_PMO_PATH},target=/hq/pmo,type=bind',
+    ];
+    // Only add parent repo mounts for worktree mode
+    // Worktree .git files reference paths like /Users/.../repos/{repoName}/.git/worktrees/name
+    // These mounts make those paths accessible inside the container at /hq/repos/{repoName}
+    // Clone mode doesn't need this because each clone has its own self-contained .git directory
+    if (mountMode === 'worktree' && options.repoWorktrees) {
+        for (const repoName of options.repoWorktrees) {
+            mounts.push(`source=\${localEnv:PRLT_HQ_PATH}/repos/${repoName},target=/hq/repos/${repoName},type=bind`);
+        }
+    }
+    // If using "mount" channel, mount local prlt build from PRLT_REPO_PATH
+    // The setup-prlt.sh script will detect /opt/prlt and configure the wrapper
+    if (useMount) {
+        mounts.push('source=${localEnv:PRLT_REPO_PATH},target=/opt/prlt,type=bind,readonly');
+    }
     const devcontainerJson = {
         name: `Agent: ${options.agentName}`,
         build: {
@@ -59,26 +88,7 @@ export function generateDevcontainerJson(options, config) {
             `--cpus=${options.cpus || cfg.devcontainer.cpus}`,
         ],
         remoteUser: 'node',
-        mounts: [
-            'source=${localWorkspaceFolder},target=/workspace,type=bind',
-            'source=claude-bash-history,target=/commandhistory,type=volume',
-            'source=claude-credentials,target=/home/node/.claude,type=volume',
-            // NOTE: ~/.claude.json is COPIED (not mounted) to /workspace/.claude.json
-            // to avoid corruption from concurrent writes by multiple containers
-            // NOTE: SSH agent socket mounting doesn't work reliably on Docker Desktop for Mac
-            // So we use HTTPS + token approach instead. The token is fetched fresh at spawn time.
-            'source=${localEnv:PRLT_HQ_PATH}/.proletariat,target=/hq/.proletariat,type=bind',
-            // PMO path can be anywhere (e.g., /hq/pmo or /hq/repos/myrepo/pmo)
-            // Use PRLT_PMO_PATH env var to mount the actual location to /hq/pmo
-            'source=${localEnv:PRLT_PMO_PATH},target=/hq/pmo,type=bind',
-            // Mount each repo's directory so git worktrees can resolve their parent
-            // Worktree .git files reference paths like /Users/.../repos/{repoName}/.git/worktrees/name
-            // These mounts make those paths accessible inside the container at /hq/repos/{repoName}
-            ...(options.repoWorktrees || []).map(repoName => `source=\${localEnv:PRLT_HQ_PATH}/repos/${repoName},target=/hq/repos/${repoName},type=bind`),
-            // If using "mount" channel, mount local prlt build from PRLT_REPO_PATH
-            // The setup-prlt.sh script will detect /opt/prlt and configure the wrapper
-            ...(useMount ? ['source=${localEnv:PRLT_REPO_PATH},target=/opt/prlt,type=bind,readonly'] : []),
-        ],
+        mounts,
         containerEnv: {
             DEVCONTAINER: 'true',
             ANTHROPIC_API_KEY: '${localEnv:ANTHROPIC_API_KEY}',
@@ -89,6 +99,8 @@ export function generateDevcontainerJson(options, config) {
             // Agent identity - allows agent to know its name and host path
             PRLT_AGENT_NAME: options.agentName,
             PRLT_HOST_PATH: options.agentDir,
+            // Mount mode - allows scripts to know if git wrapper is needed
+            PRLT_MOUNT_MODE: mountMode,
             // /hq/.proletariat/bin contains prlt wrapper with ESM loader for native modules
             PATH: '/hq/.proletariat/bin:/home/node/.npm-global/bin:/usr/local/bin:/usr/bin:/bin',
         },
@@ -386,8 +398,12 @@ GITWRAPPER
     echo "Git wrapper installed for worktree path translation"
 }
 
-# Set up git wrapper for worktree path translation
-setup_git_wrapper
+# Set up git wrapper for worktree path translation (only needed for worktree mount mode)
+if [ "\${PRLT_MOUNT_MODE:-clone}" = "worktree" ]; then
+    setup_git_wrapper
+else
+    echo "Clone mode: git wrapper not needed (self-contained .git directories)"
+fi
 
 # Copy Claude credentials from workspace to home (each container gets its own copy)
 if [ -f "/workspace/.claude.json" ]; then

package/dist/lib/execution/runners.js

@@ -742,10 +742,15 @@ function createDockerContainer(context, containerName, imageName, config) {
         ...(context.hqPath ? [`-v "${context.hqPath}/.proletariat:/hq/.proletariat"`] : []),
         // PMO path
         ...(context.pmoPath ? [`-v "${context.pmoPath}:/hq/pmo"`] : []),
+        // Mount parent repos for git worktree resolution
+        // Worktree .git files reference paths like /Users/.../repos/{repoName}/.git/worktrees/name
+        // These mounts make those paths accessible inside the container at /hq/repos/{repoName}
+        ...(context.repoWorktrees || []).map(repoName => `-v "${context.hqPath}/repos/${repoName}:/hq/repos/${repoName}"`),
         // Claude credentials - shared named volume (login once, all containers share)
         `-v "claude-credentials:/home/node/.claude"`,
     ];
     // Build environment flags
+    const hasWorktrees = context.repoWorktrees && context.repoWorktrees.length > 0;
     const envVars = [
         `-e DEVCONTAINER=true`,
         `-e PRLT_HQ_PATH=/hq`,
@@ -756,6 +761,8 @@ function createDockerContainer(context, containerName, imageName, config) {
         ...(process.env.GH_TOKEN ? [`-e GH_TOKEN="${process.env.GH_TOKEN}"`] : []),
         // NOTE: Do NOT pass CLAUDE_CODE_OAUTH_TOKEN - it overrides credentials file
         // and setup-token generates invalid tokens. Use "prlt agent auth" instead.
+        // Set mount mode to worktree if we have repo worktrees - triggers git wrapper setup
+        ...(hasWorktrees ? [`-e PRLT_MOUNT_MODE=worktree`] : []),
     ];
     // Resource limits
     const resourceFlags = [
@@ -1421,12 +1428,11 @@ async function runDevcontainerInTmux(context, devcontainerCmd, config, displayMo
         const claudeCmd = cmdMatch ? cmdMatch[1] : devcontainerCmd;
         // Create a script inside the container that runs claude and keeps shell open
         // TERM must be set for Claude's TUI to render properly
-        // Unset DEVCONTAINER and CI to prevent Claude from detecting container/CI environment
-        // which might cause it to suppress TUI output
+        // Unset CI to prevent Claude from detecting CI environment which suppresses TUI output
+        // Note: We keep DEVCONTAINER set so prlt workspace detection works correctly
         const tmuxScript = `#!/bin/bash
 export TERM=xterm-256color
 export COLORTERM=truecolor
-unset DEVCONTAINER
 unset CI
 echo "🚀 Starting: ${sessionName}"
 echo ""
@@ -1695,70 +1701,6 @@ exec $SHELL
         };
     }
 }
-/**
- * Legacy: Run devcontainer in host-side tmux (kept for non-container modes)
- */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-async function runDevcontainerInHostTmux(context, devcontainerCmd, config) {
-    const sessionName = config.tmux.session;
-    const windowName = buildTmuxWindowName(context);
-    try {
-        // Check if tmux is available on host
-        execSync('which tmux', { stdio: 'pipe' });
-        // Write command to temp script
-        const baseDir = context.hqPath
-            ? path.join(context.hqPath, '.proletariat', 'scripts')
-            : path.join(os.homedir(), '.proletariat', 'scripts');
-        fs.mkdirSync(baseDir, { recursive: true });
-        const scriptPath = path.join(baseDir, `exec-${context.ticketId}-${Date.now()}.sh`);
-        const windowTitle = buildWindowTitle(context);
-        const setTitleCmds = getSetTitleCommands(windowTitle);
-        const scriptContent = `#!/bin/bash
-${setTitleCmds}
-echo "🚀 Starting ticket execution: ${context.ticketId}"
-${devcontainerCmd}
-rm -f "${scriptPath}"
-exec $SHELL
-`;
-        fs.writeFileSync(scriptPath, scriptContent, { mode: 0o755 });
-        // Check if session exists
-        let sessionExists = false;
-        try {
-            execSync(`tmux has-session -t ${sessionName}`, { stdio: 'pipe' });
-            sessionExists = true;
-        }
-        catch (err) {
-            console.debug(`[runners:hostTmux] Session ${sessionName} does not exist:`, err);
-            sessionExists = false;
-        }
-        const targetPane = `${sessionName}:${windowName}`;
-        if (!sessionExists) {
-            execSync(`tmux new-session -d -s ${sessionName} -n "${windowName}"`, { stdio: 'pipe' });
-        }
-        else if (config.tmux.layout === 'window') {
-            // Create new window in existing session (starts with shell)
-            execSync(`tmux new-window -t ${sessionName} -n "${windowName}"`, { stdio: 'pipe' });
-        }
-        else {
-            // Split existing pane (starts with shell)
-            execSync(`tmux split-window -t ${sessionName} -h`, { stdio: 'pipe' });
-        }
-        // Send the script command to the shell - execute directly (not source)
-        // Using exec replaces the shell, ensuring proper TTY passthrough
-        execSync(`tmux send-keys -t "${targetPane}" 'exec ${scriptPath}' Enter`, { stdio: 'pipe' });
-        return {
-            success: true,
-            containerId: `devcontainer-${context.agentName}`,
-            sessionId: `${sessionName}:${windowName}`,
-        };
-    }
-    catch (error) {
-        return {
-            success: false,
-            error: error instanceof Error ? error.message : 'Failed to start tmux session',
-        };
-    }
-}
 // =============================================================================
 // Docker Runner
 // =============================================================================

package/dist/lib/execution/spawner.js

@@ -13,6 +13,7 @@ import { findHQRoot } from '../repos/index.js';
 import { hasDevcontainerConfig } from './devcontainer.js';
 import { loadExecutionConfig, getOrPromptCoderName } from './config.js';
 import { runExecution, isDockerRunning, isGitHubTokenAvailable, isDevcontainerCliInstalled } from './runners.js';
+import { detectRepoWorktrees, resolveWorktreePath } from './context.js';
 import { generateBranchName, DEFAULT_EXECUTION_CONFIG, } from './types.js';
 // =============================================================================
 // Git Utilities
@@ -165,24 +166,9 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
             error: `Agent directory not found at ${agentDir}`,
         };
     }
-    // Find worktree path for agent
-    let worktreePath = agentDir;
-    const agentContents = fs.readdirSync(agentDir);
-    const repoWorktrees = agentContents.filter(item => {
-        const itemPath = path.join(agentDir, item);
-        const gitPath = path.join(itemPath, '.git');
-        return fs.statSync(itemPath).isDirectory() && fs.existsSync(gitPath);
-    });
-    if (repoWorktrees.length === 1) {
-        worktreePath = path.join(agentDir, repoWorktrees[0]);
-    }
-    else if (repoWorktrees.length > 1) {
-        worktreePath = agentDir;
-    }
-    else {
-        // No git worktrees found - use current directory
-        worktreePath = process.cwd();
-    }
+    // Detect repository worktrees within agent directory
+    const repoWorktrees = detectRepoWorktrees(agentDir);
+    const worktreePath = resolveWorktreePath(agentDir, repoWorktrees);
     // Get coder name for branch naming (prompts on first use)
     const coderName = await getOrPromptCoderName(db);
     // Generate branch name
@@ -228,6 +214,7 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
         branch,
         hqPath,
         pmoPath,
+        repoWorktrees,
         createPR: options.createPR ?? false,
     };
     // Determine execution environment and display mode

package/dist/lib/execution/types.d.ts

@@ -79,6 +79,7 @@ export interface ExecutionContext {
     branch: string;
     hqPath?: string;
     pmoPath?: string;
+    repoWorktrees?: string[];
     createPR?: boolean;
     actionId?: string;
     actionName?: string;

package/dist/lib/pmo/storage/base.js

@@ -339,6 +339,27 @@ export function seedBuiltinPhaseTemplates(db) {
         insertTemplate.run(template.id, template.name, template.description, JSON.stringify(template.phases), now);
     }
 }
+/**
+ * Rule for agents about using the globally installed prlt command.
+ * This prevents agents from wasting time trying to build from source when working in the prlt repo.
+ */
+const PRLT_USAGE_RULE = `
+**IMPORTANT RULES**:
+
+1. **Use globally installed prlt**: Always use the \`prlt\` command directly
+2. **Never use local dev builds**: Do NOT use \`./apps/cli/bin/dev.js\` or \`./apps/cli/bin/run.js\`
+3. **Why**: You may be working inside the prlt source code. The local builds require dependencies and may not work correctly. The globally installed version is already configured and ready to use.
+
+Example (correct):
+\`\`\`bash
+prlt ticket edit TKT-123 --add-ac "Test passes"
+\`\`\`
+
+Example (WRONG - do not do this):
+\`\`\`bash
+./apps/cli/bin/run.js ticket edit TKT-123 ...
+\`\`\`
+`.trim();
 /**
  * Seed built-in work actions.
  */
@@ -348,7 +369,13 @@ export function seedBuiltinActions(db) {
             id: 'groom',
             name: 'Groom',
             description: 'Flesh out ticket with requirements and acceptance criteria',
-            prompt: `Analyze this ticket and improve its definition:
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Groom
+
+Analyze this ticket and improve its definition:
 - Add detailed requirements if missing or vague
 - Add clear, testable acceptance criteria
 - Break down into subtasks if the work is complex
@@ -422,7 +449,13 @@ After updating, output a brief summary of your grooming changes.`,
             id: 'implement',
             name: 'Implement',
             description: 'Write code to implement the ticket requirements',
-            prompt: `Implement this ticket according to its requirements and acceptance criteria:
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Implement
+
+Implement this ticket according to its requirements and acceptance criteria:
 - Follow the acceptance criteria exactly
 - Write clean, well-tested code
 - Update documentation if the changes affect it
@@ -469,7 +502,13 @@ When complete, the ticket should be ready for code review.`,
             id: 'continue',
             name: 'Continue',
             description: 'Continue working from where you left off',
-            prompt: `Continue working on this ticket from where you left off.
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Continue
+
+Continue working on this ticket from where you left off.
 - Review existing commits and changes to understand current state
 - Check what subtasks remain incomplete
 - Complete the remaining work
@@ -508,7 +547,13 @@ git add -A && prlt commit "your change" && git push
             id: 'test',
             name: 'Write Tests',
             description: 'Add comprehensive tests for the implementation',
-            prompt: `Write comprehensive tests for this ticket's implementation:
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Write Tests
+
+Write comprehensive tests for this ticket's implementation:
 - Add unit tests for core functionality
 - Add integration tests where appropriate
 - Cover edge cases and error handling
@@ -567,7 +612,13 @@ No commits are needed for code review.`,
             id: 'revise',
             name: 'Revise',
             description: 'Address PR feedback and review comments',
-            prompt: `Address the feedback on this ticket's pull request:
+            prompt: `${PRLT_USAGE_RULE}
+
+---
+
+# Action: Revise
+
+Address the feedback on this ticket's pull request:
 - Review all comments and requested changes carefully
 - Make the necessary code changes to address each point
 - Respond to questions with explanations