@proletariat/cli 0.3.47 → 0.3.48

package/dist/lib/caffeinate.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Caffeinate management for macOS
+ *
+ * Manages a background `caffeinate` process to prevent macOS from sleeping.
+ * PID state is stored in a runtime file for reliable stop/status operations.
+ */
+export interface CaffeinateState {
+    pid: number;
+    startedAt: string;
+    flags: string[];
+    duration?: number;
+}
+/**
+ * Ensure the platform is macOS. Throws a descriptive error on other platforms.
+ */
+export declare function assertMacOS(): void;
+/**
+ * Check whether the platform is macOS.
+ */
+export declare function isMacOS(): boolean;
+/**
+ * Read the stored caffeinate state from the PID file.
+ * Returns null if no state exists or the file is invalid.
+ */
+export declare function readState(): CaffeinateState | null;
+/**
+ * Write caffeinate state to the PID file.
+ */
+export declare function writeState(state: CaffeinateState): void;
+/**
+ * Remove the PID file.
+ */
+export declare function clearState(): void;
+/**
+ * Check whether a process with the given PID is still running.
+ */
+export declare function isProcessRunning(pid: number): boolean;
+/**
+ * Get the status of the managed caffeinate process.
+ * Cleans up stale state if the process is no longer running.
+ */
+export declare function getStatus(): {
+    running: boolean;
+    state: CaffeinateState | null;
+};
+/**
+ * Start a background caffeinate process.
+ *
+ * @param flags - Additional flags to pass to caffeinate (e.g. ['-d', '-i'])
+ * @param duration - Optional duration in seconds (passed as -t flag)
+ * @returns The state of the started process
+ * @throws If already running (idempotent guard) or on non-macOS
+ */
+export declare function startCaffeinate(flags?: string[], duration?: number): CaffeinateState;
+/**
+ * Stop the managed caffeinate process.
+ *
+ * @returns true if a process was stopped, false if nothing was running
+ */
+export declare function stopCaffeinate(): boolean;
+export declare const _internals: {
+    RUNTIME_DIR: string;
+    PID_FILE: string;
+};

package/dist/lib/caffeinate.js

@@ -0,0 +1,146 @@
+/**
+ * Caffeinate management for macOS
+ *
+ * Manages a background `caffeinate` process to prevent macOS from sleeping.
+ * PID state is stored in a runtime file for reliable stop/status operations.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { spawn } from 'node:child_process';
+const RUNTIME_DIR = path.join(os.tmpdir(), 'prlt');
+const PID_FILE = path.join(RUNTIME_DIR, 'caffeinate.pid');
+/**
+ * Ensure the platform is macOS. Throws a descriptive error on other platforms.
+ */
+export function assertMacOS() {
+    if (process.platform !== 'darwin') {
+        throw new Error(`caffeinate is only supported on macOS (current platform: ${process.platform})`);
+    }
+}
+/**
+ * Check whether the platform is macOS.
+ */
+export function isMacOS() {
+    return process.platform === 'darwin';
+}
+/**
+ * Read the stored caffeinate state from the PID file.
+ * Returns null if no state exists or the file is invalid.
+ */
+export function readState() {
+    try {
+        const data = fs.readFileSync(PID_FILE, 'utf-8');
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write caffeinate state to the PID file.
+ */
+export function writeState(state) {
+    fs.mkdirSync(RUNTIME_DIR, { recursive: true });
+    fs.writeFileSync(PID_FILE, JSON.stringify(state, null, 2));
+}
+/**
+ * Remove the PID file.
+ */
+export function clearState() {
+    try {
+        fs.unlinkSync(PID_FILE);
+    }
+    catch {
+        // File may not exist - that's fine
+    }
+}
+/**
+ * Check whether a process with the given PID is still running.
+ */
+export function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get the status of the managed caffeinate process.
+ * Cleans up stale state if the process is no longer running.
+ */
+export function getStatus() {
+    const state = readState();
+    if (!state) {
+        return { running: false, state: null };
+    }
+    if (!isProcessRunning(state.pid)) {
+        // Process died externally - clean up stale PID file
+        clearState();
+        return { running: false, state: null };
+    }
+    return { running: true, state };
+}
+/**
+ * Start a background caffeinate process.
+ *
+ * @param flags - Additional flags to pass to caffeinate (e.g. ['-d', '-i'])
+ * @param duration - Optional duration in seconds (passed as -t flag)
+ * @returns The state of the started process
+ * @throws If already running (idempotent guard) or on non-macOS
+ */
+export function startCaffeinate(flags = [], duration) {
+    assertMacOS();
+    // Idempotent: if already running, return existing state
+    const { running, state: existingState } = getStatus();
+    if (running && existingState) {
+        return existingState;
+    }
+    const args = [...flags];
+    if (duration !== undefined && duration > 0) {
+        args.push('-t', String(duration));
+    }
+    const child = spawn('caffeinate', args, {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    if (!child.pid) {
+        throw new Error('Failed to start caffeinate process');
+    }
+    const state = {
+        pid: child.pid,
+        startedAt: new Date().toISOString(),
+        flags: args,
+        ...(duration !== undefined && duration > 0 ? { duration } : {}),
+    };
+    writeState(state);
+    return state;
+}
+/**
+ * Stop the managed caffeinate process.
+ *
+ * @returns true if a process was stopped, false if nothing was running
+ */
+export function stopCaffeinate() {
+    const { running, state } = getStatus();
+    if (!running || !state) {
+        clearState(); // Clean up any stale file
+        return false;
+    }
+    try {
+        process.kill(state.pid, 'SIGTERM');
+    }
+    catch {
+        // Process may have already exited
+    }
+    clearState();
+    return true;
+}
+// Exported for testing
+export const _internals = {
+    RUNTIME_DIR,
+    PID_FILE,
+};

package/dist/lib/execution/codex-adapter.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Codex Runtime Adapter
+ *
+ * Explicitly maps permission modes and execution contexts to Codex CLI invocations.
+ * Validates that the requested combination is supported and returns a deterministic
+ * command configuration.
+ *
+ * ## Codex Mode Mapping
+ *
+ * Codex has two permission modes:
+ *   - `--yolo`    (danger): Execute commands autonomously without approval prompts
+ *   - (default)   (safe):   Prompt the user for approval before running commands
+ *
+ * Codex execution contexts:
+ *   - Interactive terminal: User is watching in a TTY (terminal tab, foreground tmux)
+ *   - Background/detached:  Running in a tmux session, no direct TTY attached at start
+ *   - Non-TTY:              Piped output, CI, Docker detached — no TTY available
+ *
+ * ## Supported Combinations
+ *
+ * | Permission | Context       | Supported | Notes                                    |
+ * |------------|---------------|-----------|------------------------------------------|
+ * | danger     | interactive   | Yes       | `codex --yolo --prompt "..."`            |
+ * | danger     | background    | Yes       | `codex --yolo --prompt "..."`            |
+ * | danger     | non-tty       | Yes       | `codex --yolo --prompt "..."`            |
+ * | safe       | interactive   | Yes       | `codex --prompt "..."` (user can approve)|
+ * | safe       | background    | No        | Cannot prompt for approval in background |
+ * | safe       | non-tty       | No        | Cannot prompt for approval without TTY   |
+ */
+import type { DisplayMode, OutputMode, PermissionMode } from './types.js';
+/**
+ * The execution context determines whether Codex can interact with a user.
+ *
+ * - interactive: Running in a TTY where the user can see prompts and respond
+ * - background:  Running detached (tmux background, no terminal tab open)
+ * - non-tty:     No TTY at all (piped, Docker -d, CI runner)
+ */
+export type CodexExecutionContext = 'interactive' | 'background' | 'non-tty';
+/**
+ * Error thrown when an unsupported Codex mode combination is requested.
+ */
+export declare class CodexModeError extends Error {
+    readonly permissionMode: PermissionMode;
+    readonly executionContext: CodexExecutionContext;
+    constructor(permissionMode: PermissionMode, executionContext: CodexExecutionContext);
+}
+/**
+ * The resolved command and arguments for invoking Codex.
+ */
+export interface CodexCommandResult {
+    cmd: 'codex';
+    args: string[];
+    /** Whether --yolo (autonomous mode) is active */
+    yolo: boolean;
+    /** The resolved execution context */
+    executionContext: CodexExecutionContext;
+}
+/**
+ * Derive the Codex execution context from proletariat display mode and output mode.
+ *
+ * Maps proletariat's display/output dimensions to Codex's execution context:
+ * - terminal + interactive → interactive (user is watching, TTY available)
+ * - foreground + interactive → interactive
+ * - terminal + print → non-tty (output is piped, no interaction)
+ * - background + any → background (detached tmux, no direct TTY)
+ * - foreground + print → non-tty
+ */
+export declare function resolveCodexExecutionContext(displayMode: DisplayMode, outputMode: OutputMode): CodexExecutionContext;
+/**
+ * Check whether a Codex mode combination is supported.
+ * Returns null if valid, or a CodexModeError if the combination is unsupported.
+ */
+export declare function validateCodexMode(permissionMode: PermissionMode, executionContext: CodexExecutionContext): CodexModeError | null;
+/**
+ * Build the Codex CLI command for a given permission mode and execution context.
+ *
+ * This is the single source of truth for Codex invocation. All runners should
+ * use this function (via getCodexCommand or getCodexCommandFromConfig) rather
+ * than building Codex CLI args inline.
+ *
+ * @throws CodexModeError if the combination is unsupported
+ */
+export declare function getCodexCommand(prompt: string, permissionMode: PermissionMode, executionContext: CodexExecutionContext): CodexCommandResult;
+/**
+ * Build the Codex CLI command from proletariat config values.
+ *
+ * Convenience wrapper that resolves execution context from display/output mode
+ * before delegating to getCodexCommand().
+ *
+ * @param prompt - The prompt text for Codex
+ * @param sandboxed - If true, use safe mode; if false, use danger mode
+ * @param displayMode - How the agent output is displayed
+ * @param outputMode - Whether output is interactive or print
+ * @throws CodexModeError if the resolved combination is unsupported
+ */
+export declare function getCodexCommandFromConfig(prompt: string, sandboxed: boolean, displayMode?: DisplayMode, outputMode?: OutputMode): CodexCommandResult;

package/dist/lib/execution/codex-adapter.js

@@ -0,0 +1,148 @@
+/**
+ * Codex Runtime Adapter
+ *
+ * Explicitly maps permission modes and execution contexts to Codex CLI invocations.
+ * Validates that the requested combination is supported and returns a deterministic
+ * command configuration.
+ *
+ * ## Codex Mode Mapping
+ *
+ * Codex has two permission modes:
+ *   - `--yolo`    (danger): Execute commands autonomously without approval prompts
+ *   - (default)   (safe):   Prompt the user for approval before running commands
+ *
+ * Codex execution contexts:
+ *   - Interactive terminal: User is watching in a TTY (terminal tab, foreground tmux)
+ *   - Background/detached:  Running in a tmux session, no direct TTY attached at start
+ *   - Non-TTY:              Piped output, CI, Docker detached — no TTY available
+ *
+ * ## Supported Combinations
+ *
+ * | Permission | Context       | Supported | Notes                                    |
+ * |------------|---------------|-----------|------------------------------------------|
+ * | danger     | interactive   | Yes       | `codex --yolo --prompt "..."`            |
+ * | danger     | background    | Yes       | `codex --yolo --prompt "..."`            |
+ * | danger     | non-tty       | Yes       | `codex --yolo --prompt "..."`            |
+ * | safe       | interactive   | Yes       | `codex --prompt "..."` (user can approve)|
+ * | safe       | background    | No        | Cannot prompt for approval in background |
+ * | safe       | non-tty       | No        | Cannot prompt for approval without TTY   |
+ */
+// =============================================================================
+// Codex Adapter Errors
+// =============================================================================
+/**
+ * Error thrown when an unsupported Codex mode combination is requested.
+ */
+export class CodexModeError extends Error {
+    permissionMode;
+    executionContext;
+    constructor(permissionMode, executionContext) {
+        const message = buildModeErrorMessage(permissionMode, executionContext);
+        super(message);
+        this.name = 'CodexModeError';
+        this.permissionMode = permissionMode;
+        this.executionContext = executionContext;
+    }
+}
+function buildModeErrorMessage(permissionMode, executionContext) {
+    if (permissionMode === 'safe' && executionContext === 'background') {
+        return (`Codex safe mode cannot run in background: Codex needs a TTY to prompt for approval. ` +
+            `Either use danger mode (--yolo) for background execution, or run in a terminal where you can interact with Codex.`);
+    }
+    if (permissionMode === 'safe' && executionContext === 'non-tty') {
+        return (`Codex safe mode requires an interactive terminal: Codex needs a TTY to prompt for approval. ` +
+            `Either use danger mode (--yolo) for non-interactive execution, or run in a terminal where you can interact with Codex.`);
+    }
+    return `Unsupported Codex mode combination: permission=${permissionMode}, context=${executionContext}`;
+}
+// =============================================================================
+// Context Resolution
+// =============================================================================
+/**
+ * Derive the Codex execution context from proletariat display mode and output mode.
+ *
+ * Maps proletariat's display/output dimensions to Codex's execution context:
+ * - terminal + interactive → interactive (user is watching, TTY available)
+ * - foreground + interactive → interactive
+ * - terminal + print → non-tty (output is piped, no interaction)
+ * - background + any → background (detached tmux, no direct TTY)
+ * - foreground + print → non-tty
+ */
+export function resolveCodexExecutionContext(displayMode, outputMode) {
+    // Background display is always background context regardless of output mode
+    if (displayMode === 'background') {
+        return 'background';
+    }
+    // Print mode means output is captured/piped, no interactive TTY
+    if (outputMode === 'print') {
+        return 'non-tty';
+    }
+    // Terminal or foreground with interactive output = interactive
+    return 'interactive';
+}
+// =============================================================================
+// Mode Validation
+// =============================================================================
+/**
+ * Check whether a Codex mode combination is supported.
+ * Returns null if valid, or a CodexModeError if the combination is unsupported.
+ */
+export function validateCodexMode(permissionMode, executionContext) {
+    // Danger mode works in all contexts — no user interaction needed
+    if (permissionMode === 'danger') {
+        return null;
+    }
+    // Safe mode requires an interactive terminal for approval prompts
+    if (executionContext === 'interactive') {
+        return null;
+    }
+    return new CodexModeError(permissionMode, executionContext);
+}
+// =============================================================================
+// Command Builder
+// =============================================================================
+/**
+ * Build the Codex CLI command for a given permission mode and execution context.
+ *
+ * This is the single source of truth for Codex invocation. All runners should
+ * use this function (via getCodexCommand or getCodexCommandFromConfig) rather
+ * than building Codex CLI args inline.
+ *
+ * @throws CodexModeError if the combination is unsupported
+ */
+export function getCodexCommand(prompt, permissionMode, executionContext) {
+    // Validate the combination
+    const error = validateCodexMode(permissionMode, executionContext);
+    if (error) {
+        throw error;
+    }
+    const yolo = permissionMode === 'danger';
+    const args = [];
+    if (yolo) {
+        args.push('--yolo');
+    }
+    args.push('--prompt', prompt);
+    return {
+        cmd: 'codex',
+        args,
+        yolo,
+        executionContext,
+    };
+}
+/**
+ * Build the Codex CLI command from proletariat config values.
+ *
+ * Convenience wrapper that resolves execution context from display/output mode
+ * before delegating to getCodexCommand().
+ *
+ * @param prompt - The prompt text for Codex
+ * @param sandboxed - If true, use safe mode; if false, use danger mode
+ * @param displayMode - How the agent output is displayed
+ * @param outputMode - Whether output is interactive or print
+ * @throws CodexModeError if the resolved combination is unsupported
+ */
+export function getCodexCommandFromConfig(prompt, sandboxed, displayMode = 'terminal', outputMode = 'interactive') {
+    const permissionMode = sandboxed ? 'safe' : 'danger';
+    const executionContext = resolveCodexExecutionContext(displayMode, outputMode);
+    return getCodexCommand(prompt, permissionMode, executionContext);
+}

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.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':
@@ -382,6 +388,15 @@ export async function runHost(context, executor, config, displayMode = 'terminal
     const prompt = buildPrompt(context);
     // Terminal - use sandboxed setting
     const skipPermissions = !config.sandboxed;
+    // Validate Codex mode combination before proceeding
+    if (executor === 'codex') {
+        const codexPermission = config.sandboxed ? 'safe' : 'danger';
+        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
@@ -1246,8 +1261,21 @@ export function buildDevcontainerCommand(context, executor, promptFile, containe
         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 = sandboxed ? 'safe' : 'danger';
+        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
+        // Non-Claude, non-Codex executors: use getExecutorCommand() to get correct command and args
         const { cmd, args } = getExecutorCommand(executor, `PLACEHOLDER`, !sandboxed);
         // Replace the placeholder prompt with a file read for shell safety
         const argsStr = args.map(a => a === 'PLACEHOLDER' ? `"$(cat ${promptFile})"` : a).join(' ');
@@ -1987,6 +2015,14 @@ 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.sandboxed ? 'safe' : 'danger';
+            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);
@@ -2049,6 +2085,14 @@ 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.sandboxed ? 'safe' : 'danger';
+            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);

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,37 @@
+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 and normalize Linear issues into NormalizedIssueEnvelopes.
+ */
+export declare function listLinearIssues(configInput: LinearAdapterConfig, options?: {
+    limit?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<NormalizedIssueEnvelope[]>;