@proletariat/cli 0.3.35 → 0.3.40

package/dist/lib/database/index.js

@@ -424,29 +424,56 @@ export function addAgentsToDatabase(workspacePath, agentNames, themeId, mountMod
     db.close();
 }
 /**
- * Add an ephemeral agent to the database
+ * Add an ephemeral agent to the database.
+ * Throws on name collision — use tryAddEphemeralAgentToDatabase for
+ * concurrency-safe insertion with conflict detection.
  */
 export function addEphemeralAgentToDatabase(workspacePath, agentName, baseName, themeId, mountMode = 'worktree') {
+    const result = tryAddEphemeralAgentToDatabase(workspacePath, agentName, baseName, themeId, mountMode);
+    if (!result) {
+        throw new Error(`Agent name "${agentName}" already exists (UNIQUE constraint failed: agents.name)`);
+    }
+    return result;
+}
+/**
+ * Try to add an ephemeral agent to the database.
+ * Returns the Agent on success, or null if the name already exists
+ * (SQLITE_CONSTRAINT_PRIMARYKEY). This is concurrency-safe: parallel
+ * processes that generate the same name will not crash — the loser
+ * simply gets null and can retry with a different name.
+ */
+export function tryAddEphemeralAgentToDatabase(workspacePath, agentName, baseName, themeId, mountMode = 'worktree') {
     const db = openWorkspaceDatabase(workspacePath);
-    const now = new Date().toISOString();
-    const worktreePath = `agents/temp/${agentName}`;
-    db.prepare(`
-    INSERT INTO agents (name, type, status, base_name, theme_id, worktree_path, mount_mode, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(agentName, 'ephemeral', 'active', baseName, themeId || null, worktreePath, mountMode, now);
-    const agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(agentName);
-    db.close();
-    return {
-        name: agent.name,
-        type: agent.type,
-        status: agent.status,
-        base_name: agent.base_name,
-        theme_id: agent.theme_id,
-        worktree_path: agent.worktree_path,
-        mount_mode: (agent.mount_mode || 'clone'),
-        created_at: agent.created_at,
-        cleaned_at: agent.cleaned_at,
-    };
+    try {
+        const now = new Date().toISOString();
+        const worktreePath = `agents/temp/${agentName}`;
+        db.prepare(`
+      INSERT INTO agents (name, type, status, base_name, theme_id, worktree_path, mount_mode, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(agentName, 'ephemeral', 'active', baseName, themeId || null, worktreePath, mountMode, now);
+        const agent = db.prepare('SELECT * FROM agents WHERE name = ?').get(agentName);
+        return {
+            name: agent.name,
+            type: agent.type,
+            status: agent.status,
+            base_name: agent.base_name,
+            theme_id: agent.theme_id,
+            worktree_path: agent.worktree_path,
+            mount_mode: (agent.mount_mode || 'clone'),
+            created_at: agent.created_at,
+            cleaned_at: agent.cleaned_at,
+        };
+    }
+    catch (err) {
+        const sqliteErr = err;
+        if (sqliteErr.code === 'SQLITE_CONSTRAINT_PRIMARYKEY' || sqliteErr.code === 'SQLITE_CONSTRAINT_UNIQUE') {
+            return null;
+        }
+        throw err;
+    }
+    finally {
+        db.close();
+    }
 }
 /**
  * Get all ephemeral agent names from the database
@@ -669,6 +696,34 @@ export function getAgentWorktrees(workspacePath, agentName) {
     db.close();
     return worktrees;
 }
+/**
+ * Find agent worktrees matching a branch pattern (case-insensitive LIKE).
+ */
+export function findWorktreesByBranch(workspacePath, branchPattern) {
+    const db = openWorkspaceDatabase(workspacePath);
+    const worktrees = db.prepare('SELECT * FROM agent_worktrees WHERE LOWER(branch) LIKE ?').all(branchPattern);
+    db.close();
+    return worktrees;
+}
+/**
+ * Get agent worktrees for a specific repository.
+ */
+export function getWorktreesForRepo(workspacePath, repoName) {
+    const db = openWorkspaceDatabase(workspacePath);
+    const worktrees = db.prepare('SELECT agent_name, is_clean, commits_ahead, branch FROM agent_worktrees WHERE repo_name = ?').all(repoName);
+    db.close();
+    return worktrees;
+}
+/**
+ * Upsert a workspace setting (key-value pair).
+ */
+export function upsertWorkspaceSetting(db, key, value) {
+    db.prepare(`
+    INSERT INTO workspace_settings (key, value)
+    VALUES (?, ?)
+    ON CONFLICT(key) DO UPDATE SET value = excluded.value
+  `).run(key, value);
+}
 /**
  * Remove agents from database
  */
@@ -685,6 +740,69 @@ export function removeAgentsFromDatabase(workspacePath, agentNames) {
     db.close();
 }
 // =============================================================================
+// PMO Bootstrapping Operations
+// =============================================================================
+/**
+ * Check if PMO tables exist and get basic stats.
+ * Used by pmo init to detect existing PMO before storage layer is available.
+ */
+export function checkPMOExists(dbPath) {
+    const db = new Database(dbPath);
+    try {
+        const result = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='pmo_projects'").get();
+        if (result === undefined) {
+            return { exists: false, projectCount: 0, ticketCount: 0 };
+        }
+        const projectCountResult = db.prepare('SELECT COUNT(*) as count FROM pmo_projects').get();
+        const ticketCountResult = db.prepare('SELECT COUNT(*) as count FROM pmo_tickets').get();
+        return {
+            exists: true,
+            projectCount: projectCountResult.count,
+            ticketCount: ticketCountResult.count,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Get a PMO setting from the pmo_settings table.
+ * Used for bootstrapping queries before storage layer is available.
+ */
+export function getPMOSetting(dbPath, key) {
+    const db = new Database(dbPath);
+    try {
+        const result = db.prepare('SELECT value FROM pmo_settings WHERE key = ?').get(key);
+        return result?.value ?? null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Drop PMO tables from the database.
+ * Used during PMO reinitialization.
+ */
+export function dropPMOTables(dbPath, tables) {
+    const db = new Database(dbPath);
+    try {
+        for (const table of tables) {
+            try {
+                db.prepare(`DROP TABLE IF EXISTS ${table}`).run();
+            }
+            catch {
+                // Ignore errors - table might not exist
+            }
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+// =============================================================================
 // Theme CRUD Operations
 // =============================================================================
 /**

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.
  */
@@ -63,6 +74,40 @@ export declare function getDockerCredentialInfo(): {
     expiresAt: Date;
     subscriptionType?: string;
 } | null;
+/**
+ * Preflight result indicating whether the executor is ready to run.
+ */
+export interface PreflightResult {
+    ok: boolean;
+    error?: string;
+}
+/**
+ * Check if an executor binary is available on the host.
+ * Returns a PreflightResult with ok=true if the binary is found,
+ * or ok=false with a descriptive error and remediation hint.
+ */
+export declare function checkExecutorOnHost(executor: ExecutorType): PreflightResult;
+/**
+ * Check if an executor binary is available inside a Docker container.
+ * Returns a PreflightResult with ok=true if the binary is found,
+ * or ok=false with a descriptive error and remediation hint.
+ */
+export declare function checkExecutorInContainer(executor: ExecutorType, containerId: string): PreflightResult;
+/**
+ * Run preflight checks for a given execution environment and executor.
+ * Validates that the executor binary is available before spawning.
+ *
+ * Checks performed per environment:
+ * - host: Verify binary on PATH
+ * - devcontainer: Verify binary inside container (if container running)
+ * - docker: Verify binary on host (used in docker run command)
+ * - vm: Verify binary on host (will be checked on remote separately)
+ */
+export declare function runExecutorPreflight(executor: ExecutorType, environment: ExecutionEnvironment, containerId?: string): PreflightResult;
+export declare function getExecutorCommand(executor: ExecutorType, prompt: string, skipPermissions?: boolean): {
+    cmd: string;
+    args: string[];
+};
 export interface RunnerResult {
     success: boolean;
     pid?: string;

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';
@@ -147,10 +188,125 @@ export function getDockerCredentialInfo() {
         return null;
     }
 }
+/**
+ * Get the binary name for an executor type.
+ */
+function getExecutorBinary(executor) {
+    switch (executor) {
+        case 'claude-code':
+            return 'claude';
+        case 'codex':
+            return 'codex';
+        case 'aider':
+            return 'aider';
+        case 'custom':
+            return 'echo'; // placeholder
+        default:
+            return 'claude';
+    }
+}
+/**
+ * Get install/setup hints for a missing executor binary.
+ */
+function getExecutorRemediationHint(executor) {
+    switch (executor) {
+        case 'claude-code':
+            return 'Install Claude Code: npm install -g @anthropic-ai/claude-code\n' +
+                '  Then authenticate: claude login';
+        case 'codex':
+            return 'Install Codex: npm install -g @openai/codex\n' +
+                '  Then authenticate: set OPENAI_API_KEY or run codex --login';
+        case 'aider':
+            return 'Install aider: pip install aider-chat\n' +
+                '  Then authenticate: set OPENAI_API_KEY or ANTHROPIC_API_KEY';
+        case 'custom':
+            return 'Configure a custom executor command in your execution settings.';
+        default:
+            return 'Install the required executor and ensure it is on your PATH.';
+    }
+}
+/**
+ * Check if an executor binary is available on the host.
+ * Returns a PreflightResult with ok=true if the binary is found,
+ * or ok=false with a descriptive error and remediation hint.
+ */
+export function checkExecutorOnHost(executor) {
+    const binary = getExecutorBinary(executor);
+    try {
+        execSync(`${binary} --version`, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            timeout: 10000,
+        });
+        return { ok: true };
+    }
+    catch {
+        return {
+            ok: false,
+            error: `Executor "${executor}" not found: "${binary}" is not installed or not on PATH.\n\n` +
+                `Remediation:\n  ${getExecutorRemediationHint(executor)}`,
+        };
+    }
+}
+/**
+ * Check if an executor binary is available inside a Docker container.
+ * Returns a PreflightResult with ok=true if the binary is found,
+ * or ok=false with a descriptive error and remediation hint.
+ */
+export function checkExecutorInContainer(executor, containerId) {
+    const binary = getExecutorBinary(executor);
+    try {
+        execSync(`docker exec ${containerId} which ${binary}`, {
+            stdio: 'pipe',
+            timeout: 10000,
+        });
+        return { ok: true };
+    }
+    catch {
+        return {
+            ok: false,
+            error: `Executor "${executor}" not found in container ${containerId}: "${binary}" is not installed.\n\n` +
+                `Remediation:\n  Ensure "${binary}" is installed in the devcontainer image.\n  ` +
+                getExecutorRemediationHint(executor),
+        };
+    }
+}
+/**
+ * Run preflight checks for a given execution environment and executor.
+ * Validates that the executor binary is available before spawning.
+ *
+ * Checks performed per environment:
+ * - host: Verify binary on PATH
+ * - devcontainer: Verify binary inside container (if container running)
+ * - docker: Verify binary on host (used in docker run command)
+ * - vm: Verify binary on host (will be checked on remote separately)
+ */
+export function runExecutorPreflight(executor, environment, containerId) {
+    switch (environment) {
+        case 'host':
+            return checkExecutorOnHost(executor);
+        case 'devcontainer':
+            // For devcontainer, check inside the container if it's already running
+            if (containerId) {
+                return checkExecutorInContainer(executor, containerId);
+            }
+            // Container not yet running - will be checked after container start
+            return { ok: true };
+        case 'docker':
+            // Docker runner builds the command on host, executor runs inside container
+            // Can't check until container is created, so skip for now
+            return { ok: true };
+        case 'vm':
+            // VM executor runs remotely - can't check from host
+            // Could add SSH-based check in the future
+            return { ok: true };
+        default:
+            return { ok: true };
+    }
+}
 // =============================================================================
 // Executor Commands
 // =============================================================================
-function getExecutorCommand(executor, prompt, skipPermissions = true) {
+export function getExecutorCommand(executor, prompt, skipPermissions = true) {
     switch (executor) {
         case 'claude-code':
             if (skipPermissions) {
@@ -740,7 +896,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 +950,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 +1058,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 +1087,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,13 +1265,21 @@ 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,
                 error: 'Failed to start Docker container. Check Docker logs for details.',
             };
         }
+        // Executor preflight check (TKT-1082): verify executor binary is available inside container
+        const preflight = checkExecutorInContainer(executor, containerId);
+        if (!preflight.ok) {
+            return {
+                success: false,
+                error: preflight.error,
+            };
+        }
         // Write prompt to file in worktree (accessible by container)
         const { hostPath: promptHostPath, containerPath: promptFile } = writePromptFile(context);
         // Inject fresh GitHub token into container (containers may be reused with stale/empty tokens)
@@ -1456,21 +1624,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.
@@ -1740,6 +1897,8 @@ exec $SHELL
 export async function runDocker(context, executor, config) {
     const prompt = buildPrompt(context);
     const containerName = `work-${context.ticketId}-${Date.now()}`;
+    // Get the correct executor command (claude, codex, aider, etc.)
+    const { cmd, args } = getExecutorCommand(executor, prompt, !config.sandboxed);
     try {
         // Check if docker is available
         execSync('which docker', { stdio: 'pipe' });
@@ -1764,10 +1923,10 @@ export async function runDocker(context, executor, config) {
         if (config.docker.cpus) {
             dockerCmd += ` --cpus ${config.docker.cpus}`;
         }
-        // Escape prompt for shell
-        const escapedPrompt = prompt.replace(/'/g, "'\\''");
+        // Build executor command with properly escaped args
+        const escapedArgs = args.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(' ');
         dockerCmd += ` ${config.docker.image}`;
-        dockerCmd += ` claude --print '${escapedPrompt}'`;
+        dockerCmd += ` ${cmd} ${escapedArgs}`;
         const containerId = execSync(dockerCmd, { encoding: 'utf-8' }).trim();
         return {
             success: true,
@@ -1796,6 +1955,8 @@ export async function runVm(context, executor, config, host) {
     const user = config.vm.user;
     const keyPath = config.vm.keyPath;
     const remoteWorkspace = `/workspace/${context.agentName}`;
+    // Get the correct executor command (claude, codex, aider, etc.)
+    const { cmd, args } = getExecutorCommand(executor, prompt, !config.sandboxed);
     try {
         // Build SSH options
         let sshOpts = '';
@@ -1817,9 +1978,9 @@ export async function runVm(context, executor, config, host) {
             const gitPullCmd = `cd ${remoteWorkspace} && git fetch && git checkout ${context.branch}`;
             execSync(`ssh ${sshOpts} ${user}@${targetHost} "${gitPullCmd}"`, { stdio: 'pipe' });
         }
-        // Execute on remote
-        const escapedPrompt = prompt.replace(/'/g, "'\\''");
-        const remoteCmd = `cd ${remoteWorkspace} && claude --print '${escapedPrompt}'`;
+        // Execute on remote using the correct executor
+        const escapedArgs = args.map(a => `'${a.replace(/'/g, "'\\''")}'`).join(' ');
+        const remoteCmd = `cd ${remoteWorkspace} && ${cmd} ${escapedArgs}`;
         const sshCmd = `ssh ${sshOpts} ${user}@${targetHost} "nohup ${remoteCmd} > /tmp/work-${context.ticketId}.log 2>&1 &"`;
         execSync(sshCmd, { stdio: 'pipe' });
         return {

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.
@@ -50,6 +60,11 @@ export declare function flattenContainerSessions(containerTmuxSessions: Map<stri
     sessionName: string;
     containerId: string;
 }>;
+/**
+ * Find container sessions using prefix matching.
+ * Handles short vs full container ID mismatches between DB records and docker output.
+ */
+export declare function findContainerSessionsByPrefix(containerTmuxSessions: Map<string, string[]>, containerId: string): 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