@proletariat/cli 0.3.96 → 0.3.98

package/dist/commands/work/start.js

@@ -9,7 +9,8 @@ import { enrichAgentSession } from '../../lib/telemetry/telemetry-bridge.js';
 import { registerAgent } from '../../lib/registry/index.js';
 import { shouldOutputJson, outputErrorAsJson, createMetadata, outputConfirmationNeededAsJson, outputExecutionResultAsJson, } from '../../lib/prompt-json.js';
 import { FlagResolver } from '../../lib/flags/index.js';
-import { getWorkColumnSetting, findColumnByName, resolveReviewGate } from '../../lib/work-lifecycle/settings.js';
+import { findColumnByName, resolveReviewGate } from '../../lib/work-lifecycle/settings.js';
+import { moveTicketByIntent } from '../../lib/work-lifecycle/transition.js';
 import { getTicketExternalMetadata, resolveExternalTicketId } from '../../lib/external-issues/utils.js';
 import { styles } from '../../lib/styles.js';
 import { getWorkspaceInfo, createEphemeralAgent, getTicketTmuxSession, killTmuxSession, findWorktreeForBranch, resolveAgentDir, } from '../../lib/agents/commands.js';
@@ -17,7 +18,7 @@ import { openWorkspaceDatabase } from '../../lib/database/index.js';
 import { generateBranchName, DEFAULT_EXECUTION_CONFIG, } from '../../lib/execution/types.js';
 import { runExecution, isDockerRunning, isGitHubTokenAvailable, isDevcontainerCliInstalled, dockerCredentialsExist, getDockerCredentialInfo, isClaudeExecutor, getExecutorDisplayName } from '../../lib/execution/runners.js';
 import { ExecutionStorage, ContainerStorage } from '../../lib/execution/storage.js';
-import { loadExecutionConfig, getTerminalApp, promptTerminalPreference, getShell, promptShellPreference, hasTerminalPreference, hasShellPreference, getAuthMethod, saveAuthMethod, getCreatePrDefault, getMirrorToPmoDefault, getCleanupPolicy } from '../../lib/execution/config.js';
+import { loadExecutionConfig, getTerminalApp, promptTerminalPreference, getShell, promptShellPreference, hasTerminalPreference, hasShellPreference, getAuthMethod, saveAuthMethod, getCreatePrDefault, getVerifyCiDefault, getMirrorToPmoDefault, getCleanupPolicy } from '../../lib/execution/config.js';
 import { hasDevcontainerConfig } from '../../lib/execution/devcontainer.js';
 import { detectRepoWorktrees, resolveWorktreePath, buildWorkspaceRepos } from '../../lib/execution/context.js';
 import { isGHInstalled, isGHAuthenticated } from '../../lib/pr/index.js';
@@ -27,12 +28,15 @@ import { buildAsanaMetadata, buildAsanaSpawnContextMessage, buildAsanaTicketDesc
 import { buildShortcutMetadata, buildShortcutSpawnContextMessage, buildShortcutTicketDescription, getShortcutStoryByKey, } from '../../lib/external-issues/shortcut.js';
 import { buildTrelloMetadata, buildTrelloSpawnContextMessage, buildTrelloTicketDescription, getTrelloCardById, } from '../../lib/external-issues/trello.js';
 import { resolveMirrorToPmo } from '../../lib/external-issues/work-start.js';
+import { buildTicketFromEnvelope } from '../../lib/external-issues/ticket-builder.js';
+import { TicketRefStore } from '../../lib/execution/ticket-refs.js';
 import { getLinearApiKey, loadLinearConfig } from '../../lib/linear/config.js';
 import { LinearMapper } from '../../lib/linear/mapper.js';
 import { ExternalIssueAdapterError } from '../../lib/external-issues/types.js';
 import { loadDefaultWorkSource, getConnectedIntegrations, isLocalTicketId, } from '../../lib/work-source/index.js';
 import { pruneWorktrees, checkoutBranchSafe } from '../../lib/branch/index.js';
 import { handlePostExecutionTransition } from '../../lib/work-lifecycle/index.js';
+import { runPreflightChecks, formatPreflightReport } from '../../lib/execution/preflight.js';
 /**
  * Try to execute a git command, return true if successful
  */
@@ -161,6 +165,7 @@ export default class WorkStart extends PMOCommand {
         '<%= config.bin %> <%= command.id %> TKT-001 --review-gate post        # Ship then human reviews after',
         '<%= config.bin %> <%= command.id %> PRLT-1085 PRLT-1086 PRLT-1087 --create-pr  # Batch spawn in parallel',
         '<%= config.bin %> <%= command.id %> TKT-001 TKT-002 TKT-003 --max-parallel 2  # Limit concurrent spawns',
+        '<%= config.bin %> <%= command.id %> TKT-001 --dry-run                        # Validate environment without spawning',
     ];
     static args = {
         ticketId: Args.string({
@@ -246,6 +251,10 @@ export default class WorkStart extends PMOCommand {
             description: '[deprecated: use --create-pr instead] Skip PR creation when work is ready',
             default: false,
         }),
+        'verify-ci': Flags.boolean({
+            description: 'Agent polls CI after pushing and fixes failures before exiting (PRLT-1126)',
+            default: false,
+        }),
         output: Flags.string({
             char: 'o',
             description: 'Output mode',
@@ -317,6 +326,10 @@ export default class WorkStart extends PMOCommand {
             description: 'Maximum number of concurrent spawns when starting multiple tickets (default: unlimited)',
             min: 1,
         }),
+        'dry-run': Flags.boolean({
+            description: 'Validate environment and prerequisites without actually spawning an agent',
+            default: false,
+        }),
     };
     async findLinkedTicketByEnvelope(projectId, envelope) {
         const tickets = await this.storage.listTickets(projectId);
@@ -520,6 +533,8 @@ export default class WorkStart extends PMOCommand {
             let fromIssueMirror;
             let fromIssueMirrorSource;
             let sourceResolutionMeta;
+            // PRLT-1167: When built from envelope without PMO mirror, holds the in-memory ticket
+            let envelopeTicket;
             // Handle --from shorthand: parse provider:key into source + key
             let fromFlag = flags.from;
             let fromIssueActive = flags['from-issue'];
@@ -620,12 +635,33 @@ export default class WorkStart extends PMOCommand {
                     linkedTicket = await this.createOrUpdateLinkedTicket(projectId, envelope, db);
                     await autoExportToBoard(this.pmoPath, this.storage);
                 }
+                else if (existingLinkedTicket) {
+                    // Existing PMO ticket found — use it (backward compat)
+                    linkedTicket = existingLinkedTicket;
+                }
                 else {
-                    if (!existingLinkedTicket) {
-                        db.close();
-                        return handleError('EXTERNAL_ISSUE_NOT_MIRRORED', `No linked PMO ticket found for ${sourceAndKey.source} issue "${sourceAndKey.key}". Re-run with --mirror-to-pmo.`);
+                    // PRLT-1167: Build Ticket from envelope directly — no PMO mirror
+                    linkedTicket = buildTicketFromEnvelope(envelope, projectId);
+                    envelopeTicket = linkedTicket;
+                    // Store in ticket_refs so post-execution and other commands can find it
+                    const ticketRefStore = new TicketRefStore(db);
+                    ticketRefStore.upsert({
+                        id: linkedTicket.id,
+                        provider: envelope.source.name,
+                        externalId: envelope.source.externalId,
+                        externalKey: envelope.source.externalKey,
+                        externalUrl: envelope.source.url,
+                        title: envelope.title,
+                        description: envelope.description,
+                        status: envelope.status,
+                        priority: envelope.priority,
+                        category: envelope.category,
+                        assignee: envelope.assignee,
+                        projectId,
+                    });
+                    if (!jsonMode) {
+                        this.log(styles.muted(`Ticket ref stored: ${linkedTicket.id} (no PMO mirror)`));
                     }
-                    linkedTicket = existingLinkedTicket;
                 }
                 ticketId = linkedTicket.id;
                 externalIssueContextMessage = buildExternalSpawnContextMessage(envelope, flags.message);
@@ -651,14 +687,65 @@ export default class WorkStart extends PMOCommand {
                 }
                 ticketId = selected;
             }
-            // Get ticket
-            const ticket = await this.storage.getTicket(ticketId);
+            // Get ticket — use envelope-built ticket when available (PRLT-1167: no PMO mirror)
+            const ticket = envelopeTicket ?? await this.storage.getTicket(ticketId);
             if (!ticket) {
                 db.close();
                 return handleError('TICKET_NOT_FOUND', `Ticket "${ticketId}" not found.`);
             }
             // Use resolved internal ID for all subsequent operations (external keys like PRLT-xxx resolve to TKT-xxx)
             ticketId = ticket.id;
+            const isExternalOnly = !!envelopeTicket;
+            // --dry-run: validate environment and report issues without spawning
+            if (flags['dry-run']) {
+                const dryRunEnvironment = flags['run-on-host'] ? 'host' : 'devcontainer';
+                const dryRunExecutor = flags.executor || DEFAULT_EXECUTION_CONFIG.defaultExecutor;
+                const report = runPreflightChecks({
+                    environment: dryRunEnvironment,
+                    executor: dryRunExecutor,
+                    db,
+                    ticket: { id: ticket.id, title: ticket.title },
+                    agentDir: null, // Not yet created during dry-run
+                });
+                if (jsonMode) {
+                    const metadata = createMetadata('work start', flags);
+                    metadata.dryRun = true;
+                    metadata.environment = dryRunEnvironment;
+                    metadata.executor = dryRunExecutor;
+                    const jsonResult = {
+                        passed: report.passed,
+                        checks: report.checks.map(c => ({
+                            name: c.name,
+                            label: c.label,
+                            passed: c.passed,
+                            severity: c.severity,
+                            message: c.message,
+                            fix: c.fix ?? null,
+                        })),
+                        errors: report.errors.length,
+                        warnings: report.warnings.length,
+                    };
+                    outputExecutionResultAsJson([{ workId: '', ticketId: ticket.id, agent: '', status: report.passed ? 'ready' : 'blocked' }], report.passed ? 1 : 0, report.passed ? 0 : 1, { ...metadata, preflight: jsonResult });
+                }
+                else {
+                    this.log('');
+                    this.log(styles.header(`Dry-run: preflight validation for ${ticket.id}`));
+                    this.log(styles.muted(`   Environment: ${dryRunEnvironment}`));
+                    this.log(styles.muted(`   Executor: ${dryRunExecutor}`));
+                    this.log('');
+                    this.log(formatPreflightReport(report));
+                    this.log('');
+                    if (report.passed) {
+                        this.log(styles.success('All preflight checks passed — ready to spawn.'));
+                    }
+                    else {
+                        this.log(styles.error(`${report.errors.length} error(s) and ${report.warnings.length} warning(s) found.`));
+                        this.log(styles.muted('Fix the errors above, then run without --dry-run to start work.'));
+                    }
+                }
+                db.close();
+                return;
+            }
             // In JSON mode with explicit flags, implement two-step confirm-then-execute protocol
             if (jsonMode) {
                 // Check if all required flags for non-interactive execution are provided
@@ -745,8 +832,8 @@ export default class WorkStart extends PMOCommand {
                 // If --yes is set with all flags, continue to execution (don't return)
                 // If missing flags, continue and let FlagResolver handle prompts
             }
-            // Check if ticket is blocked by dependencies
-            const isBlocked = await this.storage.isTicketBlocked(ticketId);
+            // Check if ticket is blocked by dependencies (skip for external-only tickets)
+            const isBlocked = isExternalOnly ? false : await this.storage.isTicketBlocked(ticketId);
             if (isBlocked && !flags.force) {
                 const blockers = await this.storage.getTicketBlockers(ticketId);
                 const incompleteBlockers = blockers.filter(b => b.status !== 'done' && b.status !== 'canceled');
@@ -1783,6 +1870,19 @@ export default class WorkStart extends PMOCommand {
             }
             // Add createPR to context
             context.createPR = createPR;
+            // Resolve verify-ci: flag > workspace config > default false
+            // Only meaningful when createPR is true (need a PR to poll CI on)
+            let verifyCi = false;
+            if (flags['verify-ci']) {
+                verifyCi = true;
+            }
+            else {
+                const configVerifyCi = getVerifyCiDefault(db);
+                if (configVerifyCi !== null) {
+                    verifyCi = configVerifyCi;
+                }
+            }
+            context.verifyCi = verifyCi;
             // Resolve review gate mode (most specific wins: spawn flag > action config > workspace default)
             const reviewGate = resolveReviewGate(flags['review-gate'], selectedAction?.reviewGate, db);
             context.reviewGate = reviewGate;
@@ -1802,6 +1902,10 @@ export default class WorkStart extends PMOCommand {
                 };
                 this.log(styles.warning(`   Review gate: ${reviewGate} (${gateDescriptions[reviewGate]})`));
             }
+            // Display verify-ci status
+            if (!jsonMode && verifyCi && context.createPR) {
+                this.log(styles.success(`   CI verify: enabled — agent will poll CI and fix failures before exiting`));
+            }
             // Handle git operations
             let finalBranch = branch;
             // Set up repo paths (needed for all action types)
@@ -1946,8 +2050,8 @@ export default class WorkStart extends PMOCommand {
                         }
                     }
                 }
-                // Save branch to ticket
-                if (!isExistingBranch || finalBranch !== branch) {
+                // Save branch to ticket (skip for external-only tickets — no PMO record)
+                if (!isExternalOnly && (!isExistingBranch || finalBranch !== branch)) {
                     await this.storage.updateTicket(ticket.id, { branch: finalBranch });
                 }
                 // Update context with final branch
@@ -2095,64 +2199,74 @@ export default class WorkStart extends PMOCommand {
                     });
                 }
                 // Update ticket assignee ONLY after successful spawn
+                // For external-only tickets, update ticket_ref instead of PMO storage
                 if (!ticket.assignee || ticket.assignee !== assignedAgent) {
-                    await this.storage.updateTicket(ticket.id, { assignee: assignedAgent });
-                    this.log(styles.muted(`   Assigned to: ${assignedAgent}`));
-                }
-                // Move ticket to target column based on action's toState
-                // If action has a to_state, use that state name directly; otherwise fall back to "In Progress" default
-                const targetStateName = selectedAction?.toState;
-                const board = ticket.projectId ? await this.storage.getProjectBoard(ticket.projectId) : null;
-                const columnNames = board ? board.columns.map(col => col.name) : [];
-                let targetColumnName = null;
-                if (targetStateName) {
-                    // Try direct state name match first
-                    targetColumnName = findColumnByName(columnNames, targetStateName);
-                    if (!targetColumnName) {
-                        const categoryMap = {
-                            'Backlog': 'planned',
-                            'Todo': 'planned',
-                            'In Progress': 'in_progress',
-                            'Done': 'done',
-                        };
-                        const columnType = categoryMap[targetStateName] || 'in_progress';
-                        const workColumnName = getWorkColumnSetting(db, columnType);
-                        targetColumnName = findColumnByName(columnNames, workColumnName);
+                    if (isExternalOnly) {
+                        // Update ticket_ref with assignee
+                        const ticketRefStore = new TicketRefStore(db);
+                        ticketRefStore.upsert({ id: ticket.id, title: ticket.title, assignee: assignedAgent });
                     }
+                    else {
+                        await this.storage.updateTicket(ticket.id, { assignee: assignedAgent });
+                    }
+                    this.log(styles.muted(`   Assigned to: ${assignedAgent}`));
                 }
-                else {
-                    // No target state specified — default to "In Progress"
-                    const workColumnName = getWorkColumnSetting(db, 'in_progress');
-                    targetColumnName = findColumnByName(columnNames, workColumnName);
-                }
-                if (targetColumnName && ticket.statusName !== targetColumnName) {
-                    try {
-                        await this.storage.moveTicket(ticket.projectId, ticket.id, targetColumnName);
-                        this.log(styles.muted(`   Moved to: ${targetColumnName}`));
+                // Move ticket to target column based on action's toState or default 'started' intent
+                // Skip PMO board operations for external-only tickets (no PMO record to move)
+                if (!isExternalOnly) {
+                    // If action has a to_state, try direct match first; otherwise use intent resolution
+                    const targetStateName = selectedAction?.toState;
+                    const board = ticket.projectId ? await this.storage.getProjectBoard(ticket.projectId) : null;
+                    const columnNames = board ? board.columns.map(col => col.name) : [];
+                    let targetColumnName = null;
+                    if (targetStateName) {
+                        // Try direct state name match first (backward compat with action toState)
+                        targetColumnName = findColumnByName(columnNames, targetStateName);
                     }
-                    catch (moveError) {
-                        // Non-fatal - work can proceed even if column move fails
-                        this.warn(`Could not move ticket to "${targetColumnName}": ${moveError instanceof Error ? moveError.message : moveError}`);
+                    if (!targetColumnName) {
+                        // Use intent-based resolution — 'started' intent
+                        const transition = await moveTicketByIntent({
+                            db,
+                            storage: this.storage,
+                            ticket,
+                            intent: 'started',
+                            providerName: 'pmo',
+                            resolveProvider: (tid, pid) => this.resolveTicketProvider(tid, pid),
+                            log: (msg) => this.log(styles.muted(`   ${msg}`)),
+                        });
+                        if (transition.moved) {
+                            this.log(styles.muted(`   Moved to: ${transition.targetColumn}`));
+                        }
                     }
-                    // Sync to external provider (e.g., Linear) if ticket was imported from one
-                    try {
-                        const provider = await this.resolveTicketProvider(ticket.id, ticket.projectId);
-                        if (provider.name !== 'pmo') {
-                            const result = await provider.moveTicket(ticket.id, targetColumnName);
-                            if (result.success) {
-                                this.log(styles.muted(`   Synced to ${result.provider}: ${targetColumnName}`));
+                    else if (targetColumnName && ticket.statusName !== targetColumnName) {
+                        try {
+                            await this.storage.moveTicket(ticket.projectId, ticket.id, targetColumnName);
+                            this.log(styles.muted(`   Moved to: ${targetColumnName}`));
+                        }
+                        catch (moveError) {
+                            // Non-fatal - work can proceed even if column move fails
+                            this.warn(`Could not move ticket to "${targetColumnName}": ${moveError instanceof Error ? moveError.message : moveError}`);
+                        }
+                        // Sync to external provider (e.g., Linear) if ticket was imported from one
+                        try {
+                            const provider = await this.resolveTicketProvider(ticket.id, ticket.projectId);
+                            if (provider.name !== 'pmo') {
+                                const result = await provider.moveTicket(ticket.id, targetColumnName);
+                                if (result.success) {
+                                    this.log(styles.muted(`   Synced to ${result.provider}: ${targetColumnName}`));
+                                }
                             }
                         }
+                        catch {
+                            // Non-fatal — don't block work start for provider sync failures
+                        }
                     }
-                    catch {
-                        // Non-fatal — don't block work start for provider sync failures
-                    }
-                }
-                await autoExportToBoard(this.pmoPath, this.storage, (msg) => {
-                    if (!jsonMode) {
-                        this.log(styles.muted(msg));
-                    }
-                });
+                    await autoExportToBoard(this.pmoPath, this.storage, (msg) => {
+                        if (!jsonMode) {
+                            this.log(styles.muted(msg));
+                        }
+                    });
+                } // end if (!isExternalOnly)
                 // Output results
                 if (jsonMode) {
                     // Output JSON execution result with resolved PR mode and source
@@ -2196,20 +2310,53 @@ export default class WorkStart extends PMOCommand {
                     success: false,
                     errorType: 'spawn_failure',
                 });
+                // Run post-failure diagnostics to give user actionable info
+                const failureDiag = runPreflightChecks({
+                    environment,
+                    executor,
+                    db,
+                    ticket: { id: ticket.id, title: ticket.title },
+                    agentDir: context.agentDir,
+                });
+                const diagErrors = failureDiag.errors;
                 if (jsonMode) {
-                    // Output JSON failure result with resolved PR mode
+                    // Output JSON failure result with resolved PR mode and diagnostics
                     const failMetadata = createMetadata('work start', flags);
                     failMetadata.resolvedPRMode = createPR ? 'create-pr' : 'no-pr';
                     failMetadata.prModeSource = prModeSource;
+                    failMetadata.spawnError = result.error || 'Unknown error';
+                    if (diagErrors.length > 0) {
+                        failMetadata.diagnostics = diagErrors.map(e => ({
+                            check: e.name,
+                            message: e.message,
+                            fix: e.fix ?? null,
+                        }));
+                    }
                     outputExecutionResultAsJson([{
                             workId: execution.id,
                             ticketId: ticket.id,
                             agent: assignedAgent,
                             status: 'failed',
+                            error: result.error || 'Unknown error',
                         }], 0, 1, failMetadata);
                 }
                 else {
-                    return handleError('START_FAILED', `Failed to start work: ${result.error}`);
+                    // Build a detailed error message with the spawn error and any diagnostic findings
+                    const spawnError = result.error || 'Unknown error';
+                    const errorLines = [`Failed to start work on ${ticket.id}: ${spawnError}`];
+                    if (diagErrors.length > 0) {
+                        errorLines.push('');
+                        errorLines.push('Diagnostics found these issues:');
+                        for (const diag of diagErrors) {
+                            errorLines.push(`  ✗ ${diag.label}: ${diag.message}`);
+                            if (diag.fix) {
+                                errorLines.push(`    → Fix: ${diag.fix}`);
+                            }
+                        }
+                    }
+                    errorLines.push('');
+                    errorLines.push('Tip: Run with --dry-run to validate your environment before spawning.');
+                    return handleError('START_FAILED', errorLines.join('\n'));
                 }
             }
             db.close();
@@ -2289,6 +2436,8 @@ export default class WorkStart extends PMOCommand {
                 startArgs.push('--create-pr');
             if (flags['no-pr'])
                 startArgs.push('--no-pr');
+            if (flags['verify-ci'])
+                startArgs.push('--verify-ci');
             if (flags.session)
                 startArgs.push('--session', flags.session);
             if (flags.force)
@@ -2343,6 +2492,7 @@ export default class WorkStart extends PMOCommand {
                     ticketId: ticket.id,
                     agent: '',
                     status: 'failed',
+                    error: error instanceof Error ? error.message : String(error),
                 });
             }
         };
@@ -2827,30 +2977,35 @@ export default class WorkStart extends PMOCommand {
             if (!ticket.assignee || ticket.assignee !== agentName) {
                 await this.storage.updateTicket(ticket.id, { assignee: agentName });
             }
-            // Move ticket to In Progress column ONLY after successful spawn
-            const targetColumnName = getWorkColumnSetting(db, 'in_progress');
-            const board = ticket.projectId ? await this.storage.getProjectBoard(ticket.projectId) : null;
-            const columnNames = board ? board.columns.map(col => col.name) : [];
-            const inProgressColumn = findColumnByName(columnNames, targetColumnName);
-            if (inProgressColumn && ticket.status !== inProgressColumn) {
-                await this.storage.moveTicket(ticket.projectId, ticket.id, inProgressColumn);
-                // Sync to external provider (e.g., Linear) if ticket was imported from one
-                try {
-                    const provider = await this.resolveTicketProvider(ticket.id, ticket.projectId);
-                    if (provider.name !== 'pmo') {
-                        await provider.moveTicket(ticket.id, inProgressColumn);
-                    }
-                }
-                catch {
-                    // Non-fatal — don't block work start for provider sync failures
-                }
-            }
+            // Move ticket to In Progress column ONLY after successful spawn — via intent resolution
+            const transition = await moveTicketByIntent({
+                db,
+                storage: this.storage,
+                ticket,
+                intent: 'started',
+                providerName: 'pmo',
+                resolveProvider: (tid, pid) => this.resolveTicketProvider(tid, pid),
+            });
             await autoExportToBoard(this.pmoPath, this.storage, () => { });
             this.log(styles.success(`   ✓ ${ticket.id} started (${execution.id})`));
         }
         else {
             executionStorage.updateStatus(execution.id, 'failed');
-            throw new Error(result.error || 'Unknown error');
+            // Include diagnostic details in the error message
+            const spawnError = result.error || 'Unknown error';
+            const diag = runPreflightChecks({
+                environment,
+                executor,
+                db,
+                ticket: { id: ticket.id, title: ticket.title },
+                agentDir: context.agentDir,
+            });
+            const diagIssues = diag.errors;
+            if (diagIssues.length > 0) {
+                const details = diagIssues.map(e => `${e.label}: ${e.message}`).join('; ');
+                throw new Error(`${spawnError} [${details}]`);
+            }
+            throw new Error(spawnError);
         }
     }
 }