@proletariat/cli 0.3.47 → 0.3.49

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

@@ -1,8 +1,8 @@
 /**
  * Devcontainer Template Generator
  *
- * Generates .devcontainer/ configuration for agent sandboxed execution.
- * Uses a custom Dockerfile with network firewall for security sandboxing.
+ * Generates .devcontainer/ configuration for agent isolated execution.
+ * Uses a custom Dockerfile with network firewall for security isolation.
  */
 import { ExecutionConfig, ExecutorType } from './types.js';
 export type MountMode = 'worktree' | 'clone';
@@ -48,7 +48,7 @@ export interface DevcontainerJson {
 /**
  * Generate default devcontainer.json content
  *
- * Uses a custom Dockerfile with firewall for network sandboxing.
+ * Uses a custom Dockerfile with firewall for network isolation.
  * Mounts the entire agent workspace directory so all contents (repos, prompt files, etc.)
  * are accessible inside the container at /workspace.
  */

package/dist/lib/execution/devcontainer.js

@@ -1,8 +1,8 @@
 /**
  * Devcontainer Template Generator
  *
- * Generates .devcontainer/ configuration for agent sandboxed execution.
- * Uses a custom Dockerfile with network firewall for security sandboxing.
+ * Generates .devcontainer/ configuration for agent isolated execution.
+ * Uses a custom Dockerfile with network firewall for security isolation.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -11,7 +11,7 @@ import { parseChannel } from '../workspace-config.js';
 /**
  * Generate default devcontainer.json content
  *
- * Uses a custom Dockerfile with firewall for network sandboxing.
+ * Uses a custom Dockerfile with firewall for network isolation.
  * Mounts the entire agent workspace directory so all contents (repos, prompt files, etc.)
  * are accessible inside the container at /workspace.
  */

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

@@ -8,3 +8,4 @@ export * from './runners.js';
 export * from './storage.js';
 export * from './config.js';
 export * from './devcontainer.js';
+export * from './codex-adapter.js';

package/dist/lib/execution/index.js

@@ -8,3 +8,4 @@ export * from './runners.js';
 export * from './storage.js';
 export * from './config.js';
 export * from './devcontainer.js';
+export * from './codex-adapter.js';

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

@@ -3,7 +3,7 @@
  *
  * Implementations for each execution environment (devcontainer, host, docker, vm).
  */
-import { ExecutionEnvironment, DisplayMode, OutputMode, SessionManager, ExecutorType, ExecutionContext, ExecutionConfig } from './types.js';
+import { ExecutionEnvironment, DisplayMode, OutputMode, PermissionMode, SessionManager, ExecutorType, ExecutionContext, ExecutionConfig } from './types.js';
 /**
  * Build a unified name for tmux sessions, window names, and tab titles.
  * Format: "{ticketId}-{action}-{agentName}"
@@ -162,7 +162,7 @@ export declare function getContainerId(containerName: string): string | null;
  * Uses docker exec for direct container access.
  * Uses a prompt file to avoid shell escaping issues.
  */
-export declare function buildDevcontainerCommand(context: ExecutionContext, executor: ExecutorType, promptFile: string, containerId?: string, outputMode?: OutputMode, sandboxed?: boolean, displayMode?: DisplayMode): string;
+export declare function buildDevcontainerCommand(context: ExecutionContext, executor: ExecutorType, promptFile: string, containerId?: string, outputMode?: OutputMode, permissionMode?: PermissionMode, displayMode?: DisplayMode): string;
 /**
  * Run command inside a Docker container.
  * Uses raw Docker commands for filesystem isolation - no devcontainer CLI required.

package/dist/lib/execution/runners.js

@@ -11,6 +11,7 @@ import * as os from 'node:os';
 import { DEFAULT_EXECUTION_CONFIG, } from './types.js';
 import { getSetTitleCommands } from '../terminal.js';
 import { readDevcontainerJson } from './devcontainer.js';
+import { getCodexCommand, resolveCodexExecutionContext, validateCodexMode } from './codex-adapter.js';
 // =============================================================================
 // Terminal Title Helpers
 // =============================================================================
@@ -167,11 +168,16 @@ export function getExecutorCommand(executor, prompt, skipPermissions = true) {
             }
             // Manual mode - will prompt for each action (still interactive, no -p)
             return { cmd: 'claude', args: [prompt] };
-        case 'codex':
-            // Map danger mode to Codex-native autonomy mode.
-            return skipPermissions
-                ? { cmd: 'codex', args: ['--yolo', '--prompt', prompt] }
-                : { cmd: 'codex', args: ['--prompt', prompt] };
+        case 'codex': {
+            // Delegate to Codex adapter for deterministic mode mapping.
+            // getExecutorCommand is called without display/output context, so we use
+            // 'interactive' as default context (safe for validation — all permission modes
+            // are valid with interactive). Runners that need stricter validation should
+            // call the adapter directly with the actual execution context.
+            const codexPermission = skipPermissions ? 'danger' : 'safe';
+            const codexResult = getCodexCommand(prompt, codexPermission, 'interactive');
+            return { cmd: codexResult.cmd, args: codexResult.args };
+        }
         case 'aider':
             return { cmd: 'aider', args: ['--message', prompt] };
         case 'custom':
@@ -380,8 +386,17 @@ export async function runHost(context, executor, config, displayMode = 'terminal
     const sessionName = buildTmuxWindowName(context);
     const windowTitle = buildWindowTitle(context);
     const prompt = buildPrompt(context);
-    // Terminal - use sandboxed setting
-    const skipPermissions = !config.sandboxed;
+    // Terminal - use permission mode setting
+    const skipPermissions = config.permissionMode === 'danger';
+    // Validate Codex mode combination before proceeding
+    if (executor === 'codex') {
+        const codexPermission = config.permissionMode;
+        const codexContext = resolveCodexExecutionContext(displayMode, config.outputMode);
+        const modeError = validateCodexMode(codexPermission, codexContext);
+        if (modeError) {
+            return { success: false, error: modeError.message };
+        }
+    }
     const { cmd, args } = getExecutorCommand(executor, prompt, skipPermissions);
     // Write command to temp script to avoid shell escaping issues
     // Use HQ .proletariat/scripts if available, otherwise fallback to home dir
@@ -919,7 +934,7 @@ function createDockerContainer(context, containerName, imageName, config, execut
         `--memory=${config.devcontainer.memory}`,
         `--cpus=${config.devcontainer.cpus}`,
     ];
-    // Security flags - these provide the sandboxing
+    // Security flags - these provide the isolation
     const securityFlags = [
         '--cap-add=NET_ADMIN', // For firewall setup
         '--cap-add=NET_RAW', // For firewall setup
@@ -951,10 +966,10 @@ function createDockerContainer(context, containerName, imageName, config, execut
  * Run the post-start setup commands in a container.
  * This includes firewall initialization, prlt setup, and Claude settings.
  * @param containerId - Docker container ID
- * @param sandboxed - Whether running in safe mode (true) or danger mode (false)
+ * @param permissionMode - Permission mode: 'safe' requires approval, 'danger' skips checks
  * @param executor - Which executor is being used (determines Claude-specific setup)
  */
-function runContainerSetup(containerId, sandboxed = true, executor = 'claude-code') {
+function runContainerSetup(containerId, permissionMode = 'safe', executor = 'claude-code') {
     try {
         // Run firewall init (requires sudo since we're running as node user)
         execSync(`docker exec ${containerId} sudo /usr/local/bin/init-firewall.sh`, { stdio: 'pipe' });
@@ -995,9 +1010,9 @@ function runContainerSetup(containerId, sandboxed = true, executor = 'claude-cod
                     console.debug('[runners:docker] Failed to parse host .claude.json, using empty settings');
                 }
             }
-            // Only set bypassPermissionsModeAccepted when user chose danger mode (!sandboxed)
+            // Only set bypassPermissionsModeAccepted when user chose danger mode
             // This doesn't modify the host file - only the container copy
-            if (!sandboxed) {
+            if (permissionMode === 'danger') {
                 settings.bypassPermissionsModeAccepted = true;
             }
             // Skip first-run onboarding (theme picker, tips, etc.) for automated agents
@@ -1032,7 +1047,7 @@ function runContainerSetup(containerId, sandboxed = true, executor = 'claude-cod
             const settingsJson = JSON.stringify(settings);
             // Write to container at /home/node/.claude.json using stdin piping
             execSync(`docker exec -i ${containerId} bash -c 'cat > /home/node/.claude.json'`, { input: settingsJson, stdio: ['pipe', 'pipe', 'pipe'] });
-            console.debug(`[runners:docker] Copied .claude.json settings to container (bypassPermissionsModeAccepted=${!sandboxed})`);
+            console.debug(`[runners:docker] Copied .claude.json settings to container (bypassPermissionsModeAccepted=${permissionMode === 'danger'})`);
             // Write ~/.claude/settings.json to skip the dangerous mode permission prompt (TKT-1134)
             // This prevents Claude Code from prompting about permission mode on first run
             const claudeSettings = JSON.stringify({ skipDangerousModePermissionPrompt: true });
@@ -1138,10 +1153,10 @@ function ensureDockerContainer(context, config, executor = 'claude-code') {
         return null;
     }
     // Run post-start setup (firewall, prlt, Claude settings)
-    // Pass sandboxed config to determine whether to set bypassPermissionsModeAccepted
+    // Pass permission mode to determine whether to set bypassPermissionsModeAccepted
     // Pass executor to skip Claude-specific setup for non-Claude executors
-    console.debug(`[runners:docker] Running container setup (sandboxed=${config.sandboxed}, executor=${executor})`);
-    if (!runContainerSetup(containerId, config.sandboxed, executor)) {
+    console.debug(`[runners:docker] Running container setup (permissionMode=${config.permissionMode}, executor=${executor})`);
+    if (!runContainerSetup(containerId, config.permissionMode, executor)) {
         console.debug(`[runners:docker] Setup failed, but continuing...`);
         // Don't fail completely - setup might partially work
     }
@@ -1225,30 +1240,42 @@ function writePromptFile(context) {
  * Uses docker exec for direct container access.
  * Uses a prompt file to avoid shell escaping issues.
  */
-export function buildDevcontainerCommand(context, executor, promptFile, containerId, outputMode = 'interactive', sandboxed = true, displayMode = 'terminal') {
+export function buildDevcontainerCommand(context, executor, promptFile, containerId, outputMode = 'interactive', permissionMode = 'safe', displayMode = 'terminal') {
     // Calculate the relative path from agentDir to worktreePath for cd
     const relativePath = path.relative(context.agentDir, context.worktreePath);
     const cdCmd = relativePath ? `cd /workspace/${relativePath} && ` : '';
     // Build executor command using the centralized getExecutorCommand()
     // This ensures all runners use consistent executor invocation
     let executorCmd;
+    const skipPermissions = permissionMode === 'danger';
     if (isClaudeExecutor(executor)) {
-        // Claude-specific flags based on output mode and sandboxed setting
+        // Claude-specific flags based on output mode and permission mode
         // - interactive: No -p flag, shows streaming UI (watch Claude work in real-time)
         // - print: Uses -p flag, outputs final result only (better for logs/automation)
         const printFlag = outputMode === 'print' ? '-p ' : '';
-        // sandboxed=true means safe mode (no --dangerously-skip-permissions)
-        // sandboxed=false means danger mode (use --dangerously-skip-permissions)
         // --permission-mode bypassPermissions: skips the "trust this folder" dialog
         const bypassTrustFlag = '--permission-mode bypassPermissions ';
-        const permissionsFlag = !sandboxed ? '--dangerously-skip-permissions ' : '';
+        const permissionsFlag = skipPermissions ? '--dangerously-skip-permissions ' : '';
         // --effort high: skips the effort level prompt for automated agents (TKT-1134)
         const effortFlag = '--effort high ';
         executorCmd = `claude ${bypassTrustFlag}${permissionsFlag}${effortFlag}${printFlag}"$(cat ${promptFile})"`;
     }
+    else if (executor === 'codex') {
+        // Use Codex adapter for mode validation and deterministic command building.
+        // Validates that the permission/display combination is supported before building.
+        const codexPermission = permissionMode;
+        const codexContext = resolveCodexExecutionContext(displayMode, outputMode);
+        const modeError = validateCodexMode(codexPermission, codexContext);
+        if (modeError) {
+            throw modeError;
+        }
+        const codexResult = getCodexCommand('PLACEHOLDER', codexPermission, codexContext);
+        const argsStr = codexResult.args.map(a => a === 'PLACEHOLDER' ? `"$(cat ${promptFile})"` : a).join(' ');
+        executorCmd = `${codexResult.cmd} ${argsStr}`;
+    }
     else {
-        // Non-Claude executors: use getExecutorCommand() to get correct command and args
-        const { cmd, args } = getExecutorCommand(executor, `PLACEHOLDER`, !sandboxed);
+        // Non-Claude, non-Codex executors: use getExecutorCommand() to get correct command and args
+        const { cmd, args } = getExecutorCommand(executor, `PLACEHOLDER`, skipPermissions);
         // Replace the placeholder prompt with a file read for shell safety
         const argsStr = args.map(a => a === 'PLACEHOLDER' ? `"$(cat ${promptFile})"` : a).join(' ');
         executorCmd = `${cmd} ${argsStr}`;
@@ -1337,7 +1364,7 @@ export async function runDevcontainer(context, executor, config, displayMode = '
         }
         // Build the docker exec command (just runs claude directly)
         // tmux session setup is handled by runDevcontainerInTmux, not buildDevcontainerCommand
-        const devcontainerCmd = buildDevcontainerCommand(context, executor, promptFile, containerId, config.outputMode, config.sandboxed, displayMode);
+        const devcontainerCmd = buildDevcontainerCommand(context, executor, promptFile, containerId, config.outputMode, config.permissionMode, displayMode);
         // Execute based on display mode
         // When sessionManager is 'tmux', always use tmux inside container for session persistence
         // (allows reattach via `prlt session attach` even for background mode)
@@ -1987,9 +2014,17 @@ export async function runDocker(context, executor, config) {
         if (config.docker.cpus) {
             dockerCmd += ` --cpus ${config.docker.cpus}`;
         }
+        // Validate Codex mode: Docker runner is always non-tty (detached with -d)
+        if (executor === 'codex') {
+            const codexPermission = config.permissionMode;
+            const modeError = validateCodexMode(codexPermission, 'non-tty');
+            if (modeError) {
+                return { success: false, error: modeError.message };
+            }
+        }
         // Build executor command using getExecutorCommand() for correct invocation
         const escapedPrompt = prompt.replace(/'/g, "'\\''");
-        const { cmd, args } = getExecutorCommand(executor, escapedPrompt, !config.sandboxed);
+        const { cmd, args } = getExecutorCommand(executor, escapedPrompt, config.permissionMode === 'danger');
         // For Claude Code in Docker, use --print for non-interactive output
         // Non-Claude executors use their native command format from getExecutorCommand()
         dockerCmd += ` ${config.docker.image}`;
@@ -2049,9 +2084,17 @@ 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' });
         }
+        // Validate Codex mode: VM runner is always non-tty (SSH + nohup)
+        if (executor === 'codex') {
+            const codexPermission = config.permissionMode;
+            const modeError = validateCodexMode(codexPermission, 'non-tty');
+            if (modeError) {
+                return { success: false, error: modeError.message };
+            }
+        }
         // Execute on remote using executor-appropriate command
         const escapedPrompt = prompt.replace(/'/g, "'\\''");
-        const { cmd: executorCmd, args: executorArgs } = getExecutorCommand(executor, escapedPrompt, !config.sandboxed);
+        const { cmd: executorCmd, args: executorArgs } = getExecutorCommand(executor, escapedPrompt, config.permissionMode === 'danger');
         // Build the remote command based on executor type
         let remoteCmd;
         if (isClaudeExecutor(executor)) {

package/dist/lib/execution/spawner.js

@@ -282,7 +282,7 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
         environment = 'host';
     }
     const displayMode = options.displayMode || 'terminal';
-    const sandboxed = !(options.skipPermissions ?? false);
+    const permissionMode = (options.skipPermissions ?? false) ? 'danger' : 'safe';
     // 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') {
@@ -457,12 +457,12 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
         executor,
         environment,
         displayMode,
-        sandboxed,
+        permissionMode,
         branch,
     });
     // Load execution config (use passed config or load from db)
     const executionConfig = options.executionConfig || loadExecutionConfig(db);
-    executionConfig.sandboxed = sandboxed;
+    executionConfig.permissionMode = permissionMode;
     // Run execution
     // Default to tmux for session persistence (enables peek/poke/attach)
     const sessionManager = options.sessionManager || 'tmux';

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

@@ -4,7 +4,7 @@
  * Database operations for agent_work table.
  */
 import Database from 'better-sqlite3';
-import { AgentWork, ExecutionStatus, ExecutorType, ExecutionEnvironment, DisplayMode } from './types.js';
+import { AgentWork, ExecutionStatus, ExecutorType, ExecutionEnvironment, DisplayMode, PermissionMode } from './types.js';
 export declare class ExecutionStorage {
     private db;
     constructor(db: Database.Database);
@@ -18,7 +18,7 @@ export declare class ExecutionStorage {
         executor: ExecutorType;
         environment: ExecutionEnvironment;
         displayMode: DisplayMode;
-        sandboxed: boolean;
+        permissionMode: PermissionMode;
         branch?: string;
         pid?: string;
         containerId?: string;

package/dist/lib/execution/storage.js

@@ -18,7 +18,7 @@ function rowToAgentWork(row) {
         executor: row.executor,
         environment: (row.environment || 'host'),
         displayMode: (row.display_mode || 'terminal'),
-        sandboxed: row.sandboxed === 1,
+        permissionMode: (row.permission_mode || 'safe'),
         status: row.status,
         branch: row.branch || undefined,
         pid: row.pid || undefined,
@@ -51,10 +51,10 @@ export class ExecutionStorage {
         const id = `WORK-${randomUUID().substring(0, 8).toUpperCase()}`;
         this.db.prepare(`
       INSERT INTO ${T.agent_work} (
-        id, ticket_id, agent_name, executor, environment, display_mode, sandboxed,
+        id, ticket_id, agent_name, executor, environment, display_mode, permission_mode,
         status, branch, pid, container_id, session_id, host, log_path, started_at
       ) VALUES (?, ?, ?, ?, ?, ?, ?, 'starting', ?, ?, ?, ?, ?, ?, ?)
-    `).run(id, params.ticketId, params.agentName, params.executor, params.environment, params.displayMode, params.sandboxed ? 1 : 0, params.branch || null, params.pid || null, params.containerId || null, params.sessionId || null, params.host || null, params.logPath || null, now);
+    `).run(id, params.ticketId, params.agentName, params.executor, params.environment, params.displayMode, params.permissionMode, params.branch || null, params.pid || null, params.containerId || null, params.sessionId || null, params.host || null, params.logPath || null, now);
         return this.getExecution(id);
     }
     /**

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

@@ -46,7 +46,7 @@ export interface AgentWork {
     environment: ExecutionEnvironment;
     displayMode: DisplayMode;
     sessionManager?: SessionManager;
-    sandboxed: boolean;
+    permissionMode: PermissionMode;
     status: ExecutionStatus;
     branch?: string;
     pid?: string;
@@ -120,7 +120,7 @@ export interface ExecutionConfig {
     autoExecute: boolean;
     shell: Shell;
     outputMode: OutputMode;
-    sandboxed: boolean;
+    permissionMode: PermissionMode;
     authMethod?: AuthMethod;
     createPrDefault?: boolean;
     tmux: {

package/dist/lib/execution/types.js

@@ -131,7 +131,7 @@ export const DEFAULT_EXECUTION_CONFIG = {
     autoExecute: false,
     shell: 'zsh', // macOS default
     outputMode: 'interactive', // Show streaming UI by default
-    sandboxed: true, // Require approval for dangerous operations by default
+    permissionMode: 'safe', // Require approval for dangerous operations by default
     tmux: {
         session: 'proletariat',
         layout: 'window',

package/dist/lib/external-issues/index.d.ts

@@ -4,7 +4,7 @@
  * Shared contract for normalizing external issues (Linear, Jira) into
  * a canonical IssueEnvelope format with deterministic spawn context mapping.
  */
-export { type IssueSource, type IssueEnvelope, type IssueSpawnContext, type IssueValidationError, type IssueValidationErrorCode, type IssueValidationResult, type ExternalIssueAdapter, type ExternalIssueErrorCode, ISSUE_SOURCES, ExternalIssueError, } from './types.js';
+export { type IssueSource, type IssueEnvelope, type IssueSpawnContext, type IssueValidationError, type IssueValidationErrorCode, type IssueValidationResult, type ExternalIssueAdapter, type ExternalIssueErrorCode, type ExternalIssueAdapterErrorCode, type NormalizedIssueEnvelope, type IssueSourceMetadata, ISSUE_SOURCES, ExternalIssueError, ExternalIssueAdapterError, toNormalizedEnvelope, } from './types.js';
 export { validateIssueEnvelope, validateOrThrow, } from './validation.js';
 export { mapToSpawnContext, } from './mapper.js';
 export { LinearIssueAdapter, JiraIssueAdapter, } from './adapters.js';

package/dist/lib/external-issues/index.js

@@ -5,7 +5,7 @@
  * a canonical IssueEnvelope format with deterministic spawn context mapping.
  */
 // Types and interfaces
-export { ISSUE_SOURCES, ExternalIssueError, } from './types.js';
+export { ISSUE_SOURCES, ExternalIssueError, ExternalIssueAdapterError, toNormalizedEnvelope, } from './types.js';
 // Validation
 export { validateIssueEnvelope, validateOrThrow, } from './validation.js';
 // Mapper

package/dist/lib/external-issues/linear.d.ts

@@ -0,0 +1,43 @@
+import { type IssueEnvelope, type NormalizedIssueEnvelope } from './types.js';
+export interface LinearAdapterConfig {
+    apiKey?: string;
+    team?: string;
+    apiUrl?: string;
+}
+/**
+ * Normalize a raw Linear API issue node into a canonical IssueEnvelope.
+ */
+export declare function normalizeLinearIssue(rawIssue: unknown): IssueEnvelope;
+/**
+ * Normalize a raw Linear issue into a PMO-ready NormalizedIssueEnvelope.
+ */
+export declare function normalizeLinearIssueToEnvelope(rawIssue: unknown): NormalizedIssueEnvelope;
+/**
+ * Build a PMO ticket description from a NormalizedIssueEnvelope.
+ */
+export declare function buildLinearTicketDescription(envelope: NormalizedIssueEnvelope): string;
+/**
+ * Build ticket metadata from a NormalizedIssueEnvelope for traceability.
+ */
+export declare function buildLinearMetadata(envelope: NormalizedIssueEnvelope): Record<string, string>;
+/**
+ * Build a spawn context message from a NormalizedIssueEnvelope.
+ */
+export declare function buildLinearSpawnContextMessage(envelope: NormalizedIssueEnvelope, additionalMessage?: string): string;
+/**
+ * Build a CLI command string for selecting a specific Linear issue.
+ */
+export declare function buildLinearIssueChoiceCommand(issueIdentifier: string, projectId?: string): string;
+/**
+ * Fetch a single Linear issue by identifier (for example, ENG-123) and normalize it.
+ */
+export declare function getLinearIssueByIdentifier(configInput: LinearAdapterConfig, identifier: string, options?: {
+    fetchImpl?: typeof fetch;
+}): Promise<NormalizedIssueEnvelope | null>;
+/**
+ * Fetch and normalize Linear issues into NormalizedIssueEnvelopes.
+ */
+export declare function listLinearIssues(configInput: LinearAdapterConfig, options?: {
+    limit?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<NormalizedIssueEnvelope[]>;