@proletariat/cli 0.3.51 → 0.3.52

package/dist/lib/execution/runners.js

@@ -152,6 +152,107 @@ export function getDockerCredentialInfo() {
         return null;
     }
 }
+/**
+ * Check if Claude Code authentication is available on the host system.
+ * Returns true if either:
+ * 1. OAuth credentials exist in ~/.claude/.credentials.json, OR
+ * 2. ANTHROPIC_API_KEY environment variable is set
+ *
+ * This is used to validate auth before spawning host sessions (e.g., orchestrator)
+ * to avoid creating stuck sessions when the keychain is locked (SSH contexts).
+ */
+export function hostCredentialsExist() {
+    // Check for ANTHROPIC_API_KEY first (works in all contexts, including SSH)
+    if (process.env.ANTHROPIC_API_KEY) {
+        return true;
+    }
+    // Check for OAuth credentials in ~/.claude/.credentials.json
+    try {
+        const homeDir = process.env.HOME || os.homedir();
+        const credPath = path.join(homeDir, '.claude', '.credentials.json');
+        if (!fs.existsSync(credPath)) {
+            return false;
+        }
+        const credData = fs.readFileSync(credPath, 'utf-8');
+        const creds = JSON.parse(credData);
+        // Check if OAuth credentials exist (similar to Docker check)
+        // Don't check expiration - Claude Code handles token refresh internally
+        if (creds.claudeAiOauth?.accessToken) {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure tmux server has keychain access for Claude Code OAuth.
+ *
+ * On macOS, tmux sessions can lose access to the keychain if the tmux server
+ * was started in a context without keychain access (e.g., from a background
+ * process, SSH session, or parent process with restricted keychain access).
+ *
+ * This function:
+ * 1. Checks if a tmux server is running
+ * 2. Tests if it can access Claude Code OAuth credentials
+ * 3. If not, restarts the tmux server to restore keychain access
+ *
+ * This runs transparently before spawning agent sessions, ensuring OAuth
+ * authentication works without manual intervention.
+ */
+async function ensureTmuxServerHasKeychainAccess() {
+    // Skip if no tmux server is running (will be started fresh with keychain access)
+    try {
+        const serverRunning = execSync('tmux list-sessions 2>/dev/null || echo ""', {
+            encoding: 'utf-8',
+            stdio: 'pipe'
+        });
+        if (!serverRunning.trim()) {
+            return; // No server running, will start fresh
+        }
+    }
+    catch {
+        return; // tmux not installed or no server running
+    }
+    // Test if tmux server can access Claude Code credentials
+    // We spawn a test session and check if Claude Code can authenticate
+    const testSession = `prlt-keychain-test-${Date.now()}`;
+    try {
+        // Create test session
+        execSync(`tmux new-session -d -s "${testSession}"`, { stdio: 'pipe' });
+        // Send command to check Claude Code auth
+        // Use 'unset CLAUDECODE' to avoid nested session error
+        execSync(`tmux send-keys -t "${testSession}" "unset CLAUDECODE && claude -p 'test' 2>&1 | head -1" Enter`, { stdio: 'pipe' });
+        // Wait for response (Claude Code startup + auth check)
+        await new Promise(resolve => setTimeout(resolve, 3000));
+        // Capture output
+        const output = execSync(`tmux capture-pane -t "${testSession}" -p`, {
+            encoding: 'utf-8',
+            stdio: 'pipe'
+        });
+        // Clean up test session
+        execSync(`tmux kill-session -t "${testSession}"`, { stdio: 'pipe' });
+        // Check if auth failed
+        if (output.includes('Not logged in') || output.includes('Please run /login')) {
+            // Keychain access is broken - restart tmux server
+            // This happens silently - the next tmux session will have keychain access
+            execSync('tmux kill-server', { stdio: 'pipe' });
+            // Brief delay to ensure server fully stops
+            await new Promise(resolve => setTimeout(resolve, 500));
+        }
+    }
+    catch (_error) {
+        // Test session failed - clean up if it exists
+        try {
+            execSync(`tmux kill-session -t "${testSession}"`, { stdio: 'pipe' });
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        // Continue - worst case, spawn will fail with clear error message
+    }
+}
 // =============================================================================
 // Executor Commands
 // =============================================================================
@@ -438,7 +539,8 @@ ${setTitleCmds}
 echo "🚀 Starting: ${sessionName}"
 echo ""
 cd "${context.worktreePath}"
-${executorInvocation}
+# Run executor in subshell with CLAUDECODE unset (prevents nested session error)
+(unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT; ${executorInvocation})
 
 # Clean up script and prompt files
 rm -f "$SCRIPT_PATH" "$PROMPT_PATH"
@@ -1693,11 +1795,13 @@ async function runDevcontainerInTmux(context, devcontainerCmd, config, displayMo
         // 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
+        // Unset CLAUDECODE to allow Claude Code to run (prevents nested session error)
         // Note: We keep DEVCONTAINER set so prlt workspace detection works correctly
         const tmuxScript = `#!/bin/bash
 export TERM=xterm-256color
 export COLORTERM=truecolor
 unset CI
+unset CLAUDECODE
 echo "🚀 Starting: ${sessionName}"
 echo ""
 ${claudeCmd}
@@ -2123,6 +2227,11 @@ export async function runVm(context, executor, config, host) {
 // Runner Dispatcher
 // =============================================================================
 export async function runExecution(environment, context, executor, config = DEFAULT_EXECUTION_CONFIG, options) {
+    // Ensure tmux server has keychain access for OAuth (host only)
+    // Docker uses claude-credentials volume, devcontainer runs inside container
+    if (environment === 'host') {
+        await ensureTmuxServerHasKeychainAccess();
+    }
     switch (environment) {
         case 'devcontainer':
             return runDevcontainer(context, executor, config, options?.displayMode, options?.sessionManager);

package/dist/lib/execution/spawner.js

@@ -16,6 +16,7 @@ import { hasDevcontainerConfig } from './devcontainer.js';
 import { loadExecutionConfig, getOrPromptCoderName } from './config.js';
 import { runExecution, isDockerRunning, isGitHubTokenAvailable, isDevcontainerCliInstalled, runExecutorPreflight, getAgentContainerName, isContainerRunning, getContainerId, buildSessionName } from './runners.js';
 import { detectRepoWorktrees, resolveWorktreePath } from './context.js';
+import { ExternalExecutionMappingStore } from '../external-issues/mapping-store.js';
 import { generateBranchName, DEFAULT_EXECUTION_CONFIG, } from './types.js';
 // =============================================================================
 // Git Utilities
@@ -103,6 +104,12 @@ function findBaseBranchInContainer(containerId, containerRepoPath, candidates =
  * contention when all agents mount the same shared volumes concurrently.
  */
 const SPAWN_STAGGER_DELAY_MS = 2000;
+const EXTERNAL_MAPPING_PROVIDERS = new Set(['linear', 'jira', 'asana', 'monday', 'pmo']);
+function getExternalProvider(value) {
+    if (!value)
+        return null;
+    return EXTERNAL_MAPPING_PROVIDERS.has(value) ? value : null;
+}
 // =============================================================================
 // Agent Selection
 // =============================================================================
@@ -501,6 +508,25 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
             await storage.moveTicket(ticket.projectId, ticket.id, inProgressColumn);
         }
         await autoExportToBoard(pmoPath, storage, log);
+        const externalProvider = getExternalProvider(ticket.metadata?.external_source);
+        const externalId = ticket.metadata?.external_id;
+        if (externalProvider && externalId) {
+            const mappingStore = new ExternalExecutionMappingStore(db);
+            mappingStore.upsertMapping({
+                provider: externalProvider,
+                externalId,
+                externalKey: ticket.metadata?.external_key ?? null,
+                canonicalUrl: ticket.metadata?.external_url ?? null,
+                latestStateSnapshot: {
+                    ticketId: ticket.id,
+                    ticketStatus: ticket.statusName ?? null,
+                    ticketCategory: ticket.statusCategory ?? null,
+                    teamKey: ticket.metadata?.external_project ?? null,
+                },
+                executionId: execution.id,
+                lastSpawnedAt: new Date(),
+            });
+        }
         return {
             success: true,
             executionId: execution.id,

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

@@ -25,6 +25,10 @@ export declare class ExecutionStorage {
         sessionId?: string;
         host?: string;
         logPath?: string;
+        externalSource?: string;
+        externalKey?: string;
+        externalId?: string;
+        externalUrl?: string;
     }): AgentWork;
     /**
      * Get execution by ID

package/dist/lib/execution/storage.js

@@ -26,6 +26,10 @@ function rowToAgentWork(row) {
         sessionId: row.session_id || undefined,
         host: row.host || undefined,
         logPath: row.log_path || undefined,
+        externalSource: row.external_source || undefined,
+        externalKey: row.external_key || undefined,
+        externalId: row.external_id || undefined,
+        externalUrl: row.external_url || undefined,
         startedAt: new Date(row.started_at),
         completedAt: row.completed_at ? new Date(row.completed_at) : undefined,
         exitCode: row.exit_code ?? undefined,
@@ -52,9 +56,10 @@ export class ExecutionStorage {
         this.db.prepare(`
       INSERT INTO ${T.agent_work} (
         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.permissionMode, params.branch || null, params.pid || null, params.containerId || null, params.sessionId || null, params.host || null, params.logPath || null, now);
+        status, branch, pid, container_id, session_id, host, log_path,
+        external_source, external_key, external_id, external_url, started_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, 'starting', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).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, params.externalSource || null, params.externalKey || null, params.externalId || null, params.externalUrl || null, now);
         return this.getExecution(id);
     }
     /**

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

@@ -54,6 +54,10 @@ export interface AgentWork {
     sessionId?: string;
     host?: string;
     logPath?: string;
+    externalSource?: string;
+    externalKey?: string;
+    externalId?: string;
+    externalUrl?: string;
     startedAt: Date;
     completedAt?: Date;
     exitCode?: number;

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

@@ -1,4 +1,5 @@
-import { type ExternalIssueAdapter, type IssueEnvelope } from './types.js';
+import { ExternalExecutionMappingStore } from './mapping-store.js';
+import { type ExternalIssueAdapter, type ExternalExecutionMapping, type IssueEnvelope } from './types.js';
 type FetchIssueByKey = (key: string) => Promise<unknown>;
 type FetchIssuesByQuery = (query: Record<string, unknown>) => Promise<unknown[]>;
 interface AdapterFetchers {
@@ -13,6 +14,14 @@ export declare class LinearIssueAdapter implements ExternalIssueAdapter {
     normalize(raw: unknown): IssueEnvelope;
     fetchByKey(key: string): Promise<IssueEnvelope>;
     fetchByQuery(query: Record<string, unknown>): Promise<IssueEnvelope[]>;
+    persistMapping(store: ExternalExecutionMappingStore, envelope: IssueEnvelope, params?: {
+        executionId?: string;
+        prUrl?: string;
+        lastSyncedAt?: Date;
+        lastSpawnedAt?: Date;
+    }): ExternalExecutionMapping;
+    readMappingByExternalId(store: ExternalExecutionMappingStore, externalId: string): ExternalExecutionMapping | null;
+    readMappingsByExecutionId(store: ExternalExecutionMappingStore, executionId: string): ExternalExecutionMapping[];
 }
 export declare class JiraIssueAdapter implements ExternalIssueAdapter {
     readonly source: "jira";
@@ -22,5 +31,13 @@ export declare class JiraIssueAdapter implements ExternalIssueAdapter {
     normalize(raw: unknown): IssueEnvelope;
     fetchByKey(key: string): Promise<IssueEnvelope>;
     fetchByQuery(query: Record<string, unknown>): Promise<IssueEnvelope[]>;
+    persistMapping(store: ExternalExecutionMappingStore, envelope: IssueEnvelope, params?: {
+        executionId?: string;
+        prUrl?: string;
+        lastSyncedAt?: Date;
+        lastSpawnedAt?: Date;
+    }): ExternalExecutionMapping;
+    readMappingByExternalId(store: ExternalExecutionMappingStore, externalId: string): ExternalExecutionMapping | null;
+    readMappingsByExecutionId(store: ExternalExecutionMappingStore, executionId: string): ExternalExecutionMapping[];
 }
 export {};

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

@@ -1,5 +1,5 @@
 import { validateOrThrow } from './validation.js';
-import { ExternalIssueError } from './types.js';
+import { ExternalIssueError, } from './types.js';
 function asRecord(value) {
     if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         return {};
@@ -206,6 +206,30 @@ export class LinearIssueAdapter {
         const rawIssues = await fetchIssuesByQuery(query);
         return rawIssues.map((raw) => this.normalize(raw));
     }
+    persistMapping(store, envelope, params) {
+        return store.upsertMapping({
+            provider: this.source,
+            externalId: envelope.external_id,
+            externalKey: envelope.external_key,
+            canonicalUrl: envelope.url,
+            latestStateSnapshot: {
+                status: envelope.status,
+                priority: envelope.priority,
+                assignee: envelope.assignee,
+                projectKey: envelope.project_key,
+            },
+            executionId: params?.executionId,
+            prUrl: params?.prUrl,
+            lastSyncedAt: params?.lastSyncedAt,
+            lastSpawnedAt: params?.lastSpawnedAt,
+        });
+    }
+    readMappingByExternalId(store, externalId) {
+        return store.getByExternalId(this.source, externalId);
+    }
+    readMappingsByExecutionId(store, executionId) {
+        return store.findByExecutionId(executionId).filter((mapping) => mapping.provider === this.source);
+    }
 }
 export class JiraIssueAdapter {
     source = 'jira';
@@ -248,4 +272,28 @@ export class JiraIssueAdapter {
         const rawIssues = await fetchIssuesByQuery(query);
         return rawIssues.map((raw) => this.normalize(raw));
     }
+    persistMapping(store, envelope, params) {
+        return store.upsertMapping({
+            provider: this.source,
+            externalId: envelope.external_id,
+            externalKey: envelope.external_key,
+            canonicalUrl: envelope.url,
+            latestStateSnapshot: {
+                status: envelope.status,
+                priority: envelope.priority,
+                assignee: envelope.assignee,
+                projectKey: envelope.project_key,
+            },
+            executionId: params?.executionId,
+            prUrl: params?.prUrl,
+            lastSyncedAt: params?.lastSyncedAt,
+            lastSpawnedAt: params?.lastSpawnedAt,
+        });
+    }
+    readMappingByExternalId(store, externalId) {
+        return store.getByExternalId(this.source, externalId);
+    }
+    readMappingsByExecutionId(store, executionId) {
+        return store.findByExecutionId(executionId).filter((mapping) => mapping.provider === this.source);
+    }
 }

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

@@ -4,7 +4,10 @@
  * 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, type ExternalIssueAdapterErrorCode, type NormalizedIssueEnvelope, type IssueSourceMetadata, ISSUE_SOURCES, ExternalIssueError, ExternalIssueAdapterError, toNormalizedEnvelope, } 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, type ExternalMappingProvider, type ExternalExecutionMapping, type UpsertExternalExecutionMappingInput, 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';
+export { ExternalExecutionMappingStore } from './mapping-store.js';
+export { normalizeJiraIssue, normalizeJiraIssueToEnvelope, buildJiraTicketDescription, buildJiraMetadata, buildJiraSpawnContextMessage, getJiraIssueByKey, } from './jira.js';
+export { resolveMirrorToPmo, type MirrorResolution, type MirrorResolutionInput, } from './work-start.js';

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

@@ -12,3 +12,8 @@ export { validateIssueEnvelope, validateOrThrow, } from './validation.js';
 export { mapToSpawnContext, } from './mapper.js';
 // Adapters
 export { LinearIssueAdapter, JiraIssueAdapter, } from './adapters.js';
+// Mapping store
+export { ExternalExecutionMappingStore } from './mapping-store.js';
+// Source helpers
+export { normalizeJiraIssue, normalizeJiraIssueToEnvelope, buildJiraTicketDescription, buildJiraMetadata, buildJiraSpawnContextMessage, getJiraIssueByKey, } from './jira.js';
+export { resolveMirrorToPmo, } from './work-start.js';

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

@@ -0,0 +1,23 @@
+import { type IssueEnvelope, type NormalizedIssueEnvelope } from './types.js';
+export interface JiraAdapterConfig {
+    baseUrl?: string;
+    host?: string;
+    email?: string;
+    apiToken?: string;
+    projectKey?: string;
+    jql?: string;
+}
+export declare function normalizeJiraIssue(rawIssue: unknown): IssueEnvelope;
+export declare function normalizeJiraIssueToEnvelope(rawIssue: unknown): NormalizedIssueEnvelope;
+export declare function buildJiraTicketDescription(envelope: NormalizedIssueEnvelope): string;
+export declare function buildJiraMetadata(envelope: NormalizedIssueEnvelope): Record<string, string>;
+export declare function buildJiraSpawnContextMessage(envelope: NormalizedIssueEnvelope, additionalMessage?: string): string;
+export declare function buildJiraIssueChoiceCommand(issueKey: string, projectId?: string): string;
+export declare function getJiraIssueByKey(configInput: JiraAdapterConfig, issueKey: string, options?: {
+    fetchImpl?: typeof fetch;
+}): Promise<NormalizedIssueEnvelope | null>;
+export declare function listJiraIssues(configInput: JiraAdapterConfig, options?: {
+    limit?: number;
+    jql?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<NormalizedIssueEnvelope[]>;

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

@@ -0,0 +1,223 @@
+import { ExternalIssueAdapterError, toNormalizedEnvelope, } from './types.js';
+import { JiraIssueAdapter } from './adapters.js';
+const DEFAULT_JIRA_API_PATH = '/rest/api/3';
+const JIRA_ISSUE_FIELDS = [
+    'summary',
+    'description',
+    'labels',
+    'priority',
+    'status',
+    'project',
+    'issuetype',
+    'assignee',
+];
+function normalizeBaseUrl(value) {
+    const trimmed = value.trim().replace(/\/+$/, '');
+    if (/^https?:\/\//i.test(trimmed)) {
+        return trimmed;
+    }
+    return `https://${trimmed}`;
+}
+function ensureJiraConfig(config) {
+    const baseUrl = config.baseUrl
+        || config.host
+        || process.env.PRLT_JIRA_BASE_URL
+        || process.env.JIRA_BASE_URL
+        || process.env.PRLT_JIRA_HOST
+        || process.env.JIRA_HOST;
+    const email = config.email || process.env.PRLT_JIRA_EMAIL || process.env.JIRA_EMAIL || '';
+    const apiToken = config.apiToken || process.env.PRLT_JIRA_API_TOKEN || process.env.JIRA_API_TOKEN;
+    const projectKey = config.projectKey || process.env.PRLT_JIRA_PROJECT || process.env.JIRA_PROJECT_KEY || '';
+    const jql = config.jql || process.env.PRLT_JIRA_JQL || '';
+    if (!baseUrl) {
+        throw new ExternalIssueAdapterError('MISSING_CONFIG', 'Missing Jira base URL. Set PRLT_JIRA_BASE_URL/JIRA_BASE_URL or PRLT_JIRA_HOST/JIRA_HOST.');
+    }
+    if (!apiToken) {
+        throw new ExternalIssueAdapterError('MISSING_CONFIG', 'Missing Jira API token. Set PRLT_JIRA_API_TOKEN or JIRA_API_TOKEN.');
+    }
+    return {
+        baseUrl: normalizeBaseUrl(baseUrl),
+        host: normalizeBaseUrl(baseUrl),
+        email,
+        apiToken,
+        projectKey,
+        jql,
+    };
+}
+function ensureIssueKey(key) {
+    const trimmed = key.trim().toUpperCase();
+    if (!/^[A-Z][A-Z0-9_]*-\d+$/.test(trimmed)) {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', `Invalid Jira issue key: "${key}".`);
+    }
+    return trimmed;
+}
+function buildAuthHeader(config) {
+    if (config.email) {
+        const token = Buffer.from(`${config.email}:${config.apiToken}`).toString('base64');
+        return `Basic ${token}`;
+    }
+    return `Bearer ${config.apiToken}`;
+}
+function buildListJql(config, explicitJql) {
+    const jql = explicitJql?.trim() || config.jql.trim();
+    if (jql.length > 0) {
+        return jql;
+    }
+    const projectKey = config.projectKey.trim();
+    if (!projectKey) {
+        throw new ExternalIssueAdapterError('MISSING_CONFIG', 'Missing Jira project key/JQL. Pass --project-key or --jql, or set PRLT_JIRA_PROJECT/PRLT_JIRA_JQL.');
+    }
+    return `project = "${projectKey}" AND statusCategory != Done ORDER BY updated DESC`;
+}
+function getErrorMessage(payload, fallback) {
+    if (!payload || typeof payload !== 'object') {
+        return fallback;
+    }
+    const errorMessages = payload.errorMessages;
+    if (Array.isArray(errorMessages) && typeof errorMessages[0] === 'string' && errorMessages[0].trim()) {
+        return errorMessages[0].trim();
+    }
+    return fallback;
+}
+async function parseJsonOrThrow(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', 'Jira response was not valid JSON.');
+    }
+}
+function deriveJiraCategory(envelope) {
+    const typeValue = envelope.item_type?.trim().toLowerCase() || '';
+    if (typeValue === 'bug' || typeValue === 'incident') {
+        return 'bug';
+    }
+    if (typeValue === 'task' || typeValue === 'story' || typeValue === 'issue') {
+        return 'feature';
+    }
+    return 'feature';
+}
+function ensureIssueShape(issue) {
+    if (!issue.id || !issue.key || !issue.fields) {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', 'Jira issue payload is missing required fields (id, key, fields).', issue);
+    }
+}
+export function normalizeJiraIssue(rawIssue) {
+    if (!rawIssue || typeof rawIssue !== 'object') {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', 'Jira issue payload is invalid.', rawIssue);
+    }
+    const issue = rawIssue;
+    ensureIssueShape(issue);
+    const adapter = new JiraIssueAdapter();
+    return adapter.normalize(issue);
+}
+export function normalizeJiraIssueToEnvelope(rawIssue) {
+    const envelope = normalizeJiraIssue(rawIssue);
+    return toNormalizedEnvelope(envelope, deriveJiraCategory(envelope));
+}
+export function buildJiraTicketDescription(envelope) {
+    const body = envelope.description.trim();
+    const metadataLines = [
+        `- Source: ${envelope.source.name}`,
+        `- External key: ${envelope.source.externalKey}`,
+        `- External id: ${envelope.source.externalId}`,
+        `- URL: ${envelope.source.url}`,
+        `- Status: ${envelope.status}`,
+        `- Priority: ${envelope.priority || 'Unset'}`,
+        `- Labels: ${envelope.labels.length > 0 ? envelope.labels.join(', ') : 'None'}`,
+    ];
+    const parts = [
+        body,
+        '## External Issue Context',
+        metadataLines.join('\n'),
+    ].filter(Boolean);
+    return parts.join('\n\n');
+}
+export function buildJiraMetadata(envelope) {
+    return {
+        external_source: envelope.source.name,
+        external_key: envelope.source.externalKey,
+        external_id: envelope.source.externalId,
+        external_url: envelope.source.url,
+        external_raw: JSON.stringify(envelope.source.raw),
+    };
+}
+export function buildJiraSpawnContextMessage(envelope, additionalMessage) {
+    const lines = [
+        `External issue source: ${envelope.source.name}`,
+        `External issue key: ${envelope.source.externalKey}`,
+        `External issue id: ${envelope.source.externalId}`,
+        `External issue URL: ${envelope.source.url}`,
+    ];
+    if (additionalMessage?.trim()) {
+        lines.push('', additionalMessage.trim());
+    }
+    return lines.join('\n');
+}
+export function buildJiraIssueChoiceCommand(issueKey, projectId) {
+    let command = `prlt work jira --issue ${issueKey} --json`;
+    if (projectId) {
+        command += ` -P ${projectId}`;
+    }
+    return command;
+}
+export async function getJiraIssueByKey(configInput, issueKey, options) {
+    const config = ensureJiraConfig(configInput);
+    const fetchImpl = options?.fetchImpl || fetch;
+    const key = ensureIssueKey(issueKey);
+    const baseApiUrl = `${config.baseUrl}${DEFAULT_JIRA_API_PATH}`;
+    const fields = encodeURIComponent(JIRA_ISSUE_FIELDS.join(','));
+    const issueUrl = `${baseApiUrl}/issue/${encodeURIComponent(key)}?fields=${fields}`;
+    const response = await fetchImpl(issueUrl, {
+        method: 'GET',
+        headers: {
+            Accept: 'application/json',
+            Authorization: buildAuthHeader(config),
+        },
+    });
+    if (response.status === 401 || response.status === 403) {
+        throw new ExternalIssueAdapterError('AUTH_FAILED', 'Jira authentication failed. Verify your Jira credentials.');
+    }
+    if (response.status === 404) {
+        return null;
+    }
+    const payload = await parseJsonOrThrow(response);
+    if (!response.ok) {
+        const msg = getErrorMessage(payload, `Jira request failed with status ${response.status}.`);
+        throw new ExternalIssueAdapterError('REQUEST_FAILED', msg, payload);
+    }
+    return normalizeJiraIssueToEnvelope(payload);
+}
+export async function listJiraIssues(configInput, options) {
+    const config = ensureJiraConfig(configInput);
+    const fetchImpl = options?.fetchImpl || fetch;
+    const limit = Math.max(1, Math.min(options?.limit ?? 20, 100));
+    const jql = buildListJql(config, options?.jql);
+    const baseApiUrl = `${config.baseUrl}${DEFAULT_JIRA_API_PATH}`;
+    const response = await fetchImpl(`${baseApiUrl}/search`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            Authorization: buildAuthHeader(config),
+        },
+        body: JSON.stringify({
+            jql,
+            maxResults: limit,
+            fields: JIRA_ISSUE_FIELDS,
+        }),
+    });
+    if (response.status === 401 || response.status === 403) {
+        throw new ExternalIssueAdapterError('AUTH_FAILED', 'Jira authentication failed. Verify your Jira credentials.');
+    }
+    const payload = await parseJsonOrThrow(response);
+    if (!response.ok) {
+        const msg = getErrorMessage(payload, `Jira request failed with status ${response.status}.`);
+        throw new ExternalIssueAdapterError('REQUEST_FAILED', msg, payload);
+    }
+    const data = payload;
+    if (!Array.isArray(data.issues)) {
+        throw new ExternalIssueAdapterError('BAD_PAYLOAD', 'Jira response payload was missing issues array.', payload);
+    }
+    return data.issues.map(normalizeJiraIssueToEnvelope);
+}

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

@@ -65,14 +65,15 @@ function priorityFromLinear(value) {
             return null;
     }
 }
-function ensureLinearConfig(config) {
+function ensureLinearConfig(config, options) {
     const apiKey = config.apiKey || process.env.LINEAR_API_KEY || process.env.PRLT_LINEAR_API_KEY;
     const team = config.team || process.env.PRLT_LINEAR_TEAM || process.env.LINEAR_TEAM_KEY;
     const apiUrl = config.apiUrl || process.env.PRLT_LINEAR_API_URL || DEFAULT_LINEAR_API_URL;
     if (!apiKey) {
         throw new ExternalIssueAdapterError('MISSING_CONFIG', 'Missing Linear API key. Set LINEAR_API_KEY or PRLT_LINEAR_API_KEY.');
     }
-    if (!team) {
+    const requireTeam = options?.requireTeam ?? true;
+    if (requireTeam && !team) {
         throw new ExternalIssueAdapterError('MISSING_CONFIG', 'Missing Linear team key. Pass --team or set PRLT_LINEAR_TEAM.');
     }
     return { apiKey, team, apiUrl };
@@ -180,7 +181,7 @@ export function buildLinearIssueChoiceCommand(issueIdentifier, projectId) {
  * Fetch a single Linear issue by identifier (for example, ENG-123) and normalize it.
  */
 export async function getLinearIssueByIdentifier(configInput, identifier, options) {
-    const config = ensureLinearConfig(configInput);
+    const config = ensureLinearConfig(configInput, { requireTeam: false });
     const fetchImpl = options?.fetchImpl || fetch;
     const response = await fetchImpl(config.apiUrl, {
         method: 'POST',

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

@@ -15,7 +15,8 @@ import type { IssueEnvelope, IssueSpawnContext } from './types.js';
  * The mapping is deterministic: the same IssueEnvelope always produces
  * the same IssueSpawnContext.
  *
- * @param envelope - Validated IssueEnvelope
+ * @param input - IssueEnvelope-like input
  * @returns Spawn context with prompt and metadata
+ * @throws ExternalIssueError when input fails IssueEnvelope validation
  */
-export declare function mapToSpawnContext(envelope: IssueEnvelope): IssueSpawnContext;
+export declare function mapToSpawnContext(input: IssueEnvelope | unknown): IssueSpawnContext;