@proletariat/cli 0.3.24 → 0.3.26

package/dist/hooks/init.js

@@ -13,6 +13,10 @@ const hook = async function ({ id, config }) {
     if (id === 'init') {
         return;
     }
+    // Skip when --help flag is present - help should always be available
+    if (process.argv.includes('--help') || process.argv.includes('-h')) {
+        return;
+    }
     // Skip for help-related commands/flags
     // When user runs just `prlt` with no args, id is undefined
     if (!id || id === 'help') {

package/dist/lib/execution/runners.js

@@ -262,6 +262,8 @@ function buildPrompt(context) {
             prompt += `When you have completed the task, provide a summary of what you did.`;
         }
     }
+    // Universal stop instruction - prevents Claude Code from making additional API calls after task completion
+    prompt += `\n\n---\n\n**STOP:** After providing your final summary, your task is complete. Do not take any further actions, do not verify your work again, and do not continue the conversation. Simply output your summary and stop.`;
     return prompt;
 }
 // =============================================================================
@@ -1479,9 +1481,11 @@ exec bash
                 error: `Failed to write script to container: ${error instanceof Error ? error.message : error}`,
             };
         }
-        // Step 2: Create tmux session with bash explicitly (not default shell which may be zsh)
-        // Using bash avoids zsh-newuser-install prompt that blocks the session
-        const createSessionCmd = `tmux new-session -d -s "${sessionName}" -n "${sessionName}" bash${mouseOption} \\; set-option -g set-titles on \\; set-option -g set-titles-string "#{window_name}"`;
+        // Step 2: Create tmux session running the script directly
+        // Pass the script as the session command (like host runner does) instead of using send-keys.
+        // The send-keys approach had a race condition where keys could be lost if bash hadn't
+        // fully initialized, causing background mode to create empty sessions without running claude.
+        const createSessionCmd = `tmux new-session -d -s "${sessionName}" -n "${sessionName}" "bash ${scriptPath}"${mouseOption} \\; set-option -g set-titles on \\; set-option -g set-titles-string "#{window_name}"`;
         try {
             execSync(`docker exec ${actualContainerId} bash -c '${createSessionCmd}'`, { stdio: 'pipe' });
         }
@@ -1491,28 +1495,28 @@ exec bash
                 error: `Failed to create tmux session inside container: ${error instanceof Error ? error.message : error}`,
             };
         }
-        // Step 3: Send keys to run the script (this runs in the interactive bash)
-        const sendKeysCmd = `tmux send-keys -t "${sessionName}" "source ${scriptPath}" Enter`;
-        try {
-            execSync(`docker exec ${actualContainerId} bash -c '${sendKeysCmd}'`, { stdio: 'pipe' });
-        }
-        catch (error) {
-            return {
-                success: false,
-                error: `Failed to start script in tmux session: ${error instanceof Error ? error.message : error}`,
-            };
-        }
-        // Step 2: Open iTerm tab that attaches directly to container's tmux
-        // Skip this step for background mode - just return success after tmux session is created
+        // Step 3: Handle display mode
+        // For background mode, return success after tmux session is created
         // User can reattach later with `prlt session attach`
         if (displayMode === 'background') {
+            // Verify the tmux session was actually created (brief delay to let tmux start)
+            await new Promise(resolve => setTimeout(resolve, 500));
+            try {
+                execSync(`docker exec ${actualContainerId} tmux has-session -t "${sessionName}" 2>&1`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    error: `Failed to verify tmux session "${sessionName}" inside container. The session may not have started correctly.`,
+                };
+            }
             return {
                 success: true,
                 containerId: actualContainerId,
                 sessionId: sessionName, // Container tmux session name for tracking
             };
         }
-        // Foreground mode: attach to container's tmux session in current terminal (blocking)
+        // For foreground mode: attach to container's tmux session in current terminal (blocking)
         if (displayMode === 'foreground') {
             try {
                 // Clear screen and attach - this blocks until user detaches or claude exits

package/dist/lib/execution/session-utils.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Session Utilities
+ *
+ * Shared utilities for tmux session naming, parsing, and discovery.
+ * Used by session/list.ts and session/attach.ts commands.
+ */
+/**
+ * Known action names used in session naming.
+ * These are the actions defined in pmo/actions/ that may be used when spawning agents.
+ */
+export declare const KNOWN_ACTIONS: readonly ["Implement", "Review", "Fix", "Refactor", "Test", "Document", "work"];
+/**
+ * Parse a tmux session name following prlt naming convention.
+ * Format: {ticketId}-{action}-{agentName}
+ *
+ * Note: Agent names can contain hyphens (like "stout-page"), so we match
+ * from the end using known action names to correctly split the components.
+ *
+ * Example: "TKT-878-Implement-stout-page" -> { ticketId: "TKT-878", action: "Implement", agentName: "stout-page" }
+ */
+export declare function parseSessionName(sessionName: string): {
+    ticketId: string;
+    action: string;
+    agentName: string;
+} | null;
+/**
+ * Build expected session name from execution data.
+ * Format: {ticketId}-{action}-{agentName}
+ * This is the same format used by runners.ts buildSessionName()
+ */
+export declare function buildExpectedSessionName(ticketId: string, agentName: string, action?: string): string;
+/**
+ * Check if a session name matches the expected pattern for a ticket and agent.
+ * Parses the session name and verifies the ticket ID and agent name match exactly.
+ */
+export declare function sessionMatchesExecution(sessionName: string, ticketId: string, agentName: string): boolean;
+/**
+ * Get list of host tmux session names.
+ */
+export declare function getHostTmuxSessionNames(): string[];
+/**
+ * Get map of containerId -> tmux session names.
+ * Only checks containers with the devcontainer.local_folder label.
+ */
+export declare function getContainerTmuxSessionMap(): Map<string, string[]>;
+/**
+ * Flatten container sessions map into an array for easier iteration.
+ */
+export declare function flattenContainerSessions(containerTmuxSessions: Map<string, string[]>): Array<{
+    sessionName: string;
+    containerId: string;
+}>;
+/**
+ * Try to find a matching tmux session for an execution with NULL sessionId.
+ * First tries exact matches with known action names, then falls back to
+ * partial matching with agent name verification.
+ *
+ * @returns The matched session name, or null if no match found
+ */
+export declare function findSessionForExecution(ticketId: string, agentName: string, availableSessions: string[]): string | null;

package/dist/lib/execution/session-utils.js

@@ -0,0 +1,162 @@
+/**
+ * Session Utilities
+ *
+ * Shared utilities for tmux session naming, parsing, and discovery.
+ * Used by session/list.ts and session/attach.ts commands.
+ */
+import { execSync } from 'node:child_process';
+/**
+ * Known action names used in session naming.
+ * These are the actions defined in pmo/actions/ that may be used when spawning agents.
+ */
+export const KNOWN_ACTIONS = [
+    'Implement',
+    'Review',
+    'Fix',
+    'Refactor',
+    'Test',
+    'Document',
+    'work', // Default fallback
+];
+/**
+ * Parse a tmux session name following prlt naming convention.
+ * Format: {ticketId}-{action}-{agentName}
+ *
+ * Note: Agent names can contain hyphens (like "stout-page"), so we match
+ * from the end using known action names to correctly split the components.
+ *
+ * Example: "TKT-878-Implement-stout-page" -> { ticketId: "TKT-878", action: "Implement", agentName: "stout-page" }
+ */
+export function parseSessionName(sessionName) {
+    // First, extract the ticket ID (format: TKT-### or PROJECT-###)
+    const ticketMatch = sessionName.match(/^(TKT-\d+|[A-Z]+-\d+)-/);
+    if (!ticketMatch) {
+        return null;
+    }
+    const ticketId = ticketMatch[1];
+    const remainder = sessionName.slice(ticketMatch[0].length);
+    // Try to match known actions (case-insensitive) at the start of the remainder
+    for (const action of KNOWN_ACTIONS) {
+        const actionLower = action.toLowerCase();
+        const remainderLower = remainder.toLowerCase();
+        // Check if remainder starts with this action followed by a hyphen
+        if (remainderLower.startsWith(actionLower + '-')) {
+            const agentName = remainder.slice(action.length + 1);
+            if (agentName) {
+                return {
+                    ticketId,
+                    action: remainder.slice(0, action.length), // Preserve original casing
+                    agentName,
+                };
+            }
+        }
+    }
+    // Fallback: Split on first hyphen (original behavior for unknown actions)
+    const parts = remainder.split('-');
+    if (parts.length >= 2) {
+        return {
+            ticketId,
+            action: parts[0],
+            agentName: parts.slice(1).join('-'),
+        };
+    }
+    return null;
+}
+/**
+ * Build expected session name from execution data.
+ * Format: {ticketId}-{action}-{agentName}
+ * This is the same format used by runners.ts buildSessionName()
+ */
+export function buildExpectedSessionName(ticketId, agentName, action = 'work') {
+    return `${ticketId}-${action}-${agentName}`;
+}
+/**
+ * Check if a session name matches the expected pattern for a ticket and agent.
+ * Parses the session name and verifies the ticket ID and agent name match exactly.
+ */
+export function sessionMatchesExecution(sessionName, ticketId, agentName) {
+    const parsed = parseSessionName(sessionName);
+    if (!parsed)
+        return false;
+    return parsed.ticketId === ticketId && parsed.agentName === agentName;
+}
+/**
+ * Get list of host tmux session names.
+ */
+export function getHostTmuxSessionNames() {
+    try {
+        execSync('which tmux', { stdio: 'pipe' });
+        const output = execSync('tmux list-sessions -F "#{session_name}"', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        if (!output)
+            return [];
+        return output.split('\n');
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get map of containerId -> tmux session names.
+ * Only checks containers with the devcontainer.local_folder label.
+ */
+export function getContainerTmuxSessionMap() {
+    const sessionMap = new Map();
+    try {
+        const containersOutput = execSync('docker ps --filter "label=devcontainer.local_folder" --format "{{.ID}}"', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+        if (!containersOutput)
+            return sessionMap;
+        for (const containerId of containersOutput.split('\n')) {
+            try {
+                const tmuxOutput = execSync(`docker exec ${containerId} tmux list-sessions -F "#{session_name}" 2>/dev/null`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+                if (tmuxOutput) {
+                    sessionMap.set(containerId, tmuxOutput.split('\n'));
+                }
+            }
+            catch {
+                // Container has no tmux sessions
+            }
+        }
+    }
+    catch {
+        // Docker not available
+    }
+    return sessionMap;
+}
+/**
+ * Flatten container sessions map into an array for easier iteration.
+ */
+export function flattenContainerSessions(containerTmuxSessions) {
+    const result = [];
+    containerTmuxSessions.forEach((sessions, containerId) => {
+        for (const sessionName of sessions) {
+            result.push({ sessionName, containerId });
+        }
+    });
+    return result;
+}
+/**
+ * Try to find a matching tmux session for an execution with NULL sessionId.
+ * First tries exact matches with known action names, then falls back to
+ * partial matching with agent name verification.
+ *
+ * @returns The matched session name, or null if no match found
+ */
+export function findSessionForExecution(ticketId, agentName, availableSessions) {
+    // First, try exact matches with known action names
+    for (const action of KNOWN_ACTIONS) {
+        const expectedName = buildExpectedSessionName(ticketId, agentName, action);
+        if (availableSessions.includes(expectedName)) {
+            return expectedName;
+        }
+        // Also try lowercase variant
+        const expectedNameLower = buildExpectedSessionName(ticketId, agentName, action.toLowerCase());
+        if (availableSessions.includes(expectedNameLower)) {
+            return expectedNameLower;
+        }
+    }
+    // Fallback: partial match with agent name verification
+    // This catches sessions with unknown action names while preventing
+    // false matches when multiple agents work on the same ticket
+    const match = availableSessions.find(s => sessionMatchesExecution(s, ticketId, agentName));
+    return match || null;
+}

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

@@ -31,6 +31,8 @@ export interface SpawnOptions {
     executionConfig?: ExecutionConfig;
     /** Logging callback */
     log?: (msg: string) => void;
+    /** Skip GitHub remote check */
+    skipRemoteCheck?: boolean;
 }
 export interface SpawnResult {
     success: boolean;

package/dist/lib/execution/spawner.js

@@ -10,6 +10,7 @@ import { execSync } from 'node:child_process';
 import { autoExportToBoard } from '../pmo/index.js';
 import { getWorkColumnSetting, findColumnByName } from '../pmo/utils.js';
 import { findHQRoot } from '../repos/index.js';
+import { hasGitHubRemote } from '../repos/git.js';
 import { hasDevcontainerConfig } from './devcontainer.js';
 import { loadExecutionConfig, getOrPromptCoderName } from './config.js';
 import { runExecution, isDockerRunning, isGitHubTokenAvailable, isDevcontainerCliInstalled } from './runners.js';
@@ -30,6 +31,21 @@ function tryGitCommand(cmd, cwd) {
         return false;
     }
 }
+/**
+ * Check if any of the given repos have a GitHub remote
+ */
+function checkReposForRemote(repoPaths) {
+    const reposWithoutRemote = [];
+    for (const repoPath of repoPaths) {
+        if (isGitRepo(repoPath) && !hasGitHubRemote(repoPath)) {
+            reposWithoutRemote.push(repoPath);
+        }
+    }
+    return {
+        hasRemote: reposWithoutRemote.length === 0,
+        reposWithoutRemote,
+    };
+}
 /**
  * Check if a directory is a git repository
  */
@@ -272,6 +288,32 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
     const gitRepos = repoWorktrees.length > 0
         ? repoWorktrees.map(r => path.join(agentDir, r))
         : [worktreePath];
+    // Check for GitHub remote if PR creation is enabled
+    if (!options.skipRemoteCheck) {
+        const remoteCheck = checkReposForRemote(gitRepos);
+        if (!remoteCheck.hasRemote) {
+            const repoNames = remoteCheck.reposWithoutRemote.map(r => path.basename(r)).join(', ');
+            if (options.createPR) {
+                // If PR creation is requested, we must have a remote
+                return {
+                    success: false,
+                    ticketId: ticket.id,
+                    agentName,
+                    error: `No GitHub remote found for: ${repoNames}\n\n` +
+                        'Cannot create PRs without a GitHub remote.\n' +
+                        'Options:\n' +
+                        '  1. Run "prlt repo create" to create a GitHub repo and set up remote\n' +
+                        '  2. Manually add a remote: git remote add origin <url>\n' +
+                        '  3. Use --skip-remote-check to spawn without PR support',
+                };
+            }
+            else {
+                // Just warn if not creating PRs
+                log(`⚠️  No GitHub remote found for: ${repoNames}. PRs cannot be created.`);
+                log('   Run "prlt repo create" to set up a GitHub remote.');
+            }
+        }
+    }
     // Always fetch latest from origin before branch operations
     // This ensures all spawn actions work with the latest code
     for (const repoPath of gitRepos) {

package/dist/lib/flags/resolver.d.ts

@@ -74,8 +74,8 @@ export interface ResolverChoice<T = string> {
 export interface PromptDefinition<TValue = unknown, TFlags = Record<string, unknown>> {
     /** The flag name this prompt resolves (e.g., 'column', 'title') */
     flagName: string;
-    /** Prompt type */
-    type: 'list' | 'checkbox' | 'input' | 'confirm' | 'editor';
+    /** Prompt type. Use 'multiline' for inline multi-line text input (replaces 'editor') */
+    type: 'list' | 'checkbox' | 'input' | 'confirm' | 'editor' | 'multiline';
     /** User-facing prompt message */
     message: string | ((ctx: ResolverContext<TFlags>) => string);
     /**

package/dist/lib/flags/resolver.js

@@ -40,6 +40,7 @@
  */
 import inquirer from 'inquirer';
 import { outputPromptAsJson, createMetadata, } from '../prompt-json.js';
+import { multiLineInput } from '../multiline-input.js';
 /**
  * FlagResolver handles unified flag resolution for both human and machine modes.
  *
@@ -228,6 +229,20 @@ export class FlagResolver {
      * Prompt for value in interactive mode
      */
     async promptInteractive(prompt, message, choices, defaultValue) {
+        // Handle multiline type specially - use our custom multiLineInput
+        if (prompt.type === 'multiline') {
+            const result = await multiLineInput({
+                message,
+                default: typeof defaultValue === 'string' ? defaultValue : '',
+                validate: prompt.validate
+                    ? (value) => prompt.validate(value, this.resolverContext)
+                    : undefined,
+            });
+            if (result.cancelled) {
+                throw new Error('Input cancelled');
+            }
+            return result.value;
+        }
         // Build inquirer prompt config as a single question object
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const question = {

package/dist/lib/init/index.js

@@ -9,6 +9,8 @@ import { addRepositoriesToHQ, isInGitRepo } from '../repos/index.js';
 import { createPMO, } from '../pmo/index.js';
 import { createWorkspaceDatabase, addRepositoriesToDatabase, addAgentsToDatabase, createTheme, addThemeNames, setActiveTheme } from '../database/index.js';
 import { ensureMachineConfigDir, registerHeadquarters, getOrganizations, createOrganization, } from '../machine-config.js';
+import { hasGitHubRemote } from '../repos/git.js';
+import { isGHInstalled, isGHAuthenticated } from '../pr/index.js';
 /**
  * Validate that HQ path is not inside a git repository or another HQ
  * Returns: { valid: true } or { valid: false, reason: string }
@@ -291,6 +293,22 @@ export async function initializeHQ(options) {
         };
     });
     addRepositoriesToDatabase(hqPath, dbRepos);
+    // Check for repos without GitHub remotes (only in interactive mode)
+    if (!quiet && addedRepos.length > 0) {
+        const reposPath = path.join(hqPath, 'repos');
+        const reposWithoutRemote = [];
+        for (const repoName of addedRepos) {
+            const repoFullPath = path.join(reposPath, repoName);
+            if (fs.existsSync(repoFullPath) && !hasGitHubRemote(repoFullPath)) {
+                reposWithoutRemote.push(repoName);
+            }
+        }
+        if (reposWithoutRemote.length > 0 && isGHInstalled() && isGHAuthenticated()) {
+            log(chalk.yellow(`\n⚠️  The following repos have no GitHub remote: ${reposWithoutRemote.join(', ')}`));
+            log(chalk.gray('   Without a remote, agents cannot create pull requests.'));
+            log(chalk.gray('   You can create GitHub repos later with: prlt repo create'));
+        }
+    }
     // Create PMO if requested
     if (pmoSetup.includePMO) {
         await createPMO({

package/dist/lib/multiline-input.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Multi-line text input utility for CLI.
+ *
+ * Provides inline TTY text input without opening external editors.
+ * Handles paste safely, supports cursor navigation, and provides
+ * clear visual feedback.
+ *
+ * Usage:
+ * ```typescript
+ * const text = await multiLineInput({
+ *   message: 'Enter description:',
+ *   default: 'Existing content...',
+ * });
+ * ```
+ */
+/**
+ * Options for multiLineInput
+ */
+export interface MultiLineInputOptions {
+    /** Prompt message displayed above the input area */
+    message: string;
+    /** Default/initial content to populate the input with */
+    default?: string;
+    /** Hint text shown below the input area (e.g., key bindings) */
+    hint?: string;
+    /** Whether input is required (empty not allowed) */
+    required?: boolean;
+    /** Validation function - returns true if valid, or error message */
+    validate?: (value: string) => boolean | string;
+}
+/**
+ * Result of multiLineInput
+ */
+export interface MultiLineInputResult {
+    /** The entered text */
+    value: string;
+    /** Whether input was cancelled (Ctrl+C) */
+    cancelled: boolean;
+}
+/**
+ * Collect multi-line input from the user with an inline TTY editor.
+ *
+ * Features:
+ * - Arrow key navigation
+ * - Backspace/delete
+ * - Copy-paste handling (escapes special characters)
+ * - Ctrl+D to finish, Ctrl+C to cancel
+ * - Pre-populated content support
+ * - Real-time visual feedback
+ *
+ * @param options Input options
+ * @returns The entered text and cancellation status
+ */
+export declare function multiLineInput(options: MultiLineInputOptions): Promise<MultiLineInputResult>;
+/**
+ * Convenience wrapper that returns just the value string.
+ * Throws if cancelled.
+ */
+export declare function promptMultiLine(options: MultiLineInputOptions): Promise<string>;
+/**
+ * Integration with FlagResolver - creates a prompt-compatible function
+ */
+export declare function createMultiLinePrompt(message: string, defaultValue?: string, hint?: string): () => Promise<string>;