@proletariat/cli 0.3.35 → 0.3.40

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

@@ -2,9 +2,34 @@
  * Session Utilities
  *
  * Shared utilities for tmux session naming, parsing, and discovery.
- * Used by session/list.ts and session/attach.ts commands.
+ * Used by session/list.ts, session/attach.ts, session/health.ts, and session/peek.ts commands.
  */
 import { execSync } from 'node:child_process';
+/**
+ * Capture the last N lines from a tmux pane.
+ * Supports both host tmux sessions and container tmux sessions (via docker exec).
+ *
+ * @param sessionId - The tmux session ID to capture from
+ * @param lines - Number of scrollback lines to capture
+ * @param containerId - Optional container ID for container-based sessions
+ * @returns The captured pane content, or null if capture fails
+ */
+export function captureTmuxPane(sessionId, lines, containerId) {
+    try {
+        const captureCmd = `tmux capture-pane -t "${sessionId}" -p -S -${lines}`;
+        if (containerId) {
+            return execSync(`docker exec ${containerId} bash -c '${captureCmd}'`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 10000 }).trim();
+        }
+        return execSync(captureCmd, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 5000,
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Known action names used in session naming.
  * These are the actions defined in pmo/actions/ that may be used when spawning agents.
@@ -102,10 +127,37 @@ export function getHostTmuxSessionNames() {
 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)
+        const containerIds = new Set();
+        // Primary: devcontainer-labeled containers (historical behavior).
+        try {
+            const labeledOutput = execSync('docker ps --filter "label=devcontainer.local_folder" --format "{{.ID}}"', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+            if (labeledOutput) {
+                for (const id of labeledOutput.split('\n')) {
+                    if (id.trim())
+                        containerIds.add(id.trim());
+                }
+            }
+        }
+        catch {
+            // Ignore and continue with broad fallback discovery.
+        }
+        // Fallback: include all running containers so prlt-managed devcontainers
+        // without the devcontainer.local_folder label are still discoverable.
+        try {
+            const allOutput = execSync('docker ps --format "{{.ID}}"', { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+            if (allOutput) {
+                for (const id of allOutput.split('\n')) {
+                    if (id.trim())
+                        containerIds.add(id.trim());
+                }
+            }
+        }
+        catch {
+            // Docker not available.
+        }
+        if (containerIds.size === 0)
             return sessionMap;
-        for (const containerId of containersOutput.split('\n')) {
+        for (const containerId of containerIds) {
             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) {
@@ -134,6 +186,21 @@ export function flattenContainerSessions(containerTmuxSessions) {
     });
     return result;
 }
+/**
+ * Find container sessions using prefix matching.
+ * Handles short vs full container ID mismatches between DB records and docker output.
+ */
+export function findContainerSessionsByPrefix(containerTmuxSessions, containerId) {
+    const exact = containerTmuxSessions.get(containerId);
+    if (exact)
+        return exact;
+    for (const [key, sessions] of containerTmuxSessions) {
+        if (key.startsWith(containerId) || containerId.startsWith(key)) {
+            return sessions;
+        }
+    }
+    return [];
+}
 /**
  * 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

package/dist/lib/execution/spawner.js

@@ -13,7 +13,7 @@ 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';
+import { runExecution, isDockerRunning, isGitHubTokenAvailable, isDevcontainerCliInstalled, runExecutorPreflight } from './runners.js';
 import { detectRepoWorktrees, resolveWorktreePath } from './context.js';
 import { generateBranchName, DEFAULT_EXECUTION_CONFIG, } from './types.js';
 // =============================================================================
@@ -282,6 +282,19 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
     }
     const displayMode = options.displayMode || 'terminal';
     const sandboxed = !(options.skipPermissions ?? false);
+    // Executor preflight check (TKT-1082): verify binary is available before proceeding
+    // For host environment, check immediately. For devcontainer, check happens after container start.
+    if (environment === 'host') {
+        const preflight = runExecutorPreflight(executor, environment);
+        if (!preflight.ok) {
+            return {
+                success: false,
+                ticketId: ticket.id,
+                agentName,
+                error: preflight.error,
+            };
+        }
+    }
     // Create branch in worktree(s)
     // For devcontainer environments, run git commands inside the container
     // because the worktree .git file has container paths, not host paths
@@ -438,7 +451,7 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
         };
     }
     else {
-        executionStorage.updateStatus(execution.id, 'failed');
+        executionStorage.updateStatus(execution.id, 'failed', undefined, result.error);
         return {
             success: false,
             executionId: execution.id,

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

@@ -33,7 +33,7 @@ export declare class ExecutionStorage {
     /**
      * Update execution status
      */
-    updateStatus(id: string, status: ExecutionStatus, exitCode?: number): void;
+    updateStatus(id: string, status: ExecutionStatus, exitCode?: number, errorMessage?: string): void;
     /**
      * Update execution with process info
      */
@@ -71,6 +71,11 @@ export declare class ExecutionStorage {
      * Returns the number of stale executions cleaned up.
      */
     cleanupStaleExecutions(): number;
+    /**
+     * Find container sessions using prefix matching.
+     * Handles cases where the stored containerId format differs from docker ps output.
+     */
+    private findContainerSessionsByPrefix;
     /**
      * Get list of host tmux session names
      */

package/dist/lib/execution/storage.js

@@ -29,6 +29,7 @@ function rowToAgentWork(row) {
         startedAt: new Date(row.started_at),
         completedAt: row.completed_at ? new Date(row.completed_at) : undefined,
         exitCode: row.exit_code ?? undefined,
+        errorMessage: row.error_message || undefined,
     };
 }
 // =============================================================================
@@ -68,14 +69,28 @@ export class ExecutionStorage {
     /**
      * Update execution status
      */
-    updateStatus(id, status, exitCode) {
+    updateStatus(id, status, exitCode, errorMessage) {
         const completedAt = ['completed', 'failed', 'stopped'].includes(status) ? Date.now() : null;
-        if (exitCode !== undefined) {
+        if (exitCode !== undefined && errorMessage) {
+            this.db.prepare(`
+        UPDATE ${T.agent_work}
+        SET status = ?, completed_at = ?, exit_code = ?, error_message = ?
+        WHERE id = ?
+      `).run(status, completedAt, exitCode, errorMessage, id);
+        }
+        else if (exitCode !== undefined) {
             this.db.prepare(`
         UPDATE ${T.agent_work}
         SET status = ?, completed_at = ?, exit_code = ?
         WHERE id = ?
       `).run(status, completedAt, exitCode, id);
+        }
+        else if (errorMessage) {
+            this.db.prepare(`
+        UPDATE ${T.agent_work}
+        SET status = ?, completed_at = ?, error_message = ?
+        WHERE id = ?
+      `).run(status, completedAt, errorMessage, id);
         }
         else {
             this.db.prepare(`
@@ -215,9 +230,9 @@ export class ExecutionStorage {
             }
             let sessionExists = false;
             if (exec.environment === 'devcontainer' && exec.containerId) {
-                // Check if session exists in container
-                const containerSessions = containerTmuxSessions.get(exec.containerId);
-                sessionExists = containerSessions?.includes(exec.sessionId) ?? false;
+                // Check if session exists in container (use prefix matching for ID format differences)
+                const containerSessions = this.findContainerSessionsByPrefix(containerTmuxSessions, exec.containerId);
+                sessionExists = containerSessions.includes(exec.sessionId);
             }
             else {
                 // Check if session exists on host
@@ -231,6 +246,21 @@ export class ExecutionStorage {
         }
         return cleanedCount;
     }
+    /**
+     * Find container sessions using prefix matching.
+     * Handles cases where the stored containerId format differs from docker ps output.
+     */
+    findContainerSessionsByPrefix(containerTmuxSessions, containerId) {
+        const exact = containerTmuxSessions.get(containerId);
+        if (exact)
+            return exact;
+        for (const [key, sessions] of containerTmuxSessions) {
+            if (key.startsWith(containerId) || containerId.startsWith(key)) {
+                return sessions;
+            }
+        }
+        return [];
+    }
     /**
      * Get list of host tmux session names
      */

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

@@ -57,6 +57,7 @@ export interface AgentWork {
     startedAt: Date;
     completedAt?: Date;
     exitCode?: number;
+    errorMessage?: string;
 }
 export interface ExecutionContext {
     ticketId: string;
@@ -112,6 +113,7 @@ export declare function getBranchType(category?: string): string;
  * - agent: the AI agent doing the work
  */
 export declare function generateBranchName(ticketId: string, ticketTitle: string, ownerName: string, agentName: string, category?: string): string;
+export type AuthMethod = 'oauth' | 'apikey';
 export interface ExecutionConfig {
     defaultEnvironment: ExecutionEnvironment;
     defaultExecutor: ExecutorType;
@@ -119,6 +121,7 @@ export interface ExecutionConfig {
     shell: Shell;
     outputMode: OutputMode;
     sandboxed: boolean;
+    authMethod?: AuthMethod;
     tmux: {
         session: string;
         layout: 'split' | 'window';

package/dist/lib/mcp/tools/board.js

@@ -2,9 +2,9 @@
  * MCP Board Tools
  */
 import { z } from 'zod';
-import { errorResponse, strictTool } from '../helpers.js';
+import { formatTicket, errorResponse, strictTool } from '../helpers.js';
 export function registerBoardTools(server, ctx) {
-    strictTool(server, 'board_show', 'Show the kanban board', { project: z.string().optional().describe('Project ID') }, async (params) => {
+    strictTool(server, 'board_view', 'Show the kanban board', { project: z.string().optional().describe('Project ID') }, async (params) => {
         try {
             let projectId = params.project;
             if (!projectId) {
@@ -27,10 +27,8 @@ export function registerBoardTools(server, ctx) {
                                     position: col.position,
                                     ticketCount: col.tickets.length,
                                     tickets: col.tickets.map((t) => ({
-                                        id: t.id,
-                                        title: t.title,
-                                        priority: t.priority,
-                                        assignee: t.assignee,
+                                        ...formatTicket(t),
+                                        labels: t.labels,
                                     })),
                                 })),
                                 updatedAt: board.updatedAt.toISOString(),

package/dist/lib/mcp/tools/cli-passthrough.js

@@ -17,9 +17,26 @@ export function registerAgentTools(server, ctx) {
             return errorResponse(error);
         }
     });
-    strictTool(server, 'agent_status', 'Check agent status', {}, async () => {
+    strictTool(server, 'agent_status', 'Check agent status. With agent param, returns that agent\'s status. Without, auto-detects current agent or returns all agent statuses.', { agent: z.string().optional().describe('Agent name. If omitted, auto-detects current agent or returns all.') }, async (params) => {
         try {
-            const output = ctx.runCommand('prlt agent status --json 2>/dev/null || prlt agent status');
+            if (params.agent) {
+                const output = ctx.runCommand(`prlt agent status ${params.agent} --json`);
+                return textResponse(output);
+            }
+            // Try auto-detecting current agent via whoami
+            try {
+                const whoamiOutput = ctx.runCommand('prlt whoami --json');
+                const whoami = JSON.parse(whoamiOutput);
+                if (whoami.agent) {
+                    const output = ctx.runCommand(`prlt agent status ${whoami.agent} --json`);
+                    return textResponse(output);
+                }
+            }
+            catch {
+                // whoami failed or no agent detected, fall through
+            }
+            // No agent detected - return all agent statuses
+            const output = ctx.runCommand('prlt agent status --json');
             return textResponse(output);
         }
         catch (error) {
@@ -139,7 +156,7 @@ export function registerRepoTools(server, ctx) {
     });
 }
 export function registerBranchTools(server, ctx) {
-    strictTool(server, 'branch_list', 'List branches', {}, async () => {
+    strictTool(server, 'branch_list', 'List branches (across all HQ repos if not in a git repo)', {}, async () => {
         try {
             const output = ctx.runCommand('prlt branch list');
             return textResponse(output);
@@ -161,9 +178,11 @@ export function registerBranchTools(server, ctx) {
             return errorResponse(error);
         }
     });
-    strictTool(server, 'branch_where', 'Show which ticket/branch you are on', {}, async () => {
+    strictTool(server, 'branch_where', 'Find which directory a branch is checked out in', {
+        search: z.string().describe('Branch name or ticket ID to search for'),
+    }, async (params) => {
         try {
-            const output = ctx.runCommand('prlt branch where');
+            const output = ctx.runCommand(`prlt branch where ${params.search}`);
             return textResponse(output);
         }
         catch (error) {
@@ -314,7 +333,7 @@ export function registerUtilityTools(server, ctx) {
     });
     strictTool(server, 'session_list', 'List tmux sessions', {}, async () => {
         try {
-            const output = ctx.runCommand('prlt session list');
+            const output = ctx.runCommand('prlt session list --json');
             return textResponse(output);
         }
         catch (error) {

package/dist/lib/mcp/tools/epic.js

@@ -71,7 +71,7 @@ export function registerEpicTools(server, ctx) {
             return errorResponse(error);
         }
     });
-    strictTool(server, 'epic_show', 'Get epic details with tickets', { id: z.string().describe('Epic ID') }, async (params) => {
+    strictTool(server, 'epic_view', 'Get epic details with tickets', { id: z.string().describe('Epic ID') }, async (params) => {
         try {
             const epic = await ctx.storage.getEpic(params.id);
             if (!epic)
@@ -83,9 +83,14 @@ export function registerEpicTools(server, ctx) {
                         text: JSON.stringify({
                             success: true,
                             epic: {
-                                ...epic,
+                                id: epic.id,
+                                projectId: epic.projectId,
+                                title: epic.title,
+                                status: epic.status,
+                                position: epic.position,
+                                specId: epic.specId,
                                 ticketCount: tickets.length,
-                                tickets: tickets.map((t) => ({ id: t.id, title: t.title, statusName: t.statusName, priority: t.priority })),
+                                tickets: tickets.map((t) => ({ id: t.id, title: t.title, statusName: t.statusName, priority: t.priority, category: t.category })),
                                 createdAt: epic.createdAt.toISOString(),
                                 updatedAt: epic.updatedAt.toISOString(),
                             },

package/dist/lib/mcp/tools/index.d.ts

@@ -17,4 +17,5 @@ export { registerTemplateTools } from './template.js';
 export { registerViewTools } from './view.js';
 export { registerDietTools } from './diet.js';
 export { registerLabelTools } from './label.js';
+export { registerTmuxTools } from './tmux.js';
 export { registerAgentTools, registerDockerTools, registerRepoTools, registerBranchTools, registerGitHubTools, registerInitTools, registerUtilityTools, } from './cli-passthrough.js';

package/dist/lib/mcp/tools/index.js

@@ -17,5 +17,6 @@ export { registerTemplateTools } from './template.js';
 export { registerViewTools } from './view.js';
 export { registerDietTools } from './diet.js';
 export { registerLabelTools } from './label.js';
+export { registerTmuxTools } from './tmux.js';
 // CLI passthrough tools
 export { registerAgentTools, registerDockerTools, registerRepoTools, registerBranchTools, registerGitHubTools, registerInitTools, registerUtilityTools, } from './cli-passthrough.js';

package/dist/lib/mcp/tools/spec.js

@@ -67,7 +67,7 @@ export function registerSpecTools(server, ctx) {
             return errorResponse(error);
         }
     });
-    strictTool(server, 'spec_show', 'Get spec details', { id: z.string().describe('Spec ID') }, async (params) => {
+    strictTool(server, 'spec_view', 'Get spec details', { id: z.string().describe('Spec ID') }, async (params) => {
         try {
             const spec = await ctx.storage.getSpec(params.id);
             if (!spec)

package/dist/lib/mcp/tools/ticket.js

@@ -5,7 +5,7 @@ import { z } from 'zod';
 import { formatTicket, formatTicketFull, errorResponse, strictTool } from '../helpers.js';
 import { getWorkspacePriorities, setWorkspacePriorities } from '../../pmo/utils.js';
 export function registerTicketTools(server, ctx) {
-    strictTool(server, 'ticket_list', 'List tickets with optional filters', {
+    strictTool(server, 'ticket_list', 'List tickets with optional filters. Returns summary fields only (no descriptions). Use ticket_show for full details.', {
         project: z.string().optional().describe('Project ID'),
         column: z.string().optional().describe('Filter by column/status'),
         priority: z.string().optional().describe('Filter by priority (uses workspace priority scale)'),
@@ -17,9 +17,11 @@ export function registerTicketTools(server, ctx) {
         label: z.string().optional().describe('Filter by label name'),
         label_group: z.string().optional().describe('Filter by label group name'),
         all_projects: z.boolean().optional().describe('List from all projects'),
+        limit: z.number().min(1).optional().describe('Maximum number of tickets to return (default: 50)'),
+        offset: z.number().min(0).optional().describe('Number of tickets to skip for pagination (default: 0)'),
     }, async (params) => {
         try {
-            const tickets = await ctx.storage.listTickets(params.all_projects ? undefined : params.project, {
+            const allTickets = await ctx.storage.listTickets(params.all_projects ? undefined : params.project, {
                 column: params.column,
                 priority: params.priority,
                 category: params.category,
@@ -31,31 +33,31 @@ export function registerTicketTools(server, ctx) {
                 labelGroup: params.label_group,
                 allProjects: params.all_projects,
             });
+            const total = allTickets.length;
+            const offset = params.offset ?? 0;
+            const limit = params.limit ?? 50;
+            const tickets = allTickets.slice(offset, offset + limit);
             return {
                 content: [{
                         type: 'text',
                         text: JSON.stringify({
                             success: true,
+                            total,
                             count: tickets.length,
+                            offset,
+                            limit,
                             tickets: await Promise.all(tickets.map(async (t) => {
                                 const ticketLabels = await ctx.storage.getLabelsForTicket(t.id);
                                 return {
                                     id: t.id,
                                     title: t.title,
-                                    description: t.description,
                                     priority: t.priority,
                                     category: t.category,
                                     statusName: t.statusName,
                                     statusCategory: t.statusCategory,
-                                    projectId: t.projectId,
                                     assignee: t.assignee,
-                                    owner: t.owner,
-                                    epicId: t.epicId,
-                                    branch: t.branch,
                                     position: t.position,
                                     labels: ticketLabels.map(l => ({ id: l.id, name: l.name, groupName: l.groupName })),
-                                    createdAt: t.createdAt.toISOString(),
-                                    updatedAt: t.updatedAt.toISOString(),
                                 };
                             })),
                         }, null, 2),

package/dist/lib/mcp/tools/tmux.d.ts

@@ -0,0 +1,16 @@
+/**
+ * MCP Tmux Tools
+ *
+ * Provides tmux interaction tools for AI agents to drive interactive CLI sessions.
+ * Used by the explore-cli action to perform exploratory QA testing.
+ *
+ * Tools:
+ * - tmux_send_keys: Send keystrokes to a tmux session
+ * - tmux_capture_pane: Capture current terminal screen from a tmux session
+ * - tmux_start_session: Start a new tmux session with an optional command
+ * - tmux_list_sessions: List active tmux sessions
+ * - tmux_kill_session: Kill a tmux session
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpToolContext } from '../types.js';
+export declare function registerTmuxTools(server: McpServer, _ctx: McpToolContext): void;

package/dist/lib/mcp/tools/tmux.js

@@ -0,0 +1,182 @@
+/**
+ * MCP Tmux Tools
+ *
+ * Provides tmux interaction tools for AI agents to drive interactive CLI sessions.
+ * Used by the explore-cli action to perform exploratory QA testing.
+ *
+ * Tools:
+ * - tmux_send_keys: Send keystrokes to a tmux session
+ * - tmux_capture_pane: Capture current terminal screen from a tmux session
+ * - tmux_start_session: Start a new tmux session with an optional command
+ * - tmux_list_sessions: List active tmux sessions
+ * - tmux_kill_session: Kill a tmux session
+ */
+import { z } from 'zod';
+import { execFileSync } from 'node:child_process';
+import { errorResponse, strictTool, successResponse } from '../helpers.js';
+const TMUX_ENV = { ...process.env, TERM: process.env.TERM || 'xterm-256color' };
+/**
+ * Execute a tmux command with args passed as an array (no shell interpretation).
+ */
+function runTmux(args, timeoutMs = 10_000) {
+    return execFileSync('tmux', args, {
+        encoding: 'utf-8',
+        timeout: timeoutMs,
+        env: TMUX_ENV,
+    }).trim();
+}
+/** Validate session name — alphanumeric, hyphens, underscores, dots only. */
+function validateSessionName(name) {
+    if (!/^[a-zA-Z0-9_.-]+$/.test(name)) {
+        throw new Error(`Invalid session name: "${name}". Only alphanumeric, hyphens, underscores, and dots allowed.`);
+    }
+}
+/**
+ * Check if a tmux session exists.
+ */
+function sessionExists(sessionName) {
+    try {
+        runTmux(['has-session', '-t', sessionName]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function registerTmuxTools(server, _ctx) {
+    // ── tmux_send_keys ───────────────────────────────────────────────────
+    strictTool(server, 'tmux_send_keys', 'Send keystrokes to a tmux session. Supports text input and special keys like Enter, Escape, Up, Down, Left, Right, C-c (Ctrl+C), Tab, BSpace, etc. Use this to interact with interactive CLI menus and prompts.', {
+        session: z.string().describe('Tmux session name to send keys to'),
+        keys: z.string().describe('Keys to send. Text is sent literally; special keys: Enter, Escape, Up, Down, Left, Right, C-c, C-d, Tab, BSpace, Space, Home, End, PPage, NPage'),
+        literal: z.boolean().optional().describe('If true, send keys as literal text (disables special key lookup). Default false.'),
+        delay_ms: z.number().optional().describe('Milliseconds to wait after sending keys before returning (default 100). Useful to let the UI render.'),
+    }, async (params) => {
+        try {
+            validateSessionName(params.session);
+            if (!sessionExists(params.session)) {
+                return errorResponse(new Error(`Tmux session not found: ${params.session}`));
+            }
+            const args = ['send-keys', '-t', params.session];
+            if (params.literal)
+                args.push('-l');
+            args.push(params.keys);
+            runTmux(args);
+            // Wait for UI to render
+            const delay = Math.min(params.delay_ms ?? 100, 30_000);
+            if (delay > 0) {
+                await new Promise((resolve) => setTimeout(resolve, delay));
+            }
+            return successResponse({ sent: params.keys, session: params.session });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // ── tmux_capture_pane ────────────────────────────────────────────────
+    strictTool(server, 'tmux_capture_pane', 'Capture the current visible content of a tmux pane. Returns the terminal screen text, useful for reading CLI output, menu states, error messages, and interactive prompt displays.', {
+        session: z.string().describe('Tmux session name to capture from'),
+        start_line: z.number().optional().describe('Start line for capture (negative = scrollback). Default: beginning of visible pane.'),
+        end_line: z.number().optional().describe('End line for capture. Default: end of visible pane.'),
+        escape_sequences: z.boolean().optional().describe('If true, include ANSI escape sequences in output. Default false (plain text).'),
+    }, async (params) => {
+        try {
+            validateSessionName(params.session);
+            if (!sessionExists(params.session)) {
+                return errorResponse(new Error(`Tmux session not found: ${params.session}`));
+            }
+            const args = ['capture-pane', '-t', params.session, '-p'];
+            if (params.escape_sequences)
+                args.push('-e');
+            if (params.start_line !== undefined)
+                args.push('-S', String(params.start_line));
+            if (params.end_line !== undefined)
+                args.push('-E', String(params.end_line));
+            const content = runTmux(args);
+            return successResponse({
+                session: params.session,
+                content,
+                lines: content.split('\n').length,
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // ── tmux_start_session ───────────────────────────────────────────────
+    strictTool(server, 'tmux_start_session', 'Start a new tmux session, optionally running a command inside it. Use this to launch a CLI session for exploratory testing.', {
+        session: z.string().describe('Name for the new tmux session'),
+        command: z.string().optional().describe('Command to run in the session (e.g., "prlt" to launch the CLI)'),
+        width: z.number().optional().describe('Terminal width in columns (default 120)'),
+        height: z.number().optional().describe('Terminal height in rows (default 40)'),
+    }, async (params) => {
+        try {
+            validateSessionName(params.session);
+            if (sessionExists(params.session)) {
+                return errorResponse(new Error(`Tmux session already exists: ${params.session}`));
+            }
+            const width = params.width ?? 120;
+            const height = params.height ?? 40;
+            const args = ['new-session', '-d', '-s', params.session, '-x', String(width), '-y', String(height)];
+            if (params.command)
+                args.push(params.command);
+            runTmux(args);
+            // Give the session a moment to initialize
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            return successResponse({
+                session: params.session,
+                width,
+                height,
+                command: params.command || '(default shell)',
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // ── tmux_list_sessions ───────────────────────────────────────────────
+    strictTool(server, 'tmux_list_sessions', 'List all active tmux sessions with their status and dimensions.', {}, async () => {
+        try {
+            let output;
+            try {
+                output = runTmux(['list-sessions', '-F', '#{session_name}|#{session_width}|#{session_height}|#{session_windows}|#{session_created}']);
+            }
+            catch {
+                // No sessions running
+                return successResponse({ sessions: [] });
+            }
+            const sessions = output.split('\n').filter(Boolean).map((line) => {
+                const [name, width, height, windows, created] = line.split('|');
+                return {
+                    name,
+                    width: parseInt(width, 10),
+                    height: parseInt(height, 10),
+                    windows: parseInt(windows, 10),
+                    created: new Date(parseInt(created, 10) * 1000).toISOString(),
+                };
+            });
+            return successResponse({ sessions });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+    // ── tmux_kill_session ────────────────────────────────────────────────
+    strictTool(server, 'tmux_kill_session', 'Kill (terminate) a tmux session and all processes running in it.', {
+        session: z.string().describe('Name of the tmux session to kill'),
+    }, async (params) => {
+        try {
+            validateSessionName(params.session);
+            if (!sessionExists(params.session)) {
+                return errorResponse(new Error(`Tmux session not found: ${params.session}`));
+            }
+            runTmux(['kill-session', '-t', params.session]);
+            return successResponse({
+                killed: params.session,
+                message: `Session "${params.session}" terminated`,
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    });
+}