@proletariat/cli 0.3.45 → 0.3.46

package/dist/lib/execution/spawner.js

@@ -14,7 +14,7 @@ import { findHQRoot } from '../repos/index.js';
 import { hasGitHubRemote } from '../repos/git.js';
 import { hasDevcontainerConfig } from './devcontainer.js';
 import { loadExecutionConfig, getOrPromptCoderName } from './config.js';
-import { runExecution, isDockerRunning, isGitHubTokenAvailable, isDevcontainerCliInstalled, runExecutorPreflight } from './runners.js';
+import { runExecution, isDockerRunning, isGitHubTokenAvailable, isDevcontainerCliInstalled, runExecutorPreflight, getAgentContainerName, isContainerRunning, getContainerId, buildSessionName } from './runners.js';
 import { detectRepoWorktrees, resolveWorktreePath } from './context.js';
 import { generateBranchName, DEFAULT_EXECUTION_CONFIG, } from './types.js';
 // =============================================================================
@@ -286,7 +286,7 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
     // 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') {
-        const preflight = runExecutorPreflight(executor, environment);
+        const preflight = runExecutorPreflight(environment, executor);
         if (!preflight.ok) {
             return {
                 success: false,
@@ -402,6 +402,54 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
             }
         }
     }
+    // TKT-1028: Clean up orphaned execution records before creating a new one.
+    // If the agent's container doesn't exist or isn't running, any "running"/"starting"
+    // execution records for this agent are orphans — their container was destroyed
+    // or crashed. Mark them as "stopped" to prevent downstream issues like
+    // `prlt docker logs` failing with "multiple running containers".
+    // Also clean up stale records when the container IS running but the execution's
+    // containerId doesn't match the current container (e.g., container was recreated).
+    if (environment === 'devcontainer') {
+        const containerName = getAgentContainerName(agentName);
+        const containerRunning = isContainerRunning(containerName);
+        const staleExecutions = executionStorage.getAgentRunningExecutions(agentName);
+        if (!containerRunning) {
+            // Container not running — all "running" executions are orphans
+            for (const staleExec of staleExecutions) {
+                log(`Marking orphaned execution ${staleExec.id} as stopped (container not running)`);
+                executionStorage.updateStatus(staleExec.id, 'stopped');
+            }
+        }
+        else if (staleExecutions.length > 0) {
+            // Container IS running — check for specific orphan scenarios:
+            // 1. containerId mismatch (container was recreated since execution started)
+            // 2. Same session name as incoming spawn (tmux session will be replaced)
+            // 3. Dead tmux sessions (crashed or killed externally)
+            const currentContainerId = getContainerId(containerName);
+            const incomingSessionName = buildSessionName(context);
+            for (const staleExec of staleExecutions) {
+                if (staleExec.containerId && currentContainerId && staleExec.containerId !== currentContainerId) {
+                    log(`Marking orphaned execution ${staleExec.id} as stopped (containerId mismatch)`);
+                    executionStorage.updateStatus(staleExec.id, 'stopped');
+                }
+                else if (staleExec.sessionId === incomingSessionName) {
+                    // Same session name — will be killed when the new tmux session is created
+                    log(`Marking execution ${staleExec.id} as stopped (session will be replaced)`);
+                    executionStorage.updateStatus(staleExec.id, 'stopped');
+                }
+                else if (staleExec.sessionId && currentContainerId) {
+                    // Different session — verify it still exists in the container
+                    try {
+                        execSync(`docker exec ${currentContainerId} tmux has-session -t "${staleExec.sessionId}"`, { stdio: 'pipe' });
+                    }
+                    catch {
+                        log(`Marking orphaned execution ${staleExec.id} as stopped (tmux session gone)`);
+                        executionStorage.updateStatus(staleExec.id, 'stopped');
+                    }
+                }
+            }
+        }
+    }
     // Create execution record
     const execution = executionStorage.createExecution({
         ticketId: ticket.id,
@@ -415,10 +463,19 @@ export async function spawnAgentForTicket(ticket, agentName, storage, executionS
     // Load execution config (use passed config or load from db)
     const executionConfig = options.executionConfig || loadExecutionConfig(db);
     executionConfig.sandboxed = sandboxed;
-    // Use print mode for background, interactive for terminal/tmux
-    executionConfig.outputMode = displayMode === 'background' ? 'print' : 'interactive';
     // Run execution
-    const sessionManager = options.sessionManager || 'direct';
+    // Default to tmux for session persistence (enables peek/poke/attach)
+    const sessionManager = options.sessionManager || 'tmux';
+    // Determine output mode:
+    // - Devcontainer with tmux: always interactive (no -p flag) so Claude runs with TUI
+    //   inside tmux, enabling session peek/poke/attach for Docker agents
+    // - Otherwise: print mode for background (logs only), interactive for terminal/tmux
+    if (environment === 'devcontainer' && sessionManager === 'tmux') {
+        executionConfig.outputMode = 'interactive';
+    }
+    else {
+        executionConfig.outputMode = displayMode === 'background' ? 'print' : 'interactive';
+    }
     const result = await runExecution(environment, context, executor, executionConfig, {
         displayMode,
         sessionManager: environment === 'devcontainer' ? sessionManager : undefined,

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

@@ -122,6 +122,7 @@ export interface ExecutionConfig {
     outputMode: OutputMode;
     sandboxed: boolean;
     authMethod?: AuthMethod;
+    createPrDefault?: boolean;
     tmux: {
         session: string;
         layout: 'split' | 'window';
@@ -144,6 +145,9 @@ export interface ExecutionConfig {
         memory?: string;
         cpus?: number;
     };
+    firewall: {
+        allowlistDomains: string[];
+    };
     vm: {
         defaultHost?: string;
         user: string;

package/dist/lib/execution/types.js

@@ -152,6 +152,9 @@ export const DEFAULT_EXECUTION_CONFIG = {
         image: 'claude-code:latest',
         network: 'host',
     },
+    firewall: {
+        allowlistDomains: [],
+    },
     vm: {
         user: 'agent',
         syncMethod: 'git',

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

@@ -0,0 +1,26 @@
+import { type ExternalIssueAdapter, type IssueEnvelope } from './types.js';
+type FetchIssueByKey = (key: string) => Promise<unknown>;
+type FetchIssuesByQuery = (query: Record<string, unknown>) => Promise<unknown[]>;
+interface AdapterFetchers {
+    fetchByKey?: FetchIssueByKey;
+    fetchByQuery?: FetchIssuesByQuery;
+}
+export declare class LinearIssueAdapter implements ExternalIssueAdapter {
+    readonly source: "linear";
+    private readonly fetchByKeyImpl?;
+    private readonly fetchByQueryImpl?;
+    constructor(fetchers?: AdapterFetchers);
+    normalize(raw: unknown): IssueEnvelope;
+    fetchByKey(key: string): Promise<IssueEnvelope>;
+    fetchByQuery(query: Record<string, unknown>): Promise<IssueEnvelope[]>;
+}
+export declare class JiraIssueAdapter implements ExternalIssueAdapter {
+    readonly source: "jira";
+    private readonly fetchByKeyImpl?;
+    private readonly fetchByQueryImpl?;
+    constructor(fetchers?: AdapterFetchers);
+    normalize(raw: unknown): IssueEnvelope;
+    fetchByKey(key: string): Promise<IssueEnvelope>;
+    fetchByQuery(query: Record<string, unknown>): Promise<IssueEnvelope[]>;
+}
+export {};

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

@@ -0,0 +1,251 @@
+import { validateOrThrow } from './validation.js';
+import { ExternalIssueError } from './types.js';
+function asRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function asString(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function asNullableString(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    return asString(value) ?? null;
+}
+function deriveProjectKeyFromExternalKey(externalKey) {
+    if (!externalKey) {
+        return undefined;
+    }
+    const [prefix] = externalKey.split('-');
+    return prefix && prefix.trim().length > 0 ? prefix : undefined;
+}
+function ensureNormalized(source, candidate) {
+    try {
+        return validateOrThrow(candidate);
+    }
+    catch (error) {
+        if (error instanceof ExternalIssueError && error.code === 'VALIDATION_FAILED') {
+            throw new ExternalIssueError('NORMALIZE_FAILED', `Failed to normalize ${source} issue: ${error.message}`, source, error.validationErrors);
+        }
+        throw error;
+    }
+}
+function getFetchByKeyOrThrow(source, fetchByKey) {
+    if (fetchByKey) {
+        return fetchByKey;
+    }
+    throw new ExternalIssueError('FETCH_FAILED', `No ${source} fetchByKey implementation configured`, source);
+}
+function getFetchByQueryOrThrow(source, fetchByQuery) {
+    if (fetchByQuery) {
+        return fetchByQuery;
+    }
+    throw new ExternalIssueError('FETCH_FAILED', `No ${source} fetchByQuery implementation configured`, source);
+}
+function normalizeLinearPriority(rawPriority) {
+    if (rawPriority === null || rawPriority === undefined) {
+        return null;
+    }
+    if (typeof rawPriority === 'number') {
+        switch (rawPriority) {
+            case 1:
+                return 'P0';
+            case 2:
+                return 'P1';
+            case 3:
+                return 'P2';
+            case 4:
+                return 'P3';
+            default:
+                return null;
+        }
+    }
+    if (typeof rawPriority === 'string') {
+        const normalized = rawPriority.trim().toUpperCase();
+        return normalized.length > 0 ? normalized : null;
+    }
+    return null;
+}
+function normalizeJiraPriority(rawPriority) {
+    const name = typeof rawPriority === 'string'
+        ? rawPriority
+        : asString(asRecord(rawPriority).name);
+    if (!name) {
+        return null;
+    }
+    const normalized = name.trim().toLowerCase();
+    if (normalized === 'highest' || normalized === 'blocker') {
+        return 'P0';
+    }
+    if (normalized === 'high' || normalized === 'critical') {
+        return 'P1';
+    }
+    if (normalized === 'medium') {
+        return 'P2';
+    }
+    if (normalized === 'low' || normalized === 'lowest') {
+        return 'P3';
+    }
+    return name.trim();
+}
+function normalizeLinearLabels(rawLabels) {
+    if (!Array.isArray(rawLabels)) {
+        return [];
+    }
+    return rawLabels
+        .map((label) => {
+        if (typeof label === 'string') {
+            return asString(label);
+        }
+        if (typeof label === 'object' && label !== null) {
+            return asString(label.name);
+        }
+        return undefined;
+    })
+        .filter((label) => typeof label === 'string');
+}
+function normalizeJiraLabels(rawLabels) {
+    if (!Array.isArray(rawLabels)) {
+        return [];
+    }
+    return rawLabels.filter((label) => typeof label === 'string' && label.trim().length > 0);
+}
+function extractAdfText(node) {
+    if (typeof node === 'string') {
+        return node;
+    }
+    if (!node || typeof node !== 'object') {
+        return '';
+    }
+    const record = node;
+    const parts = [];
+    if (typeof record.text === 'string') {
+        parts.push(record.text);
+    }
+    if (Array.isArray(record.content)) {
+        for (const child of record.content) {
+            const text = extractAdfText(child);
+            if (text) {
+                parts.push(text);
+            }
+        }
+    }
+    return parts.join(' ').trim();
+}
+function normalizeJiraDescription(rawDescription) {
+    if (typeof rawDescription === 'string') {
+        return rawDescription;
+    }
+    if (rawDescription === null || rawDescription === undefined) {
+        return '';
+    }
+    return extractAdfText(rawDescription);
+}
+function deriveJiraUrl(raw, key) {
+    const directUrl = asString(raw.url);
+    if (directUrl) {
+        return directUrl;
+    }
+    const selfUrl = asString(raw.self);
+    if (!selfUrl || !key) {
+        return undefined;
+    }
+    try {
+        const parsed = new URL(selfUrl);
+        return `${parsed.origin}/browse/${key}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+export class LinearIssueAdapter {
+    source = 'linear';
+    fetchByKeyImpl;
+    fetchByQueryImpl;
+    constructor(fetchers = {}) {
+        this.fetchByKeyImpl = fetchers.fetchByKey;
+        this.fetchByQueryImpl = fetchers.fetchByQuery;
+    }
+    normalize(raw) {
+        const data = asRecord(raw);
+        const externalKey = asString(data.identifier);
+        const envelope = {
+            source: this.source,
+            external_id: asString(data.id),
+            external_key: externalKey,
+            title: asString(data.title),
+            description: typeof data.description === 'string' ? data.description : '',
+            labels: normalizeLinearLabels(data.labels),
+            priority: normalizeLinearPriority(data.priority),
+            status: asString(asRecord(data.state).name) ?? asString(data.state),
+            url: asString(data.url),
+            project_key: asString(asRecord(data.team).key) ??
+                asString(asRecord(data.project).key) ??
+                deriveProjectKeyFromExternalKey(externalKey),
+            assignee: asNullableString(asRecord(data.assignee).displayName) ??
+                asNullableString(asRecord(data.assignee).name) ??
+                asNullableString(asRecord(data.assignee).email),
+            raw: data,
+        };
+        return ensureNormalized(this.source, envelope);
+    }
+    async fetchByKey(key) {
+        const fetchIssueByKey = getFetchByKeyOrThrow(this.source, this.fetchByKeyImpl);
+        const raw = await fetchIssueByKey(key);
+        return this.normalize(raw);
+    }
+    async fetchByQuery(query) {
+        const fetchIssuesByQuery = getFetchByQueryOrThrow(this.source, this.fetchByQueryImpl);
+        const rawIssues = await fetchIssuesByQuery(query);
+        return rawIssues.map((raw) => this.normalize(raw));
+    }
+}
+export class JiraIssueAdapter {
+    source = 'jira';
+    fetchByKeyImpl;
+    fetchByQueryImpl;
+    constructor(fetchers = {}) {
+        this.fetchByKeyImpl = fetchers.fetchByKey;
+        this.fetchByQueryImpl = fetchers.fetchByQuery;
+    }
+    normalize(raw) {
+        const data = asRecord(raw);
+        const fields = asRecord(data.fields);
+        const key = asString(data.key);
+        const envelope = {
+            source: this.source,
+            external_id: asString(data.id),
+            external_key: key,
+            title: asString(fields.summary),
+            description: normalizeJiraDescription(fields.description),
+            labels: normalizeJiraLabels(fields.labels),
+            priority: normalizeJiraPriority(fields.priority),
+            status: asString(asRecord(fields.status).name),
+            url: deriveJiraUrl(data, key),
+            project_key: asString(asRecord(fields.project).key) ?? deriveProjectKeyFromExternalKey(key),
+            assignee: asNullableString(asRecord(fields.assignee).displayName) ??
+                asNullableString(asRecord(fields.assignee).emailAddress) ??
+                asNullableString(asRecord(fields.assignee).accountId),
+            item_type: asNullableString(asRecord(fields.issuetype).name),
+            raw: data,
+        };
+        return ensureNormalized(this.source, envelope);
+    }
+    async fetchByKey(key) {
+        const fetchIssueByKey = getFetchByKeyOrThrow(this.source, this.fetchByKeyImpl);
+        const raw = await fetchIssueByKey(key);
+        return this.normalize(raw);
+    }
+    async fetchByQuery(query) {
+        const fetchIssuesByQuery = getFetchByQueryOrThrow(this.source, this.fetchByQueryImpl);
+        const rawIssues = await fetchIssuesByQuery(query);
+        return rawIssues.map((raw) => this.normalize(raw));
+    }
+}

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

@@ -0,0 +1,10 @@
+/**
+ * External Issue Adapter Module
+ *
+ * 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 { validateIssueEnvelope, validateOrThrow, } from './validation.js';
+export { mapToSpawnContext, } from './mapper.js';
+export { LinearIssueAdapter, JiraIssueAdapter, } from './adapters.js';

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

@@ -0,0 +1,14 @@
+/**
+ * External Issue Adapter Module
+ *
+ * Shared contract for normalizing external issues (Linear, Jira) into
+ * a canonical IssueEnvelope format with deterministic spawn context mapping.
+ */
+// Types and interfaces
+export { ISSUE_SOURCES, ExternalIssueError, } from './types.js';
+// Validation
+export { validateIssueEnvelope, validateOrThrow, } from './validation.js';
+// Mapper
+export { mapToSpawnContext, } from './mapper.js';
+// Adapters
+export { LinearIssueAdapter, JiraIssueAdapter, } from './adapters.js';

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

@@ -0,0 +1,21 @@
+/**
+ * IssueEnvelope → Spawn Context Mapper
+ *
+ * Deterministically maps an IssueEnvelope to spawn context data
+ * (prompt text + metadata) for agent execution.
+ */
+import type { IssueEnvelope, IssueSpawnContext } from './types.js';
+/**
+ * Map an IssueEnvelope to spawn context data.
+ *
+ * Produces:
+ * - A structured prompt string containing the issue details
+ * - Metadata key-value pairs for ticket context
+ *
+ * The mapping is deterministic: the same IssueEnvelope always produces
+ * the same IssueSpawnContext.
+ *
+ * @param envelope - Validated IssueEnvelope
+ * @returns Spawn context with prompt and metadata
+ */
+export declare function mapToSpawnContext(envelope: IssueEnvelope): IssueSpawnContext;

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

@@ -0,0 +1,86 @@
+/**
+ * IssueEnvelope → Spawn Context Mapper
+ *
+ * Deterministically maps an IssueEnvelope to spawn context data
+ * (prompt text + metadata) for agent execution.
+ */
+/**
+ * Map an IssueEnvelope to spawn context data.
+ *
+ * Produces:
+ * - A structured prompt string containing the issue details
+ * - Metadata key-value pairs for ticket context
+ *
+ * The mapping is deterministic: the same IssueEnvelope always produces
+ * the same IssueSpawnContext.
+ *
+ * @param envelope - Validated IssueEnvelope
+ * @returns Spawn context with prompt and metadata
+ */
+export function mapToSpawnContext(envelope) {
+    const prompt = buildPrompt(envelope);
+    const metadata = buildMetadata(envelope);
+    return { prompt, metadata };
+}
+/**
+ * Build a structured prompt from an IssueEnvelope.
+ *
+ * The prompt includes all relevant issue fields formatted for agent consumption.
+ */
+function buildPrompt(envelope) {
+    const lines = [];
+    lines.push(`# ${envelope.title}`);
+    lines.push('');
+    lines.push(`**Source:** ${envelope.source} (${envelope.external_key})`);
+    if (envelope.item_type) {
+        lines.push(`**Item Type:** ${envelope.item_type}`);
+    }
+    lines.push(`**Status:** ${envelope.status}`);
+    if (envelope.priority) {
+        lines.push(`**Priority:** ${envelope.priority}`);
+    }
+    if (envelope.assignee) {
+        lines.push(`**Assignee:** ${envelope.assignee}`);
+    }
+    lines.push(`**Project:** ${envelope.project_key}`);
+    if (envelope.labels.length > 0) {
+        lines.push(`**Labels:** ${envelope.labels.join(', ')}`);
+    }
+    lines.push(`**URL:** ${envelope.url}`);
+    if (envelope.description) {
+        lines.push('');
+        lines.push('## Description');
+        lines.push('');
+        lines.push(envelope.description);
+    }
+    return lines.join('\n');
+}
+/**
+ * Build metadata key-value pairs from an IssueEnvelope.
+ *
+ * These are stored as ticket metadata for traceability back to
+ * the external source.
+ */
+function buildMetadata(envelope) {
+    const metadata = {
+        'external_source': envelope.source,
+        'external_id': envelope.external_id,
+        'external_key': envelope.external_key,
+        'external_url': envelope.url,
+        'external_project': envelope.project_key,
+        'external_status': envelope.status,
+    };
+    if (envelope.priority) {
+        metadata['external_priority'] = envelope.priority;
+    }
+    if (envelope.assignee) {
+        metadata['external_assignee'] = envelope.assignee;
+    }
+    if (envelope.labels.length > 0) {
+        metadata['external_labels'] = envelope.labels.join(',');
+    }
+    if (envelope.item_type) {
+        metadata['external_item_type'] = envelope.item_type;
+    }
+    return metadata;
+}

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

@@ -0,0 +1,144 @@
+/**
+ * External Issue Adapter Types
+ *
+ * Canonical types for normalizing issues from external sources
+ * (Linear and Jira) into a shared IssueEnvelope format
+ * that can be mapped to spawn context.
+ */
+/**
+ * Supported external issue sources.
+ *
+ */
+export type IssueSource = 'linear' | 'jira';
+/**
+ * All valid issue sources as a const array.
+ */
+export declare const ISSUE_SOURCES: readonly ["linear", "jira"];
+/**
+ * Canonical envelope for external issues/work items.
+ *
+ * Normalizes issues from different sources into a shared structure that can be
+ * deterministically mapped to spawn context.
+ *
+ * Source-specific fields are preserved in the `raw` payload.
+ */
+export interface IssueEnvelope {
+    /** Which external system this issue came from */
+    source: IssueSource;
+    /** Unique identifier in the external system (e.g., Linear UUID, Jira issue ID) */
+    external_id: string;
+    /** Human-readable key in the external system (e.g., "ENG-123", "PROJ-456") */
+    external_key: string;
+    /** Issue title / summary */
+    title: string;
+    /** Issue description (markdown or plain text) */
+    description: string;
+    /** Labels / tags applied to the issue */
+    labels: string[];
+    /** Priority level (normalized to P0-P3 scale) */
+    priority: string | null;
+    /** Current status name in the external system */
+    status: string;
+    /** URL to view the issue in the external system */
+    url: string;
+    /** Project key or identifier in the external system */
+    project_key: string;
+    /** Assignee display name or identifier */
+    assignee: string | null;
+    /**
+     * Source-native work item kind when available (e.g., issue, ticket, task).
+     * Optional to preserve compatibility with adapters that do not expose a
+     * stable item kind.
+     */
+    item_type?: string | null;
+    /** Original source-specific payload (preserved for source-specific logic) */
+    raw: Record<string, unknown>;
+}
+/**
+ * Metadata derived from an IssueEnvelope for spawn context.
+ * Used to populate ExecutionContext fields when spawning agent work
+ * from an external issue.
+ */
+export interface IssueSpawnContext {
+    /** Prompt text generated from the issue for the agent */
+    prompt: string;
+    /** Metadata key-value pairs to attach to the ticket */
+    metadata: Record<string, string>;
+}
+/**
+ * Error codes for issue envelope validation failures.
+ */
+export type IssueValidationErrorCode = 'MISSING_FIELD' | 'INVALID_SOURCE' | 'INVALID_FIELD_TYPE' | 'EMPTY_FIELD';
+/**
+ * Structured validation error for issue envelope fields.
+ */
+export interface IssueValidationError {
+    /** Machine-readable error code */
+    code: IssueValidationErrorCode;
+    /** The field that failed validation */
+    field: string;
+    /** Human-readable error message */
+    message: string;
+}
+/**
+ * Result of validating an issue envelope.
+ */
+export type IssueValidationResult = {
+    valid: true;
+    envelope: IssueEnvelope;
+} | {
+    valid: false;
+    errors: IssueValidationError[];
+};
+/**
+ * Contract for external issue source adapters.
+ *
+ * Both Linear and Jira adapters must implement this interface to normalize
+ * their issues into the shared IssueEnvelope format.
+ *
+ * Adapters are responsible for:
+ * 1. Fetching issues from their source API
+ * 2. Normalizing source-specific data into IssueEnvelope format
+ * 3. Preserving source-specific fields in the `raw` payload
+ */
+export interface ExternalIssueAdapter {
+    /** Which source this adapter handles */
+    readonly source: IssueSource;
+    /**
+     * Normalize a raw API response into an IssueEnvelope.
+     *
+     * @param raw - Raw issue data from the source API
+     * @returns Validated IssueEnvelope
+     * @throws ExternalIssueError if the raw data cannot be normalized
+     */
+    normalize(raw: unknown): IssueEnvelope;
+    /**
+     * Fetch and normalize a single issue by its external key.
+     *
+     * @param key - External issue key (e.g., "ENG-123" for Linear, "PROJ-456" for Jira)
+     * @returns Normalized IssueEnvelope
+     * @throws ExternalIssueError if the issue cannot be fetched or normalized
+     */
+    fetchByKey(key: string): Promise<IssueEnvelope>;
+    /**
+     * Fetch and normalize multiple issues matching a query.
+     *
+     * @param query - Source-specific query parameters
+     * @returns Array of normalized IssueEnvelopes
+     * @throws ExternalIssueError if the query fails
+     */
+    fetchByQuery(query: Record<string, unknown>): Promise<IssueEnvelope[]>;
+}
+/**
+ * Error codes for external issue operations.
+ */
+export type ExternalIssueErrorCode = 'VALIDATION_FAILED' | 'FETCH_FAILED' | 'NORMALIZE_FAILED' | 'SOURCE_NOT_SUPPORTED';
+/**
+ * Typed error for external issue operations.
+ */
+export declare class ExternalIssueError extends Error {
+    code: ExternalIssueErrorCode;
+    source?: IssueSource | undefined;
+    validationErrors?: IssueValidationError[] | undefined;
+    constructor(code: ExternalIssueErrorCode, message: string, source?: IssueSource | undefined, validationErrors?: IssueValidationError[] | undefined);
+}