@proletariat/cli 0.3.16 → 0.3.18

package/dist/lib/database/drizzle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Drizzle ORM Database Connection
+ *
+ * This module provides type-safe database connections using Drizzle ORM
+ * with better-sqlite3 as the underlying driver.
+ */
+import { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import Database from 'better-sqlite3';
+import * as schema from './drizzle-schema.js';
+export type DrizzleDB = BetterSQLite3Database<typeof schema>;
+/**
+ * Create a Drizzle database connection from an existing better-sqlite3 database.
+ * This allows gradual migration by wrapping existing database connections.
+ */
+export declare function createDrizzleConnection(db: Database.Database): DrizzleDB;
+/**
+ * Create a new Drizzle database connection from a file path.
+ * Configures pragmas for optimal performance and reliability.
+ */
+export declare function openDrizzleDatabase(dbPath: string): {
+    db: DrizzleDB;
+    sqliteDb: Database.Database;
+};
+/**
+ * Close a Drizzle database connection.
+ * Since Drizzle wraps better-sqlite3, we need to close the underlying connection.
+ */
+export declare function closeDrizzleDatabase(sqliteDb: Database.Database): void;
+export * from './drizzle-schema.js';

package/dist/lib/database/drizzle.js

@@ -0,0 +1,37 @@
+/**
+ * Drizzle ORM Database Connection
+ *
+ * This module provides type-safe database connections using Drizzle ORM
+ * with better-sqlite3 as the underlying driver.
+ */
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import Database from 'better-sqlite3';
+import * as schema from './drizzle-schema.js';
+/**
+ * Create a Drizzle database connection from an existing better-sqlite3 database.
+ * This allows gradual migration by wrapping existing database connections.
+ */
+export function createDrizzleConnection(db) {
+    return drizzle(db, { schema });
+}
+/**
+ * Create a new Drizzle database connection from a file path.
+ * Configures pragmas for optimal performance and reliability.
+ */
+export function openDrizzleDatabase(dbPath) {
+    const sqliteDb = new Database(dbPath);
+    // Configure pragmas
+    sqliteDb.pragma('foreign_keys = ON');
+    sqliteDb.pragma('busy_timeout = 5000'); // Wait up to 5 seconds if database is locked
+    const db = drizzle(sqliteDb, { schema });
+    return { db, sqliteDb };
+}
+/**
+ * Close a Drizzle database connection.
+ * Since Drizzle wraps better-sqlite3, we need to close the underlying connection.
+ */
+export function closeDrizzleDatabase(sqliteDb) {
+    sqliteDb.close();
+}
+// Re-export schema for convenience
+export * from './drizzle-schema.js';

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

@@ -52,6 +52,7 @@ export interface AgentWorktree {
     is_clean: boolean;
     last_checked?: string;
 }
+export declare const CREATE_TABLES_SQL = "\n-- Core workspace metadata\nCREATE TABLE IF NOT EXISTS workspace (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  type TEXT NOT NULL CHECK (type IN ('hq', 'workspace')),\n  workspace_name TEXT NOT NULL,\n  has_pmo BOOLEAN DEFAULT FALSE,\n  active_theme_id TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (active_theme_id) REFERENCES agent_themes(id) ON DELETE SET NULL\n);\n\n-- Repository management\nCREATE TABLE IF NOT EXISTS repositories (\n  name TEXT PRIMARY KEY,\n  path TEXT NOT NULL,\n  type TEXT DEFAULT 'main' CHECK (type IN ('main', 'dependency')),\n  source_url TEXT,\n  action TEXT CHECK (action IN ('clone', 'move', 'link')),\n  added_at TEXT NOT NULL\n);\n\n-- Agent naming themes (optional)\nCREATE TABLE IF NOT EXISTS agent_themes (\n  id TEXT PRIMARY KEY,\n  name TEXT NOT NULL UNIQUE,\n  display_name TEXT NOT NULL,\n  description TEXT,\n  builtin BOOLEAN DEFAULT FALSE,\n  created_at TEXT NOT NULL\n);\n\n-- Names available within each theme\nCREATE TABLE IF NOT EXISTS agent_theme_names (\n  theme_id TEXT NOT NULL,\n  name TEXT NOT NULL,\n  PRIMARY KEY (theme_id, name),\n  FOREIGN KEY (theme_id) REFERENCES agent_themes(id) ON DELETE CASCADE\n);\n\n-- Agent instances in workspace\nCREATE TABLE IF NOT EXISTS agents (\n  name TEXT PRIMARY KEY,\n  type TEXT NOT NULL DEFAULT 'persistent' CHECK (type IN ('persistent', 'ephemeral')),\n  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'cleaned')),\n  base_name TEXT,\n  theme_id TEXT,\n  worktree_path TEXT,\n  mount_mode TEXT NOT NULL DEFAULT 'worktree' CHECK (mount_mode IN ('worktree', 'clone')),\n  created_at TEXT NOT NULL,\n  cleaned_at TEXT,\n  FOREIGN KEY (theme_id) REFERENCES agent_themes(id) ON DELETE SET NULL\n);\n\n-- Agent-owned worktrees\nCREATE TABLE IF NOT EXISTS agent_worktrees (\n  agent_name TEXT NOT NULL,\n  repo_name TEXT NOT NULL,\n  worktree_path TEXT NOT NULL,\n  branch TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  PRIMARY KEY (agent_name, repo_name),\n  FOREIGN KEY (agent_name) REFERENCES agents(name) ON DELETE CASCADE,\n  FOREIGN KEY (repo_name) REFERENCES repositories(name) ON DELETE CASCADE\n);\n\n-- Workspace-level settings (key-value store)\nCREATE TABLE IF NOT EXISTS workspace_settings (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL\n);\n\n-- =============================================================================\n-- Indexes\n-- =============================================================================\n\nCREATE INDEX IF NOT EXISTS idx_worktrees_agent ON agent_worktrees(agent_name);\nCREATE INDEX IF NOT EXISTS idx_worktrees_repo ON agent_worktrees(repo_name);\nCREATE INDEX IF NOT EXISTS idx_theme_names_theme ON agent_theme_names(theme_id);\nCREATE INDEX IF NOT EXISTS idx_agents_theme ON agents(theme_id);\n";
 /**
  * Get the database path for a workspace
  */

package/dist/lib/database/index.js

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getThemePersistentDir, isEphemeralAgentName } from '../themes.js';
 import { PMO_SCHEMA_SQL } from '../pmo/schema.js';
-const CREATE_TABLES_SQL = `
+export const CREATE_TABLES_SQL = `
 -- Core workspace metadata
 CREATE TABLE IF NOT EXISTS workspace (
   id INTEGER PRIMARY KEY CHECK (id = 1),

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

@@ -6,6 +6,7 @@
  */
 import Database from 'better-sqlite3';
 import { ExecutionConfig, TerminalApp, Shell, DisplayMode, OutputMode, ExecutionEnvironment } from './types.js';
+import { type JsonFlags } from '../prompt-json.js';
 declare const CONFIG_KEYS: {
     terminalApp: string;
     terminalOpenInBackground: string;
@@ -106,6 +107,11 @@ export interface ExecutionPromptOptions {
     reconfigure?: boolean;
     /** Log function for status messages */
     log?: (msg: string) => void;
+    /** JSON mode configuration for AI agents */
+    jsonMode?: {
+        flags: JsonFlags & Record<string, unknown>;
+        commandName: string;
+    };
 }
 export interface ExecutionPromptResult {
     /** Execution config with terminal/shell/output settings */

package/dist/lib/execution/config.js

@@ -7,6 +7,7 @@
 import inquirer from 'inquirer';
 import { DEFAULT_EXECUTION_CONFIG } from './types.js';
 import { isGHInstalled, isGHAuthenticated } from '../pr/index.js';
+import { shouldOutputJson, outputPromptAsJson, createMetadata, buildPromptConfig, } from '../prompt-json.js';
 import { execSync } from 'node:child_process';
 const SETTINGS_TABLE = 'workspace_settings';
 // Config keys stored in workspace_settings table
@@ -342,7 +343,9 @@ export async function getShell(db) {
  * Used by work start, work spawn, and work watch commands.
  */
 export async function promptExecutionSettings(db, options) {
-    const { displayMode, environment, log = () => { } } = options;
+    const { displayMode, environment, log = () => { }, jsonMode } = options;
+    // Check if JSON mode is active
+    const isJsonMode = jsonMode && shouldOutputJson(jsonMode.flags);
     // Load execution config from database
     const executionConfig = loadExecutionConfig(db);
     // If terminal display mode, ensure terminal and shell preferences are set (prompts on first use)
@@ -373,15 +376,20 @@ export async function promptExecutionSettings(db, options) {
     let outputMode = options.outputMode ?? DEFAULT_EXECUTION_CONFIG.outputMode;
     const streamingDisplayModes = ['terminal'];
     if (options.outputMode === undefined && streamingDisplayModes.includes(displayMode)) {
+        const outputChoices = [
+            { name: 'interactive  - Watch Claude work in real-time (streaming UI)', value: 'interactive' },
+            { name: 'print        - Show final result only (better for logs)', value: 'print' },
+        ];
+        // In JSON mode, output the output mode prompt
+        if (isJsonMode && jsonMode) {
+            outputPromptAsJson(buildPromptConfig('list', 'selectedOutputMode', 'How should Claude display output?', outputChoices, 'interactive'), createMetadata(jsonMode.commandName, jsonMode.flags));
+        }
         const { selectedOutputMode } = await inquirer.prompt([
             {
                 type: 'list',
                 name: 'selectedOutputMode',
                 message: 'How should Claude display output?',
-                choices: [
-                    { name: 'interactive  - Watch Claude work in real-time (streaming UI)', value: 'interactive' },
-                    { name: 'print        - Show final result only (better for logs)', value: 'print' },
-                ],
+                choices: outputChoices,
                 default: 'interactive',
             },
         ]);
@@ -394,15 +402,20 @@ export async function promptExecutionSettings(db, options) {
         const containerNote = (environment === 'devcontainer' || environment === 'docker')
             ? ' (container provides additional isolation)'
             : '';
+        const permissionChoices = [
+            { name: '🔒 safe   - Requires approval for dangerous operations (recommended)', value: 'safe' },
+            { name: '⚠️  danger - Skip permission checks (--dangerously-skip-permissions)', value: 'danger' },
+        ];
+        // In JSON mode, output the permissions prompt
+        if (isJsonMode && jsonMode) {
+            outputPromptAsJson(buildPromptConfig('list', 'permissionMode', `Permission mode for Claude Code${containerNote}:`, permissionChoices, 'safe'), createMetadata(jsonMode.commandName, jsonMode.flags));
+        }
         const { permissionMode } = await inquirer.prompt([
             {
                 type: 'list',
                 name: 'permissionMode',
                 message: `Permission mode for Claude Code${containerNote}:`,
-                choices: [
-                    { name: '🔒 safe   - Requires approval for dangerous operations (recommended)', value: 'safe' },
-                    { name: '⚠️  danger - Skip permission checks (--dangerously-skip-permissions)', value: 'danger' },
-                ],
+                choices: permissionChoices,
                 default: 'safe',
             },
         ]);
@@ -413,15 +426,20 @@ export async function promptExecutionSettings(db, options) {
     if (options.createPR === undefined) {
         const ghAvailable = isGHInstalled() && isGHAuthenticated();
         if (ghAvailable) {
+            const prChoices = [
+                { name: '✓ Yes - Create PR when running `prlt work ready`', value: 'yes' },
+                { name: '✗ No  - Just move ticket to review (can create PR later)', value: 'no' },
+            ];
+            // In JSON mode, output the PR creation prompt
+            if (isJsonMode && jsonMode) {
+                outputPromptAsJson(buildPromptConfig('list', 'prChoice', 'Create a pull request when work is ready?', prChoices, 'yes'), createMetadata(jsonMode.commandName, jsonMode.flags));
+            }
             const { prChoice } = await inquirer.prompt([
                 {
                     type: 'list',
                     name: 'prChoice',
                     message: 'Create a pull request when work is ready?',
-                    choices: [
-                        { name: '✓ Yes - Create PR when running `prlt work ready`', value: 'yes' },
-                        { name: '✗ No  - Just move ticket to review (can create PR later)', value: 'no' },
-                    ],
+                    choices: prChoices,
                     default: 'yes',
                 },
             ]);

package/dist/lib/execution/devcontainer.js

@@ -36,32 +36,37 @@ export function generateDevcontainerJson(options, config) {
         buildArgs.GITHUB_TOKEN = '${localEnv:GITHUB_TOKEN}';
     }
     // Build mounts array - parent repo mounts only needed for worktree mode
+    // TKT-801: Use consistency=cached to reduce grpcfuse contention on Docker Desktop.
+    // This helps prevent kernel panics when multiple containers mount the same paths concurrently.
     const mounts = [
-        'source=${localWorkspaceFolder},target=/workspace,type=bind',
+        'source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached',
         'source=claude-bash-history,target=/commandhistory,type=volume',
         'source=claude-credentials,target=/home/node/.claude,type=volume',
         // NOTE: ~/.claude.json is COPIED (not mounted) to /workspace/.claude.json
         // to avoid corruption from concurrent writes by multiple containers
         // NOTE: SSH agent socket mounting doesn't work reliably on Docker Desktop for Mac
         // So we use HTTPS + token approach instead. The token is fetched fresh at spawn time.
-        'source=${localEnv:PRLT_HQ_PATH}/.proletariat,target=/hq/.proletariat,type=bind',
+        'source=${localEnv:PRLT_HQ_PATH}/.proletariat,target=/hq/.proletariat,type=bind,consistency=cached',
         // PMO path can be anywhere (e.g., /hq/pmo or /hq/repos/myrepo/pmo)
         // Use PRLT_PMO_PATH env var to mount the actual location to /hq/pmo
-        'source=${localEnv:PRLT_PMO_PATH},target=/hq/pmo,type=bind',
+        'source=${localEnv:PRLT_PMO_PATH},target=/hq/pmo,type=bind,consistency=cached',
     ];
     // Only add parent repo mounts for worktree mode
     // Worktree .git files reference paths like /Users/.../repos/{repoName}/.git/worktrees/name
     // These mounts make those paths accessible inside the container at /hq/repos/{repoName}
     // Clone mode doesn't need this because each clone has its own self-contained .git directory
+    // NOTE: Cannot use readonly because git worktrees share the object store with parent repo.
+    // Commits write to parent's .git/objects/ and refs update in .git/worktrees/<name>/
     if (mountMode === 'worktree' && options.repoWorktrees) {
         for (const repoName of options.repoWorktrees) {
-            mounts.push(`source=\${localEnv:PRLT_HQ_PATH}/repos/${repoName},target=/hq/repos/${repoName},type=bind`);
+            mounts.push(`source=\${localEnv:PRLT_HQ_PATH}/repos/${repoName},target=/hq/repos/${repoName},type=bind,consistency=cached`);
         }
     }
     // If using "mount" channel, mount local prlt build from PRLT_REPO_PATH
     // The setup-prlt.sh script will detect /opt/prlt and configure the wrapper
+    // TKT-801: Use readonly,consistency=cached to reduce grpcfuse contention
     if (useMount) {
-        mounts.push('source=${localEnv:PRLT_REPO_PATH},target=/opt/prlt,type=bind,readonly');
+        mounts.push('source=${localEnv:PRLT_REPO_PATH},target=/opt/prlt,type=bind,readonly,consistency=cached');
     }
     const devcontainerJson = {
         name: `Agent: ${options.agentName}`,
@@ -470,7 +475,7 @@ if [ -d "/opt/prlt/apps/cli" ]; then
         # Install only better-sqlite3 with correct architecture
         cd "$PRLT_LOCAL"
         npm init -y > /dev/null 2>&1
-        npm install better-sqlite3@11.6.0 --build-from-source 2>&1 || {
+        npm install better-sqlite3@12.6.2 --build-from-source 2>&1 || {
             echo "Warning: better-sqlite3 rebuild failed"
         }
 
@@ -601,8 +606,9 @@ export function updateDevcontainerMounts(agentDir, _repoWorktrees) {
     // Use single mount for entire workspace - includes all repos and temp files
     // NOTE: ~/.claude.json is COPIED (not mounted) to /workspace/.claude.json
     // to avoid corruption from concurrent writes by multiple containers
+    // TKT-801: Use consistency=cached to reduce grpcfuse contention on Docker Desktop
     devcontainerJson.mounts = [
-        'source=${localWorkspaceFolder},target=/workspace,type=bind',
+        'source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached',
         'source=claude-bash-history,target=/commandhistory,type=volume',
         'source=claude-credentials,target=/home/node/.claude,type=volume',
     ];

package/dist/lib/execution/runners.js

@@ -735,17 +735,23 @@ function createDockerContainer(context, containerName, imageName, config) {
     // KEY: Use a named Docker volume for Claude credentials - this is how devcontainer.json
     // was handling it. The volume persists across containers, so login once = logged in everywhere.
     // This avoids corruption from concurrent writes to host filesystem.
+    //
+    // TKT-801: Use :cached mount option to reduce grpcfuse contention on Docker Desktop.
+    // This improves performance and helps prevent kernel panics when multiple containers
+    // mount the same paths concurrently.
     const mounts = [
         // Agent workspace
-        `-v "${context.agentDir}:/workspace"`,
-        // HQ .proletariat directory (for database access)
-        ...(context.hqPath ? [`-v "${context.hqPath}/.proletariat:/hq/.proletariat"`] : []),
-        // PMO path
-        ...(context.pmoPath ? [`-v "${context.pmoPath}:/hq/pmo"`] : []),
-        // Mount parent repos for git worktree resolution
+        `-v "${context.agentDir}:/workspace:cached"`,
+        // HQ .proletariat directory (for database access) - use :cached to reduce contention
+        ...(context.hqPath ? [`-v "${context.hqPath}/.proletariat:/hq/.proletariat:cached"`] : []),
+        // PMO path - use :cached to reduce contention
+        ...(context.pmoPath ? [`-v "${context.pmoPath}:/hq/pmo:cached"`] : []),
+        // Mount parent repos for git worktree resolution - use :cached to reduce contention
+        // NOTE: Cannot use :ro because git worktrees share the object store with parent repo.
+        // Commits write to parent's .git/objects/ and refs update in .git/worktrees/<name>/
         // Worktree .git files reference paths like /Users/.../repos/{repoName}/.git/worktrees/name
         // These mounts make those paths accessible inside the container at /hq/repos/{repoName}
-        ...(context.repoWorktrees || []).map(repoName => `-v "${context.hqPath}/repos/${repoName}:/hq/repos/${repoName}"`),
+        ...(context.repoWorktrees || []).map(repoName => `-v "${context.hqPath}/repos/${repoName}:/hq/repos/${repoName}:cached"`),
         // Claude credentials - shared named volume (login once, all containers share)
         `-v "claude-credentials:/home/node/.claude"`,
     ];
@@ -814,6 +820,17 @@ function runContainerSetup(containerId, sandboxed = true) {
         console.debug(`[runners:docker] Container setup scripts failed:`, error);
         // Continue - setup might partially work
     }
+    // Configure pnpm to use container-local store to prevent contention
+    // Multiple agents sharing the same pnpm store causes hangs and ERR_PNPM errors (TKT-718)
+    // Each container gets its own store at /tmp/pnpm-store for reliability
+    try {
+        execSync(`docker exec ${containerId} pnpm config set store-dir /tmp/pnpm-store`, { stdio: 'pipe' });
+        console.debug(`[runners:docker] Configured pnpm store-dir to /tmp/pnpm-store`);
+    }
+    catch (error) {
+        console.debug(`[runners:docker] Failed to configure pnpm store (pnpm may not be installed):`, error);
+        // Non-fatal - pnpm may not be installed in all containers
+    }
     // Copy Claude settings file (.claude.json) from host to container
     // This is needed for Claude Code to recognize settings and bypass prompts
     // Note: Auth tokens are in the claude-credentials volume at /home/node/.claude/.credentials.json

package/dist/lib/execution/spawner.js

@@ -77,6 +77,16 @@ function findBaseBranchInContainer(containerId, containerRepoPath, candidates =
     return 'HEAD';
 }
 // =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Delay between container spawns to prevent Docker kernel panics (TKT-801).
+ * When spawning multiple agents simultaneously, Docker Desktop on Apple Silicon
+ * can hit kernel panics in grpcfuse (file sharing layer) due to spinlock
+ * contention when all agents mount the same shared volumes concurrently.
+ */
+const SPAWN_STAGGER_DELAY_MS = 2000;
+// =============================================================================
 // Agent Selection
 // =============================================================================
 /**
@@ -517,6 +527,15 @@ export async function spawnForColumn(projectId, columnName, storage, executionSt
                     roundRobinState.lastIndex = -1;
                 }
             }
+            // Staggered spawn delay to prevent Docker kernel panics (TKT-801)
+            // When spawning multiple containers, add delay between spawns to avoid
+            // mount storms that cause spinlock contention in Docker's grpcfuse layer
+            const remainingTickets = ticketsToProcess.length - (ticketsToProcess.indexOf(ticket) + 1);
+            if (remainingTickets > 0 && availableAgents.length > 0) {
+                log(`Waiting ${SPAWN_STAGGER_DELAY_MS / 1000}s before next spawn (${remainingTickets} remaining)...`);
+                // eslint-disable-next-line no-await-in-loop -- Intentional staggered delay for Docker stability
+                await new Promise(resolve => setTimeout(resolve, SPAWN_STAGGER_DELAY_MS));
+            }
         }
         else {
             result.failed.push(spawnResult);

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

@@ -0,0 +1,4 @@
+/**
+ * Flag resolution utilities for unified human/machine interactive modes
+ */
+export { FlagResolver, createFlagResolver, shouldOutputJson, isMachineOutput, type FlagResolverOptions, type PromptDefinition, type ResolverChoice, type ResolverContext, type ResolveResult, } from './resolver.js';

package/dist/lib/flags/index.js

@@ -0,0 +1,4 @@
+/**
+ * Flag resolution utilities for unified human/machine interactive modes
+ */
+export { FlagResolver, createFlagResolver, shouldOutputJson, isMachineOutput, } from './resolver.js';

package/dist/lib/flags/resolver.d.ts

@@ -0,0 +1,224 @@
+/**
+ * FlagResolver - Unified flag resolution for human and machine interactive modes
+ *
+ * This abstraction unifies the two interaction patterns in the CLI:
+ * - Human interactive mode: Uses inquirer prompts, collects input, returns flags
+ * - Machine/JSON mode: Outputs prompt schema as JSON, exits for agent to process
+ *
+ * Both modes use the same underlying pattern: prompts PRODUCE flags.
+ * The execution logic only sees flags, not prompt results.
+ *
+ * @example
+ * ```typescript
+ * // Define prompts for missing flags
+ * const resolver = new FlagResolver({
+ *   commandName: 'ticket create',
+ *   baseCommand: 'prlt ticket create',
+ *   jsonMode: shouldOutputJson(flags),
+ *   flags,
+ * });
+ *
+ * // Add prompts - they execute in order, can depend on previously resolved flags
+ * resolver.addPrompt({
+ *   flagName: 'column',
+ *   type: 'list',
+ *   message: 'Select column:',
+ *   choices: async () => columns.map(c => ({ name: c, value: c })),
+ * });
+ *
+ * resolver.addPrompt({
+ *   flagName: 'title',
+ *   type: 'input',
+ *   message: 'Enter title:',
+ *   when: (ctx) => ctx.flags.column !== undefined, // Only after column is selected
+ * });
+ *
+ * // Resolve all missing flags
+ * const resolved = await resolver.resolve();
+ * // resolved.column and resolved.title are now guaranteed to have values
+ * ```
+ */
+/**
+ * Context available during prompt resolution
+ */
+export interface ResolverContext<TFlags = Record<string, unknown>> {
+    /** Currently resolved flags (includes original flags + newly resolved) */
+    flags: TFlags;
+    /** Command args */
+    args: Record<string, unknown>;
+    /** Command name for metadata */
+    commandName: string;
+    /** Base command for building follow-up commands (e.g., "prlt ticket create") */
+    baseCommand: string;
+    /** Project ID if available */
+    projectId?: string;
+    /** Any additional custom context */
+    [key: string]: unknown;
+}
+/**
+ * Choice item for list/checkbox prompts
+ */
+export interface ResolverChoice<T = string> {
+    /** Display text */
+    name: string;
+    /** Value returned when selected */
+    value: T;
+    /** Whether this choice is disabled */
+    disabled?: boolean | string;
+    /** Full CLI command for this choice (for JSON mode) - if not provided, auto-generated */
+    command?: string;
+}
+/**
+ * Definition for a single prompt that resolves a flag
+ */
+export interface PromptDefinition<TValue = unknown, TFlags = Record<string, unknown>> {
+    /** The flag name this prompt resolves (e.g., 'column', 'title') */
+    flagName: string;
+    /** Prompt type */
+    type: 'list' | 'checkbox' | 'input' | 'confirm' | 'editor';
+    /** User-facing prompt message */
+    message: string | ((ctx: ResolverContext<TFlags>) => string);
+    /**
+     * Get choices for list/checkbox prompts.
+     * Can be async to fetch dynamic data.
+     */
+    choices?: (ctx: ResolverContext<TFlags>) => Promise<ResolverChoice<TValue>[]> | ResolverChoice<TValue>[];
+    /**
+     * Default value for the prompt.
+     * Can be a function to compute based on context.
+     */
+    default?: TValue | ((ctx: ResolverContext<TFlags>) => TValue | undefined);
+    /**
+     * Validation function for input prompts.
+     * Return true if valid, or error message string if invalid.
+     */
+    validate?: (value: TValue, ctx: ResolverContext<TFlags>) => boolean | string;
+    /**
+     * Conditional function - prompt is skipped if this returns false.
+     * Use for prompts that depend on other flags.
+     */
+    when?: (ctx: ResolverContext<TFlags>) => boolean;
+    /**
+     * Transform the flag value before storing.
+     * Useful for parsing/formatting.
+     */
+    transform?: (value: TValue, ctx: ResolverContext<TFlags>) => unknown;
+    /**
+     * For JSON mode: additional context to include in the prompt output.
+     * Useful for providing hints, examples, etc.
+     */
+    context?: Record<string, unknown> | ((ctx: ResolverContext<TFlags>) => Record<string, unknown>);
+    /**
+     * For JSON mode: generate the command string for a specific choice.
+     * If not provided, auto-generates based on flagName and value.
+     */
+    getCommand?: (value: TValue, ctx: ResolverContext<TFlags>) => string;
+    /**
+     * Skip auto-generating commands for choices (useful when choices already have custom commands)
+     */
+    skipAutoCommand?: boolean;
+}
+/**
+ * Options for creating a FlagResolver
+ */
+export interface FlagResolverOptions<TFlags extends Record<string, unknown>> {
+    /** Command name for metadata (e.g., "ticket create") */
+    commandName: string;
+    /** Base command for building commands (e.g., "prlt ticket create") */
+    baseCommand: string;
+    /** Whether JSON mode is active */
+    jsonMode: boolean;
+    /** Initial flags from CLI parsing */
+    flags: Partial<TFlags>;
+    /** Command args */
+    args?: Record<string, unknown>;
+    /** Additional custom context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Result of flag resolution
+ */
+export interface ResolveResult<TFlags> {
+    /** The fully resolved flags */
+    flags: TFlags;
+    /** Whether all required prompts were resolved (false if user cancelled) */
+    complete: boolean;
+}
+/**
+ * FlagResolver handles unified flag resolution for both human and machine modes.
+ *
+ * Usage pattern:
+ * 1. Create resolver with command info and current flags
+ * 2. Add prompt definitions for flags that may need resolution
+ * 3. Call resolve() to get complete flags
+ *
+ * In JSON mode, resolve() outputs the first unresolved prompt and exits.
+ * In interactive mode, resolve() prompts for each unresolved flag sequentially.
+ */
+export declare class FlagResolver<TFlags extends Record<string, unknown> = Record<string, unknown>> {
+    private prompts;
+    private options;
+    private resolvedFlags;
+    private resolverContext;
+    constructor(options: FlagResolverOptions<TFlags>);
+    /**
+     * Add a prompt definition for resolving a flag.
+     * Prompts are processed in the order they are added.
+     */
+    addPrompt<TValue = unknown>(prompt: PromptDefinition<TValue, TFlags>): this;
+    /**
+     * Add multiple prompt definitions at once.
+     */
+    addPrompts(prompts: PromptDefinition<unknown, TFlags>[]): this;
+    /**
+     * Update the context with additional data.
+     * Useful for adding computed values that prompts might need.
+     */
+    setContext(key: string, value: unknown): this;
+    /**
+     * Get current context value
+     */
+    getContext<T = unknown>(key: string): T | undefined;
+    /**
+     * Check if a flag has a value (not undefined)
+     */
+    hasFlag(flagName: keyof TFlags): boolean;
+    /**
+     * Get current flag value
+     */
+    getFlag<K extends keyof TFlags>(flagName: K): TFlags[K] | undefined;
+    /**
+     * Set a flag value directly (bypasses prompting)
+     */
+    setFlag<K extends keyof TFlags>(flagName: K, value: TFlags[K]): this;
+    /**
+     * Resolve all prompts and return complete flags.
+     *
+     * In JSON mode: outputs the first unresolved prompt as JSON and exits (never returns).
+     * In interactive mode: prompts for each unresolved flag and returns all flags.
+     *
+     * @returns The fully resolved flags
+     */
+    resolve(): Promise<TFlags>;
+    /**
+     * Output prompt as JSON for machine mode
+     */
+    private outputJsonPrompt;
+    /**
+     * Prompt for value in interactive mode
+     */
+    private promptInteractive;
+    /**
+     * Build a command string for a flag value
+     */
+    private buildCommand;
+}
+/**
+ * Convenience function to create a FlagResolver from command context
+ */
+export declare function createFlagResolver<TFlags extends Record<string, unknown>>(options: FlagResolverOptions<TFlags>): FlagResolver<TFlags>;
+/**
+ * Helper to check if we should use JSON mode
+ * Re-exported from prompt-json for convenience
+ */
+export { shouldOutputJson, isMachineOutput } from '../prompt-json.js';