@proletariat/cli 0.3.34 → 0.3.36

package/dist/commands/work/status.js

@@ -0,0 +1,60 @@
+import { PMOCommand, pmoBaseFlags } from '../../lib/pmo/index.js';
+import { styles, formatPriority } from '../../lib/styles.js';
+import { shouldOutputJson, outputSuccessAsJson, createMetadata, } from '../../lib/prompt-json.js';
+export default class WorkStatus extends PMOCommand {
+    static description = 'Show current work status (in-progress tickets)';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> --json',
+    ];
+    static flags = {
+        ...pmoBaseFlags,
+    };
+    getPMOOptions() {
+        return { promptIfMultiple: false };
+    }
+    async execute() {
+        const { flags } = await this.parse(WorkStatus);
+        const projectId = flags.project;
+        const jsonMode = shouldOutputJson(flags);
+        // List all tickets, optionally filtered by project
+        const tickets = await this.storage.listTickets(projectId, { allProjects: !projectId });
+        const inProgress = tickets.filter(t => t.statusCategory === 'started' && t.assignee);
+        if (jsonMode) {
+            outputSuccessAsJson({
+                inProgressCount: inProgress.length,
+                tickets: inProgress.map(t => ({
+                    id: t.id,
+                    title: t.title,
+                    assignee: t.assignee,
+                    statusName: t.statusName,
+                    priority: t.priority,
+                    projectId: t.projectId,
+                    branch: t.branch,
+                })),
+            }, createMetadata('work status', flags));
+            return;
+        }
+        // Interactive mode
+        if (inProgress.length === 0) {
+            this.log(styles.info('No in-progress work found.'));
+            return;
+        }
+        this.log(styles.title(`\nWork In Progress (${inProgress.length})`));
+        this.log(styles.muted('─'.repeat(60)));
+        for (const ticket of inProgress) {
+            const priority = formatPriority(ticket.priority);
+            this.log(`  ${styles.code(ticket.id)} ${ticket.title} ${priority}`);
+            const details = [
+                ticket.assignee ? `Assignee: ${ticket.assignee}` : null,
+                ticket.statusName ? `Status: ${ticket.statusName}` : null,
+                ticket.projectId ? `Project: ${ticket.projectId}` : null,
+                ticket.branch ? `Branch: ${ticket.branch}` : null,
+            ].filter(Boolean).join(' | ');
+            if (details) {
+                this.log(styles.muted(`     ${details}`));
+            }
+        }
+        this.log('');
+    }
+}

package/dist/commands/workflow/index.js

@@ -1,5 +1,6 @@
 import { Flags } from '@oclif/core';
 import { PMOCommand, pmoBaseFlags } from '../../lib/pmo/index.js';
+import { shouldOutputJson } from '../../lib/prompt-json.js';
 import { styles } from '../../lib/styles.js';
 export default class Workflow extends PMOCommand {
     static description = 'List all available workflows (alias for workflow list)';
@@ -31,7 +32,7 @@ export default class Workflow extends PMOCommand {
         if (flags.custom)
             filter.isBuiltin = false;
         const workflows = await this.storage.listWorkflows(Object.keys(filter).length > 0 ? filter : undefined);
-        if (flags.json || flags.machine) {
+        if (shouldOutputJson(flags)) {
             this.log(JSON.stringify(workflows, null, 2));
             return;
         }

package/dist/commands/workflow/show.d.ts

@@ -0,0 +1,13 @@
+import WorkflowView from './view.js';
+export default class WorkflowShow extends WorkflowView {
+    static description: string;
+    static hidden: boolean;
+    static args: {
+        id: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        machine: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        project: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+}

package/dist/commands/workflow/show.js

@@ -0,0 +1,16 @@
+import { Args } from '@oclif/core';
+import { pmoBaseFlags } from '../../lib/pmo/index.js';
+import WorkflowView from './view.js';
+export default class WorkflowShow extends WorkflowView {
+    static description = 'View details of a workflow (alias for workflow view)';
+    static hidden = true;
+    static args = {
+        id: Args.string({
+            description: 'Workflow ID - prompts with dropdown if not provided',
+            required: false,
+        }),
+    };
+    static flags = {
+        ...pmoBaseFlags,
+    };
+}

package/dist/commands/workspace/add.js

@@ -4,6 +4,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { registerWorkspace, normalizePath, isWorkspaceRegistered, getWorkspaceNameFromPath, } from '../../lib/machine-config.js';
 import { machineOutputFlags } from '../../lib/pmo/index.js';
+import { shouldOutputJson } from '../../lib/prompt-json.js';
 export default class WorkspaceAdd extends Command {
     static description = 'Register an existing workspace in the machine config';
     static examples = [
@@ -26,6 +27,7 @@ export default class WorkspaceAdd extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(WorkspaceAdd);
+        const jsonMode = shouldOutputJson(flags);
         // Normalize the path
         const workspacePath = normalizePath(args.path);
         // Check if path exists
@@ -56,6 +58,10 @@ export default class WorkspaceAdd extends Command {
         }
         // Check if already registered
         if (isWorkspaceRegistered(workspacePath)) {
+            if (jsonMode) {
+                this.log(JSON.stringify({ type: 'success', result: { path: workspacePath, status: 'already_registered' } }));
+                return;
+            }
             this.log(chalk.yellow(`Workspace is already registered: ${workspacePath}`));
             this.log(chalk.gray('Use "prlt workspace use" to set it as active.'));
             return;
@@ -65,11 +71,20 @@ export default class WorkspaceAdd extends Command {
         // Register the workspace
         try {
             const entry = registerWorkspace(workspacePath, workspaceName, true);
+            if (jsonMode) {
+                this.log(JSON.stringify({ type: 'success', result: { name: entry.name, path: entry.path, registeredAt: entry.registeredAt, status: 'registered' } }));
+                return;
+            }
             this.log(chalk.green(`Registered workspace: ${entry.name}`));
             this.log(chalk.gray(`  Path: ${entry.path}`));
             this.log(chalk.gray(`  Registered at: ${entry.registeredAt}`));
         }
         catch (error) {
+            if (jsonMode) {
+                this.log(JSON.stringify({ type: 'error', error: { code: 'REGISTER_FAILED', message: error.message } }));
+                this.exit(1);
+                return;
+            }
             this.error(`Failed to register workspace: ${error.message}`);
         }
     }

package/dist/commands/workspace/list.js

@@ -5,6 +5,7 @@ import { machineOutputFlags } from '../../lib/pmo/index.js';
 import { getRegisteredWorkspaces, getActiveWorkspace, } from '../../lib/machine-config.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { shouldOutputJson } from '../../lib/prompt-json.js';
 export default class WorkspaceList extends Command {
     static description = 'List all registered and discovered HQ workspaces';
     static examples = [
@@ -78,7 +79,7 @@ export default class WorkspaceList extends Command {
             });
         }
         // JSON output
-        if (flags.json || flags.machine) {
+        if (shouldOutputJson(flags)) {
             const output = {
                 workspaces: workspaces.map((w) => ({
                     name: w.name,

package/dist/commands/workspace/prune.js

@@ -5,7 +5,7 @@ import { PromptCommand } from '../../lib/prompt-command.js';
 import { styles } from '../../lib/styles.js';
 import { getRegisteredHeadquarters, unregisterHeadquarters, } from '../../lib/machine-config.js';
 import { getWorkspaceAgents, removeAgentsFromDatabase, getDatabasePath, } from '../../lib/database/index.js';
-import { outputConfirmationNeededAsJson, createMetadata, } from '../../lib/prompt-json.js';
+import { outputConfirmationNeededAsJson, createMetadata, shouldOutputJson, isNonTTY, } from '../../lib/prompt-json.js';
 import { machineOutputFlags } from '../../lib/pmo/index.js';
 export default class WorkspacePrune extends PromptCommand {
     static description = 'Remove stale workspace entries and agents with deleted worktrees';
@@ -31,14 +31,14 @@ export default class WorkspacePrune extends PromptCommand {
         const { flags } = await this.parse(WorkspacePrune);
         // In non-TTY mode without --json (CI, scripts, piped), default to dry-run unless --force is set.
         // In --json mode, we use confirmation_needed output instead of auto-dry-run so agents can review and confirm.
-        const isNonTTY = !process.stdout.isTTY;
-        const effectiveDryRun = flags['dry-run'] || (!(flags.json || flags.machine) && isNonTTY && !flags.force);
+        const nonTTY = isNonTTY();
+        const effectiveDryRun = flags['dry-run'] || (!shouldOutputJson(flags) && nonTTY && !flags.force);
         // Find stale entries
         const staleWorkspaces = this.findStaleWorkspaces();
         const staleAgents = this.findStaleAgents();
         const totalStale = staleWorkspaces.length + staleAgents.length;
         // JSON output
-        if (flags.json || flags.machine) {
+        if (shouldOutputJson(flags)) {
             const output = {
                 dryRun: effectiveDryRun,
                 staleWorkspaces: staleWorkspaces.map(w => ({
@@ -112,7 +112,7 @@ export default class WorkspacePrune extends PromptCommand {
                 this.log(styles.muted(`  • ${staleAgents.length} agent record(s)`));
             }
             this.log('');
-            if (isNonTTY) {
+            if (nonTTY) {
                 this.log(styles.muted('Non-TTY environment detected. Run with --force to remove these entries.'));
             }
             else {

package/dist/lib/branch/index.d.ts

@@ -84,6 +84,7 @@ export interface BranchInfo {
     agent?: string;
     description?: string;
     tracking?: string;
+    repo?: string;
 }
 /**
  * Get current branch name.

package/dist/lib/database/index.d.ts

@@ -52,7 +52,7 @@ export interface AgentWorktree {
     is_clean: boolean;
     last_checked?: string;
 }
-export declare const CREATE_TABLES_SQL = "\n-- Core workspace metadata\nCREATE TABLE IF NOT EXISTS workspace (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  type TEXT NOT NULL CHECK (type IN ('hq', 'workspace')),\n  workspace_name TEXT NOT NULL,\n  has_pmo BOOLEAN DEFAULT FALSE,\n  active_theme_id TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (active_theme_id) REFERENCES agent_themes(id) ON DELETE SET NULL\n);\n\n-- Repository management\nCREATE TABLE IF NOT EXISTS repositories (\n  name TEXT PRIMARY KEY,\n  path TEXT NOT NULL,\n  type TEXT DEFAULT 'main' CHECK (type IN ('main', 'dependency')),\n  source_url TEXT,\n  action TEXT CHECK (action IN ('clone', 'move', 'link')),\n  added_at TEXT NOT NULL\n);\n\n-- Agent naming themes (optional)\nCREATE TABLE IF NOT EXISTS agent_themes (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL UNIQUE,\n  display_name TEXT NOT NULL,\n  description TEXT,\n  builtin BOOLEAN DEFAULT FALSE,\n  created_at TEXT NOT NULL\n);\n\n-- Names available within each theme\nCREATE TABLE IF NOT EXISTS agent_theme_names (\n  theme_id TEXT NOT NULL,\n  name TEXT NOT NULL,\n  PRIMARY KEY (theme_id, name),\n  FOREIGN KEY (theme_id) REFERENCES agent_themes(id) ON DELETE CASCADE\n);\n\n-- Agent instances in workspace\nCREATE TABLE IF NOT EXISTS agents (\n  name TEXT PRIMARY KEY,\n  type TEXT NOT NULL DEFAULT 'persistent' CHECK (type IN ('persistent', 'ephemeral')),\n  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'cleaned')),\n  base_name TEXT,\n  theme_id TEXT,\n  worktree_path TEXT,\n  mount_mode TEXT NOT NULL DEFAULT 'worktree' CHECK (mount_mode IN ('worktree', 'clone')),\n  created_at TEXT NOT NULL,\n  cleaned_at TEXT,\n  FOREIGN KEY (theme_id) REFERENCES agent_themes(id) ON DELETE SET NULL\n);\n\n-- Agent-owned worktrees\nCREATE TABLE IF NOT EXISTS agent_worktrees (\n  agent_name TEXT NOT NULL,\n  repo_name TEXT NOT NULL,\n  worktree_path TEXT NOT NULL,\n  branch TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  PRIMARY KEY (agent_name, repo_name),\n  FOREIGN KEY (agent_name) REFERENCES agents(name) ON DELETE CASCADE,\n  FOREIGN KEY (repo_name) REFERENCES repositories(name) ON DELETE CASCADE\n);\n\n-- Workspace-level settings (key-value store)\nCREATE TABLE IF NOT EXISTS workspace_settings (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\n-- =============================================================================\n-- Indexes\n-- =============================================================================\n\nCREATE INDEX IF NOT EXISTS idx_worktrees_agent ON agent_worktrees(agent_name);\nCREATE INDEX IF NOT EXISTS idx_worktrees_repo ON agent_worktrees(repo_name);\nCREATE INDEX IF NOT EXISTS idx_theme_names_theme ON agent_theme_names(theme_id);\nCREATE INDEX IF NOT EXISTS idx_agents_theme ON agents(theme_id);\n";
+export declare const CREATE_TABLES_SQL = "\n-- Core workspace metadata\nCREATE TABLE IF NOT EXISTS workspace (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  type TEXT NOT NULL CHECK (type IN ('hq', 'workspace')),\n  workspace_name TEXT NOT NULL,\n  has_pmo BOOLEAN DEFAULT FALSE,\n  active_theme_id TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (active_theme_id) REFERENCES agent_themes(id) ON DELETE SET NULL\n);\n\n-- Repository management\nCREATE TABLE IF NOT EXISTS repositories (\n  name TEXT PRIMARY KEY,\n  path TEXT NOT NULL,\n  type TEXT DEFAULT 'main' CHECK (type IN ('main', 'dependency')),\n  source_url TEXT,\n  action TEXT CHECK (action IN ('clone', 'move', 'link')),\n  added_at TEXT NOT NULL\n);\n\n-- Agent naming themes (optional)\nCREATE TABLE IF NOT EXISTS agent_themes (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL UNIQUE,\n  display_name TEXT NOT NULL,\n  description TEXT,\n  builtin BOOLEAN DEFAULT FALSE,\n  created_at TEXT NOT NULL\n);\n\n-- Names available within each theme\nCREATE TABLE IF NOT EXISTS agent_theme_names (\n  theme_id TEXT NOT NULL,\n  name TEXT NOT NULL,\n  PRIMARY KEY (theme_id, name),\n  FOREIGN KEY (theme_id) REFERENCES agent_themes(id) ON DELETE CASCADE\n);\n\n-- Agent instances in workspace\nCREATE TABLE IF NOT EXISTS agents (\n  name TEXT PRIMARY KEY,\n  type TEXT NOT NULL DEFAULT 'persistent' CHECK (type IN ('persistent', 'ephemeral')),\n  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'cleaned')),\n  base_name TEXT,\n  theme_id TEXT,\n  worktree_path TEXT,\n  mount_mode TEXT NOT NULL DEFAULT 'worktree' CHECK (mount_mode IN ('worktree', 'clone')),\n  created_at TEXT NOT NULL,\n  cleaned_at TEXT,\n  FOREIGN KEY (theme_id) REFERENCES agent_themes(id) ON DELETE SET NULL\n);\n\n-- Agent-owned worktrees\nCREATE TABLE IF NOT EXISTS agent_worktrees (\n  agent_name TEXT NOT NULL,\n  repo_name TEXT NOT NULL,\n  worktree_path TEXT NOT NULL,\n  branch TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  last_commit_hash TEXT,\n  commits_ahead INTEGER NOT NULL DEFAULT 0,\n  is_clean INTEGER NOT NULL DEFAULT 1,\n  last_checked TEXT,\n  PRIMARY KEY (agent_name, repo_name),\n  FOREIGN KEY (agent_name) REFERENCES agents(name) ON DELETE CASCADE,\n  FOREIGN KEY (repo_name) REFERENCES repositories(name) ON DELETE CASCADE\n);\n\n-- Workspace-level settings (key-value store)\nCREATE TABLE IF NOT EXISTS workspace_settings (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\n-- =============================================================================\n-- Indexes\n-- =============================================================================\n\nCREATE INDEX IF NOT EXISTS idx_worktrees_agent ON agent_worktrees(agent_name);\nCREATE INDEX IF NOT EXISTS idx_worktrees_repo ON agent_worktrees(repo_name);\nCREATE INDEX IF NOT EXISTS idx_theme_names_theme ON agent_theme_names(theme_id);\nCREATE INDEX IF NOT EXISTS idx_agents_theme ON agents(theme_id);\n";
 /**
  * Get the database path for a workspace
  */

package/dist/lib/database/index.js

@@ -64,6 +64,10 @@ CREATE TABLE IF NOT EXISTS agent_worktrees (
   worktree_path TEXT NOT NULL,
   branch TEXT NOT NULL,
   created_at TEXT NOT NULL,
+  last_commit_hash TEXT,
+  commits_ahead INTEGER NOT NULL DEFAULT 0,
+  is_clean INTEGER NOT NULL DEFAULT 1,
+  last_checked TEXT,
   PRIMARY KEY (agent_name, repo_name),
   FOREIGN KEY (agent_name) REFERENCES agents(name) ON DELETE CASCADE,
   FOREIGN KEY (repo_name) REFERENCES repositories(name) ON DELETE CASCADE
@@ -184,6 +188,22 @@ export function openWorkspaceDatabase(workspacePath) {
     catch {
         // Ignore migration errors - table might not exist yet
     }
+    // Migration: add missing columns to agent_worktrees table (TKT-1014)
+    try {
+        const worktreesTableExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='agent_worktrees'").get();
+        if (worktreesTableExists) {
+            const worktreeTableInfo = db.prepare("PRAGMA table_info(agent_worktrees)").all();
+            if (!worktreeTableInfo.some(col => col.name === 'commits_ahead')) {
+                db.exec("ALTER TABLE agent_worktrees ADD COLUMN last_commit_hash TEXT");
+                db.exec("ALTER TABLE agent_worktrees ADD COLUMN commits_ahead INTEGER NOT NULL DEFAULT 0");
+                db.exec("ALTER TABLE agent_worktrees ADD COLUMN is_clean INTEGER NOT NULL DEFAULT 1");
+                db.exec("ALTER TABLE agent_worktrees ADD COLUMN last_checked TEXT");
+            }
+        }
+    }
+    catch {
+        // Ignore migration errors - table might not exist yet or columns already exist
+    }
     // Migration: add mount_mode column to agents table (TKT-686)
     try {
         const agentsTableInfo = db.prepare("PRAGMA table_info(agents)").all();

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/devcontainer.js

@@ -96,7 +96,9 @@ export function generateDevcontainerJson(options, config) {
         mounts,
         containerEnv: {
             DEVCONTAINER: 'true',
-            ANTHROPIC_API_KEY: '${localEnv:ANTHROPIC_API_KEY}',
+            // NOTE: ANTHROPIC_API_KEY is intentionally NOT passed by default.
+            // Claude Code prefers API key over OAuth, so passing it would cause agents
+            // to burn API credits instead of using Max subscription via OAuth.
             // GH_TOKEN enables gh CLI in container (for PR creation, etc.)
             GH_TOKEN: '${localEnv:GH_TOKEN}',
             GITHUB_TOKEN: '${localEnv:GITHUB_TOKEN}',

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

@@ -41,13 +41,29 @@ 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.
  */
 export declare function credentialsVolumeExists(): boolean;
 /**
- * Check if valid Claude credentials exist in the Docker volume.
- * Returns true if credentials exist and are not expired.
+ * Check if valid Claude OAuth credentials exist in the Docker volume.
+ * Returns true if OAuth credentials are stored (even if access token is expired,
+ * since Claude Code handles refresh internally using stored refresh tokens).
+ *
+ * NOTE: This intentionally does NOT check for ANTHROPIC_API_KEY. If the user
+ * has an API key but no OAuth credentials, we want to prompt them to set up
+ * OAuth (which uses their Max subscription) rather than silently burning API credits.
  */
 export declare function dockerCredentialsExist(): boolean;
 /**

package/dist/lib/execution/runners.js

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- runner implementations require cohesive logic */
 /**
  * Execution Runners
  *
@@ -86,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';
@@ -102,19 +144,23 @@ export function credentialsVolumeExists() {
     }
 }
 /**
- * Check if valid Claude credentials exist in the Docker volume.
- * Returns true if credentials exist and are not expired.
+ * Check if valid Claude OAuth credentials exist in the Docker volume.
+ * Returns true if OAuth credentials are stored (even if access token is expired,
+ * since Claude Code handles refresh internally using stored refresh tokens).
+ *
+ * NOTE: This intentionally does NOT check for ANTHROPIC_API_KEY. If the user
+ * has an API key but no OAuth credentials, we want to prompt them to set up
+ * OAuth (which uses their Max subscription) rather than silently burning API credits.
  */
 export function dockerCredentialsExist() {
     try {
         const result = execSync(`docker run --rm -v ${CLAUDE_CREDENTIALS_VOLUME}:/data alpine cat /data/.credentials.json 2>/dev/null`, { stdio: 'pipe', encoding: 'utf-8' });
         const creds = JSON.parse(result);
-        if (creds.claudeAiOauth?.accessToken && creds.claudeAiOauth?.expiresAt) {
-            // Check if expired
-            const expiresAt = creds.claudeAiOauth.expiresAt;
-            if (expiresAt > Date.now()) {
-                return true;
-            }
+        // Check if OAuth credentials exist. Don't check expiration because
+        // access tokens are short-lived but Claude Code handles token refresh
+        // internally using stored refresh tokens.
+        if (creds.claudeAiOauth?.accessToken) {
+            return true;
         }
         return false;
     }
@@ -735,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.
@@ -767,7 +813,10 @@ function createDockerContainer(context, containerName, imageName, config) {
         `-e PRLT_HQ_PATH=/hq`,
         `-e PRLT_AGENT_NAME="${context.agentName}"`,
         `-e PRLT_HOST_PATH="${context.agentDir}"`,
-        ...(process.env.ANTHROPIC_API_KEY ? [`-e ANTHROPIC_API_KEY="${process.env.ANTHROPIC_API_KEY}"`] : []),
+        // Only pass ANTHROPIC_API_KEY if the user explicitly chose to use it (no OAuth creds).
+        // Claude Code prefers API key over OAuth, so passing it would cause agents to burn
+        // API credits instead of using Max subscription.
+        ...(context.useApiKey && process.env.ANTHROPIC_API_KEY ? [`-e ANTHROPIC_API_KEY="${process.env.ANTHROPIC_API_KEY}"`] : []),
         ...(process.env.GITHUB_TOKEN ? [`-e GITHUB_TOKEN="${process.env.GITHUB_TOKEN}"`] : []),
         ...(process.env.GH_TOKEN ? [`-e GH_TOKEN="${process.env.GH_TOKEN}"`] : []),
         // NOTE: Do NOT pass CLAUDE_CODE_OAUTH_TOKEN - it overrides credentials file
@@ -786,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,
@@ -890,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
@@ -919,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);
@@ -1097,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,
@@ -1448,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.
@@ -1509,7 +1551,7 @@ exec bash
             try {
                 execSync(`docker exec ${actualContainerId} tmux has-session -t "${sessionName}" 2>&1`, { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
             }
-            catch (err) {
+            catch {
                 return {
                     success: false,
                     error: `Failed to verify tmux session "${sessionName}" inside container. The session may not have started correctly.`,

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.