@proletariat/cli 0.3.35 → 0.3.36

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

@@ -5,7 +5,7 @@
  * Uses the workspace_settings table (not pmo_settings - execution is workspace-level).
  */
 import Database from 'better-sqlite3';
-import { ExecutionConfig, TerminalApp, Shell, DisplayMode, OutputMode, ExecutionEnvironment } from './types.js';
+import { ExecutionConfig, TerminalApp, Shell, DisplayMode, OutputMode, ExecutionEnvironment, AuthMethod } from './types.js';
 import { type JsonFlags } from '../prompt-json.js';
 declare const CONFIG_KEYS: {
     terminalApp: string;
@@ -28,6 +28,7 @@ declare const CONFIG_KEYS: {
     vmKeyPath: string;
     vmSyncMethod: string;
     coderName: string;
+    authMethod: string;
 };
 /**
  * Load execution config from database, merging with defaults
@@ -55,6 +56,19 @@ export declare function saveTmuxControlMode(db: Database.Database, enabled: bool
  * When enabled, new terminal tabs open without stealing focus from current window.
  */
 export declare function saveTerminalOpenInBackground(db: Database.Database, enabled: boolean): void;
+/**
+ * Save auth method preference (oauth or apikey)
+ */
+export declare function saveAuthMethod(db: Database.Database, method: AuthMethod): void;
+/**
+ * Get saved auth method preference.
+ * Returns null if no preference has been saved (user should be prompted).
+ */
+export declare function getAuthMethod(db: Database.Database): AuthMethod | null;
+/**
+ * Clear saved auth method preference (will prompt again next time)
+ */
+export declare function clearAuthMethod(db: Database.Database): void;
 /**
  * Check if terminal app preference has been set
  */

package/dist/lib/execution/config.js

@@ -32,6 +32,7 @@ const CONFIG_KEYS = {
     vmKeyPath: 'execution.vm.key_path',
     vmSyncMethod: 'execution.vm.sync_method',
     coderName: 'coder.name',
+    authMethod: 'execution.auth_method',
 };
 /**
  * Get a setting value from the database
@@ -97,6 +98,11 @@ export function loadExecutionConfig(db) {
     if (sandboxed !== null) {
         config.sandboxed = sandboxed === 'true';
     }
+    // Load auth method preference
+    const authMethod = getSetting(db, CONFIG_KEYS.authMethod);
+    if (authMethod) {
+        config.authMethod = authMethod;
+    }
     // Load tmux settings
     const tmuxSession = getSetting(db, CONFIG_KEYS.tmuxSession);
     if (tmuxSession) {
@@ -178,6 +184,28 @@ export function saveTmuxControlMode(db, enabled) {
 export function saveTerminalOpenInBackground(db, enabled) {
     setSetting(db, CONFIG_KEYS.terminalOpenInBackground, enabled.toString());
 }
+/**
+ * Save auth method preference (oauth or apikey)
+ */
+export function saveAuthMethod(db, method) {
+    setSetting(db, CONFIG_KEYS.authMethod, method);
+}
+/**
+ * Get saved auth method preference.
+ * Returns null if no preference has been saved (user should be prompted).
+ */
+export function getAuthMethod(db) {
+    const value = getSetting(db, CONFIG_KEYS.authMethod);
+    if (value === 'oauth' || value === 'apikey')
+        return value;
+    return null;
+}
+/**
+ * Clear saved auth method preference (will prompt again next time)
+ */
+export function clearAuthMethod(db) {
+    db.prepare(`DELETE FROM ${SETTINGS_TABLE} WHERE key = ?`).run(CONFIG_KEYS.authMethod);
+}
 /**
  * Check if terminal app preference has been set
  */

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

@@ -41,6 +41,17 @@ export declare function buildTmuxAttachCommand(useControlMode: boolean, includeU
  */
 export declare function configureITermTmuxPreferences(mode: 'tab' | 'window'): void;
 export declare function configureITermTmuxWindowMode(mode: 'tab' | 'window'): void;
+/**
+ * Build the tmux script that runs inside the container.
+ * In background mode: kills PID 1 (sleep infinity) after Claude exits to stop/remove container.
+ * In terminal/foreground mode: drops into exec bash for user inspection.
+ */
+export declare function buildTmuxScript(sessionName: string, claudeCmd: string, displayMode: DisplayMode): string;
+/**
+ * Get the auto-remove flags for docker run based on display mode.
+ * Background mode containers get --rm so Docker removes them when they stop.
+ */
+export declare function getDockerAutoRemoveFlags(displayMode: DisplayMode): string[];
 /**
  * Check if the claude-credentials Docker volume exists.
  */

package/dist/lib/execution/runners.js

@@ -87,6 +87,47 @@ export function configureITermTmuxWindowMode(mode) {
     configureITermTmuxPreferences(mode);
 }
 // =============================================================================
+// Background Mode Cleanup Helpers (TKT-988)
+// =============================================================================
+/**
+ * Build the tmux script that runs inside the container.
+ * In background mode: kills PID 1 (sleep infinity) after Claude exits to stop/remove container.
+ * In terminal/foreground mode: drops into exec bash for user inspection.
+ */
+export function buildTmuxScript(sessionName, claudeCmd, displayMode) {
+    if (displayMode === 'background') {
+        return `#!/bin/bash
+export TERM=xterm-256color
+export COLORTERM=truecolor
+unset CI
+echo "🚀 Starting: ${sessionName}"
+echo ""
+${claudeCmd}
+echo ""
+echo "✅ Agent work complete. Cleaning up container..."
+kill 1
+`;
+    }
+    return `#!/bin/bash
+export TERM=xterm-256color
+export COLORTERM=truecolor
+unset CI
+echo "🚀 Starting: ${sessionName}"
+echo ""
+${claudeCmd}
+echo ""
+echo "✅ Agent work complete. Press Enter to close or run more commands."
+exec bash
+`;
+}
+/**
+ * Get the auto-remove flags for docker run based on display mode.
+ * Background mode containers get --rm so Docker removes them when they stop.
+ */
+export function getDockerAutoRemoveFlags(displayMode) {
+    return displayMode === 'background' ? ['--rm'] : [];
+}
+// =============================================================================
 // Docker Credential Helpers
 // =============================================================================
 const CLAUDE_CREDENTIALS_VOLUME = 'claude-credentials';
@@ -740,7 +781,7 @@ function imageExists(imageName) {
  * Create and start a Docker container for an agent.
  * Uses raw Docker commands instead of devcontainer CLI.
  */
-function createDockerContainer(context, containerName, imageName, config) {
+function createDockerContainer(context, containerName, imageName, config, displayMode = 'terminal') {
     // Build mount flags
     // KEY: Use a named Docker volume for Claude credentials - this is how devcontainer.json
     // was handling it. The volume persists across containers, so login once = logged in everywhere.
@@ -794,12 +835,16 @@ function createDockerContainer(context, containerName, imageName, config) {
         '--cap-add=NET_RAW', // For firewall setup
         // Note: After firewall is set up, the container is network-restricted
     ];
+    // Auto-remove container on stop for background mode (R5)
+    // Background containers should be cleaned up after work completes — nobody will attach to inspect
+    const autoRemoveFlags = getDockerAutoRemoveFlags(displayMode);
     try {
         const createCmd = [
             'docker run -d',
             `--name ${containerName}`,
             '--user node',
             '-w /workspace',
+            ...autoRemoveFlags,
             ...mounts,
             ...envVars,
             ...resourceFlags,
@@ -898,7 +943,7 @@ function runContainerSetup(containerId, sandboxed = true) {
  * Builds image and creates container if needed.
  * Returns the container ID if successful, null otherwise.
  */
-function ensureDockerContainer(context, config) {
+function ensureDockerContainer(context, config, displayMode = 'terminal') {
     const containerName = getContainerName(context.agentName);
     const imageName = getImageName(context.agentName);
     // Always create fresh container to ensure mounts are up-to-date
@@ -927,7 +972,7 @@ function ensureDockerContainer(context, config) {
     }
     // Create and start container
     console.debug(`[runners:docker] Creating container ${containerName}`);
-    if (!createDockerContainer(context, containerName, imageName, config)) {
+    if (!createDockerContainer(context, containerName, imageName, config, displayMode)) {
         return null;
     }
     const containerId = getContainerId(containerName);
@@ -1105,7 +1150,7 @@ export async function runDevcontainer(context, executor, config, displayMode = '
         copyClaudeCredentials(context.agentDir);
         // Start or reuse container using raw Docker commands
         // No devcontainer CLI required!
-        const containerId = ensureDockerContainer(context, config);
+        const containerId = ensureDockerContainer(context, config, displayMode);
         if (!containerId) {
             return {
                 success: false,
@@ -1456,21 +1501,10 @@ async function runDevcontainerInTmux(context, devcontainerCmd, config, displayMo
         // Extract the claude command from the devcontainer command
         const cmdMatch = devcontainerCmd.match(/bash -c '(.+)'$/);
         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 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 CI
-echo "🚀 Starting: ${sessionName}"
-echo ""
-${claudeCmd}
-echo ""
-echo "✅ Agent work complete. Press Enter to close or run more commands."
-exec bash
-`;
+        // Create a script inside the container that runs claude
+        // Background mode (R1): kills PID 1 to stop container after completion
+        // Terminal/foreground mode (R2): drops into exec bash for user inspection
+        const tmuxScript = buildTmuxScript(sessionName, claudeCmd, displayMode);
         const scriptPath = `/tmp/prlt-${sessionName}.sh`;
         // Write script and start tmux session inside container
         // IMPORTANT: We create the session with bash first, then send keys to run the script.

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

@@ -2,8 +2,18 @@
  * 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.
  */
+/**
+ * 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 declare function captureTmuxPane(sessionId: string, lines: number, containerId?: string): string | null;
 /**
  * Known action names used in session naming.
  * These are the actions defined in pmo/actions/ that may be used when spawning agents.

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.

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

@@ -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

@@ -215,9 +215,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 +231,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

@@ -112,6 +112,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 +120,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/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),