git-coco 0.34.0 → 0.35.0

package/dist/index.js

@@ -36,6 +36,9 @@ require('@langchain/core/utils/env');
 require('@langchain/core/utils/async_caller');
 var tiktoken = require('tiktoken');
 var child_process = require('child_process');
+var fs$1 = require('node:fs');
+var os$1 = require('node:os');
+var path$1 = require('node:path');
 var readline = require('readline');
 var util$1 = require('util');
 var url = require('url');
@@ -61,6 +64,9 @@ var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
 var ini__namespace = /*#__PURE__*/_interopNamespaceDefault(ini);
 var os__namespace = /*#__PURE__*/_interopNamespaceDefault(os);
 var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
+var fs__namespace$1 = /*#__PURE__*/_interopNamespaceDefault(fs$1);
+var os__namespace$1 = /*#__PURE__*/_interopNamespaceDefault(os$1);
+var path__namespace$1 = /*#__PURE__*/_interopNamespaceDefault(path$1);
 var readline__namespace = /*#__PURE__*/_interopNamespaceDefault(readline);
 
 // This file is auto-generated - DO NOT EDIT
@@ -68,7 +74,7 @@ var readline__namespace = /*#__PURE__*/_interopNamespaceDefault(readline);
 /**
  * Current build version from package.json
  */
-const BUILD_VERSION = "0.34.0";
+const BUILD_VERSION = "0.35.0";
 
 const isInteractive = (config) => {
     return config?.mode === 'interactive' || !!config?.interactive;
@@ -549,14 +555,9 @@ const CONFIG_KEYS = Object.keys({
     prompt: '',
 });
 
-/**
- * Load environment variables
- *
- * @param {Config} config
- * @returns {Config} Updated config
- **/
-function loadEnvConfig(config) {
+function loadEnvConfig(config, opts) {
     const envConfig = {};
+    let foundAny = false;
     const envKeys = [
         ...CONFIG_KEYS,
         'COCO_SERVICE_PROVIDER',
@@ -591,15 +592,20 @@ function loadEnvConfig(config) {
             // @ts-ignore
             envConfig.service = envConfig.service || {};
             handleServiceEnvVar(envConfig.service, key, envValue);
+            foundAny = true;
         }
         else {
             if (key === 'service' || !envValue) {
                 return;
             }
             envConfig[key] = envValue;
+            foundAny = true;
         }
     });
-    return { ...config, ...removeUndefined(envConfig) };
+    const merged = { ...config, ...removeUndefined(envConfig) };
+    {
+        return { config: merged, active: foundAny };
+    }
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function handleServiceEnvVar(service, key, value) {
@@ -726,19 +732,15 @@ const appendToEnvFile = async (filePath, config) => {
     });
 };
 
-/**
- * Load git profile config (from ~/.gitconfig)
- *
- * @param {Config} config
- * @returns {Config} Updated config
- **/
-function loadGitConfig(config) {
+function loadGitConfig(config, opts) {
     const gitConfigPath = path__namespace.join(os__namespace.homedir(), '.gitconfig');
+    let foundPath;
     if (fs__namespace.existsSync(gitConfigPath)) {
         const gitConfigRaw = fs__namespace.readFileSync(gitConfigPath, 'utf-8');
         const gitConfigParsed = ini__namespace.parse(gitConfigRaw);
         let service = config.service;
         if (gitConfigParsed.coco) {
+            foundPath = gitConfigPath;
             service = {
                 provider: gitConfigParsed.coco?.serviceProvider,
                 model: gitConfigParsed.coco?.serviceModel,
@@ -792,7 +794,10 @@ function loadGitConfig(config) {
             includeBranchName: gitConfigParsed.coco?.includeBranchName || config.includeBranchName,
         };
     }
-    return removeUndefined(config);
+    const cleaned = removeUndefined(config);
+    {
+        return { config: cleaned, path: foundPath };
+    }
 }
 /**
  * Appends the provided configuration to a git config file.
@@ -1032,6 +1037,10 @@ const schema$1 = {
                         "theme": {
                             "$ref": "#/definitions/LogInkThemeConfig",
                             "description": "Theme settings for `coco log -i`."
+                        },
+                        "idleTips": {
+                            "type": "boolean",
+                            "description": "Rotate short usage tips through the status line when the TUI has been idle for >10s. Off by default so power users aren't distracted."
                         }
                     },
                     "additionalProperties": false,
@@ -1865,24 +1874,29 @@ const ajv = new Ajv({
 });
 
 const validate = ajv.compile(schema$1);
-/**
- * Load project config
- *
- * @param {Config} config
- * @returns {Config} Updated config
- **/
-function loadProjectJsonConfig(config) {
-    if (fs__namespace.existsSync('.coco.config.json')) {
+function loadProjectJsonConfig(config, opts) {
+    // Prefer .coco.json, fall back to .coco.config.json
+    const candidates = ['.coco.json', '.coco.config.json'];
+    let resolvedPath;
+    for (const candidate of candidates) {
+        if (fs__namespace.existsSync(candidate)) {
+            resolvedPath = candidate;
+            break;
+        }
+    }
+    if (resolvedPath) {
         // Removing $schema from the project config to avoid validation errors.
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        const { $schema, ...projectConfig } = JSON.parse(fs__namespace.readFileSync('.coco.config.json', 'utf-8'));
+        const { $schema, ...projectConfig } = JSON.parse(fs__namespace.readFileSync(resolvedPath, 'utf-8'));
         config = { ...config, ...projectConfig };
         const isProjectConfigValid = validate(config);
         if (!isProjectConfigValid) {
             throw new Error('Invalid project config', { cause: ajv.errorsText(validate.errors) });
         }
     }
-    return config;
+    {
+        return { config: config, path: resolvedPath };
+    }
 }
 const appendToProjectJsonConfig = (filePath, config) => {
     if (!fs__namespace.existsSync(filePath)) {
@@ -1894,16 +1908,12 @@ const appendToProjectJsonConfig = (filePath, config) => {
     }, null, 2));
 };
 
-/**
- * Load XDG config
- *
- * @param {Config} config
- * @returns {Config} Updated config
- */
-function loadXDGConfig(config) {
+function loadXDGConfig(config, opts) {
     const xdgConfigHome = process.env.XDG_CONFIG_HOME || path__namespace.join(os__namespace.homedir(), '.config');
     const xdgConfigPath = path__namespace.join(xdgConfigHome, 'coco', 'config.json');
+    let foundPath;
     if (fs__namespace.existsSync(xdgConfigPath)) {
+        foundPath = xdgConfigPath;
         const xdgConfig = JSON.parse(fs__namespace.readFileSync(xdgConfigPath, 'utf-8'));
         const service = parseServiceConfig(xdgConfig.service || config.service);
         config = {
@@ -1912,7 +1922,9 @@ function loadXDGConfig(config) {
             service: service
         };
     }
-    return config;
+    {
+        return { config: config, path: foundPath };
+    }
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function parseServiceConfig(service) {
@@ -1956,6 +1968,17 @@ function parseServiceConfig(service) {
     }
 }
 
+/**
+ * Tracked config sources populated during the last loadConfig call.
+ * Useful for diagnostics (e.g. `coco doctor`).
+ */
+let _lastConfigSources = [];
+/**
+ * Returns the config sources detected during the most recent loadConfig call.
+ */
+function getConfigSources() {
+    return _lastConfigSources;
+}
 /**
  * Load application config
  *
@@ -1974,14 +1997,28 @@ function parseServiceConfig(service) {
  * @returns {Config} application config
  **/
 function loadConfig(argv = {}) {
+    const sources = [{ source: 'default' }];
     // Default config
     let config = DEFAULT_CONFIG;
     config = loadGitignore(config);
     config = loadIgnore(config);
-    config = loadXDGConfig(config);
-    config = loadGitConfig(config);
-    config = loadProjectJsonConfig(config);
-    config = loadEnvConfig(config);
+    const { config: xdgConfig, path: xdgPath } = loadXDGConfig(config);
+    config = xdgConfig;
+    if (xdgPath)
+        sources.push({ source: 'xdg', path: xdgPath });
+    const { config: gitConfig, path: gitPath } = loadGitConfig(config);
+    config = gitConfig;
+    if (gitPath)
+        sources.push({ source: 'git', path: gitPath });
+    const { config: projectConfig, path: projectPath } = loadProjectJsonConfig(config);
+    config = projectConfig;
+    if (projectPath)
+        sources.push({ source: 'project', path: projectPath });
+    const { config: envConfig, active: envActive } = loadEnvConfig(config);
+    config = envConfig;
+    if (envActive)
+        sources.push({ source: 'env' });
+    _lastConfigSources = sources;
     return { ...config, ...argv };
 }
 
@@ -5931,11 +5968,11 @@ const ChangelogResponseSchema = objectType({
     title: stringType(),
     content: stringType(),
 });
-const command$6 = 'changelog';
+const command$7 = 'changelog';
 /**
  * Command line options via yargs
  */
-const options$6 = {
+const options$7 = {
     range: {
         type: 'string',
         alias: 'r',
@@ -5982,8 +6019,8 @@ const options$6 = {
         description: 'Toggle interactive mode',
     },
 };
-const builder$6 = (yargs) => {
-    return yargs.options(options$6).usage(getCommandUsageHeader(command$6));
+const builder$7 = (yargs) => {
+    return yargs.options(options$7).usage(getCommandUsageHeader(command$7));
 };
 
 /**
@@ -10850,7 +10887,7 @@ async function processInWaves(items, processor, maxConcurrent = 6) {
     }
     return results;
 }
-const handler$6 = async (argv, logger) => {
+const handler$7 = async (argv, logger) => {
     const config = loadConfig(argv);
     const git = getRepo();
     const key = getApiKeyForModel(config);
@@ -11075,11 +11112,11 @@ const handler$6 = async (argv, logger) => {
 };
 
 var changelog = {
-    command: command$6,
+    command: command$7,
     desc: 'Generate a changelog from current or target branch, provided commit range, or since the last tag.',
-    builder: builder$6,
-    handler: commandExecutor(handler$6),
-    options: options$6,
+    builder: builder$7,
+    handler: commandExecutor(handler$7),
+    options: options$7,
 };
 
 const conventionalTypeRegex = /^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?!?:/;
@@ -11096,11 +11133,11 @@ const ConventionalCommitMessageResponseSchema = objectType({
     body: stringType().describe("Body of the commit message")
     // .max(280, "Body must be 280 characters or less"),
 }).describe("Object with Conventional Commit message 'title' and 'body' adhering to Conventional Commits specification");
-const command$5 = 'commit';
+const command$6 = 'commit';
 /**
  * Command line options via yargs
  */
-const options$5 = {
+const options$6 = {
     i: {
         alias: 'interactive',
         description: 'Toggle interactive mode',
@@ -11172,8 +11209,8 @@ const options$5 = {
         default: false,
     },
 };
-const builder$5 = (yargs) => {
-    return yargs.options(options$5).usage(getCommandUsageHeader(command$5));
+const builder$6 = (yargs) => {
+    return yargs.options(options$6).usage(getCommandUsageHeader(command$6));
 };
 
 /**
@@ -12008,7 +12045,7 @@ async function handleCommitSplit({ argv, config, git, logger, tokenizer, llm, })
     return formatCommitSplitPlan(plan);
 }
 
-const handler$5 = async (argv, logger) => {
+const handler$6 = async (argv, logger) => {
     const git = getRepo();
     const config = loadConfig(argv);
     const key = getApiKeyForModel(config);
@@ -12049,9 +12086,14 @@ const handler$5 = async (argv, logger) => {
             tokenizer,
             llm,
         });
+        const splitMode = INTERACTIVE ? 'interactive' : (config.mode || 'stdout');
         await handleResult({
             result: splitResult,
-            mode: config.mode || 'stdout',
+            mode: splitMode,
+            interactiveModeCallback: async (result) => {
+                logger.log(result);
+                logSuccess();
+            },
         });
         logLlmTelemetrySummary(logger, 'commit');
         return;
@@ -12468,11 +12510,407 @@ IMPORTANT RULES:
 };
 
 var commit = {
-    command: command$5,
+    command: command$6,
     desc: 'Summarize the staged changes in a commit message.',
+    builder: builder$6,
+    handler: commandExecutor(handler$6),
+    options: options$6,
+};
+
+const command$5 = 'doctor';
+const options$5 = {
+    fix: {
+        description: 'Attempt to auto-fix detected issues and write the updated config',
+        type: 'boolean',
+        default: false,
+    },
+};
+const builder$5 = (yargs) => {
+    return yargs.options(options$5).usage(getCommandUsageHeader(command$5));
+};
+
+/**
+ * Deprecated or renamed model identifiers that should be updated.
+ */
+const MODEL_UPGRADES = {
+    'gpt-4-turbo-preview': 'gpt-4o',
+    'gpt-4-0125-preview': 'gpt-4o',
+    'gpt-4-1106-preview': 'gpt-4o',
+    'gpt-3.5-turbo-0125': 'gpt-4o-mini',
+    'gpt-3.5-turbo-1106': 'gpt-4o-mini',
+    'gpt-3.5-turbo-16k': 'gpt-4o-mini',
+    'claude-3-opus-20240229': 'claude-sonnet-4-0',
+    'claude-3-sonnet-20240229': 'claude-3-5-sonnet-latest',
+    'claude-3-haiku-20240307': 'claude-3-5-haiku-latest',
+};
+function runDiagnostics(config) {
+    const diagnostics = [];
+    checkServiceBlock(config, diagnostics);
+    checkAuthentication(config, diagnostics);
+    checkModelCurrency(config, diagnostics);
+    checkModeConfig(config, diagnostics);
+    checkDynamicRouting(config, diagnostics);
+    checkTokenLimits(config, diagnostics);
+    checkIgnoredFiles(config, diagnostics);
+    checkProjectConfigFile(diagnostics);
+    return diagnostics;
+}
+function checkServiceBlock(config, diagnostics) {
+    if (!config.service) {
+        diagnostics.push({
+            severity: 'error',
+            message: 'No service configuration found. Coco needs an AI provider to generate results.',
+            fix: 'Run `coco init` to set up a provider, or add a "service" block to .coco.config.json.',
+        });
+        return;
+    }
+    if (!config.service.provider) {
+        diagnostics.push({
+            severity: 'error',
+            message: 'No provider set in service config.',
+            fix: 'Set service.provider to "openai", "anthropic", or "ollama".',
+        });
+    }
+    if (!config.service.model) {
+        diagnostics.push({
+            severity: 'error',
+            message: 'No model set in service config.',
+            fix: 'Set service.model to a valid model name (e.g. "gpt-4o") or "dynamic" for task-based routing.',
+        });
+    }
+}
+function checkAuthentication(config, diagnostics) {
+    if (!config.service)
+        return;
+    const { provider, authentication } = config.service;
+    if (provider === 'ollama') {
+        if (authentication && authentication.type !== 'None') {
+            diagnostics.push({
+                severity: 'warn',
+                message: 'Ollama does not require authentication. Set authentication.type to "None".',
+                fix: 'Change service.authentication to { "type": "None" }.',
+                autoFix: (raw) => {
+                    const svc = raw.service;
+                    if (svc) {
+                        svc.authentication = { type: 'None' };
+                    }
+                },
+            });
+        }
+        const ollamaService = config.service;
+        if (!ollamaService.endpoint) {
+            diagnostics.push({
+                severity: 'warn',
+                message: 'No Ollama endpoint configured. Defaulting to http://localhost:11434.',
+                fix: 'Add service.endpoint: "http://localhost:11434" to your config.',
+                autoFix: (raw) => {
+                    const svc = raw.service;
+                    if (svc) {
+                        svc.endpoint = 'http://localhost:11434';
+                    }
+                },
+            });
+        }
+        return;
+    }
+    if (!authentication || authentication.type === 'None') {
+        diagnostics.push({
+            severity: 'error',
+            message: `Provider "${provider}" requires authentication but none is configured.`,
+            fix: `Set service.authentication to { "type": "APIKey", "credentials": { "apiKey": "..." } } or use the OPENAI_API_KEY / ANTHROPIC_API_KEY environment variable.`,
+        });
+        return;
+    }
+    if (authentication.type === 'APIKey') {
+        const key = authentication.credentials?.apiKey;
+        if (!key || key === '•••••••••••••••' || key.trim() === '') {
+            diagnostics.push({
+                severity: 'warn',
+                message: 'API key appears to be a placeholder or empty. Coco may fall back to environment variables.',
+                fix: `Set the API key in your config or via environment variable (OPENAI_API_KEY or ANTHROPIC_API_KEY).`,
+            });
+        }
+    }
+}
+function checkModelCurrency(config, diagnostics) {
+    if (!config.service?.model || config.service.model === 'dynamic')
+        return;
+    const model = String(config.service.model);
+    const upgrade = MODEL_UPGRADES[model];
+    if (upgrade) {
+        diagnostics.push({
+            severity: 'warn',
+            message: `Model "${model}" has a newer replacement available: "${upgrade}".`,
+            fix: `Update service.model to "${upgrade}" for better performance and pricing.`,
+            autoFix: (raw) => {
+                const svc = raw.service;
+                if (svc) {
+                    svc.model = upgrade;
+                }
+            },
+        });
+    }
+}
+function checkModeConfig(config, diagnostics) {
+    if (!config.mode || config.mode === 'stdout') {
+        diagnostics.push({
+            severity: 'info',
+            message: 'Output mode is "stdout". Interactive features like commit split require -i or mode: "interactive".',
+            fix: 'Set "mode": "interactive" in your config, or pass -i when using interactive commands.',
+        });
+    }
+}
+function checkDynamicRouting(config, diagnostics) {
+    if (!config.service)
+        return;
+    if (config.service.model === 'dynamic') {
+        if (!config.service.dynamicModelPreference) {
+            diagnostics.push({
+                severity: 'info',
+                message: 'Dynamic model routing is enabled but no preference is set. Defaulting to "balanced".',
+                fix: 'Optionally set service.dynamicModelPreference to "cost", "balanced", or "quality".',
+            });
+        }
+        if (config.service.dynamicModels) {
+            const validTasks = ['summarize', 'commit', 'changelog', 'review', 'recap', 'repair', 'largeDiff'];
+            for (const task of Object.keys(config.service.dynamicModels)) {
+                if (!validTasks.includes(task)) {
+                    diagnostics.push({
+                        severity: 'warn',
+                        message: `Unknown dynamic model task "${task}". Valid tasks: ${validTasks.join(', ')}.`,
+                        fix: `Remove or rename the "${task}" key in service.dynamicModels.`,
+                    });
+                }
+            }
+        }
+        diagnostics.push({
+            severity: 'info',
+            message: 'Dynamic model routing is active. Coco will select models per task based on your preference.',
+        });
+    }
+    else {
+        diagnostics.push({
+            severity: 'info',
+            message: `Using fixed model "${config.service.model}" for all tasks. Set service.model to "dynamic" to enable per-task model selection.`,
+        });
+    }
+}
+function checkTokenLimits(config, diagnostics) {
+    if (!config.service)
+        return;
+    const tokenLimit = config.service.tokenLimit || 2048;
+    if (tokenLimit < 512) {
+        diagnostics.push({
+            severity: 'warn',
+            message: `Token limit (${tokenLimit}) is very low. This may cause truncated or poor-quality results.`,
+            fix: 'Increase service.tokenLimit to at least 1024, ideally 2048 or higher.',
+            autoFix: (raw) => {
+                const svc = raw.service;
+                if (svc) {
+                    svc.tokenLimit = 2048;
+                }
+            },
+        });
+    }
+    if (config.service.maxConcurrent && config.service.provider === 'ollama' && config.service.maxConcurrent > 1) {
+        diagnostics.push({
+            severity: 'warn',
+            message: `maxConcurrent is ${config.service.maxConcurrent} but Ollama typically handles one request at a time.`,
+            fix: 'Set service.maxConcurrent to 1 for Ollama.',
+            autoFix: (raw) => {
+                const svc = raw.service;
+                if (svc) {
+                    svc.maxConcurrent = 1;
+                }
+            },
+        });
+    }
+}
+function checkIgnoredFiles(config, diagnostics) {
+    if (!config.ignoredFiles || config.ignoredFiles.length === 0) {
+        diagnostics.push({
+            severity: 'info',
+            message: 'No custom ignored files configured. Coco uses defaults (package-lock.json, .gitignore contents, etc.).',
+        });
+    }
+}
+function checkProjectConfigFile(diagnostics) {
+    const hasNewName = fs__namespace.existsSync('.coco.json');
+    const hasLegacyName = fs__namespace.existsSync('.coco.config.json');
+    if (!hasNewName && !hasLegacyName) {
+        diagnostics.push({
+            severity: 'info',
+            message: 'No project config file found in the current directory. Using git config, env vars, or defaults.',
+            fix: 'Run `coco init --scope project` to create a project config.',
+        });
+        return;
+    }
+    if (hasLegacyName && !hasNewName) {
+        diagnostics.push({
+            severity: 'info',
+            message: 'Using legacy config filename .coco.config.json. Consider renaming to .coco.json.',
+            fix: 'Rename .coco.config.json to .coco.json. Both filenames are supported, but .coco.json is preferred.',
+        });
+    }
+    const configPath = hasNewName ? '.coco.json' : '.coco.config.json';
+    try {
+        const raw = JSON.parse(fs__namespace.readFileSync(configPath, 'utf-8'));
+        if (!raw.$schema) {
+            diagnostics.push({
+                severity: 'info',
+                message: `Project config (${configPath}) is missing the $schema field. Adding it enables editor autocompletion.`,
+                fix: `Add "$schema": "https://coco.griffen.codes/schema.json" to ${configPath}.`,
+                autoFix: (rawConfig) => {
+                    rawConfig.$schema = 'https://coco.griffen.codes/schema.json';
+                },
+            });
+        }
+    }
+    catch {
+        diagnostics.push({
+            severity: 'error',
+            message: `${configPath} contains invalid JSON.`,
+            fix: `Fix the JSON syntax in ${configPath} or regenerate it with \`coco init --scope project\`.`,
+        });
+    }
+}
+
+const SEVERITY_ICON = {
+    error: chalk.red('✖'),
+    warn: chalk.yellow('⚠'),
+    info: chalk.blue('ℹ'),
+};
+const SEVERITY_LABEL = {
+    error: chalk.red('error'),
+    warn: chalk.yellow('warn'),
+    info: chalk.blue('info'),
+};
+const SOURCE_LABELS = {
+    default: 'Built-in defaults',
+    xdg: 'XDG config',
+    git: 'Git config (~/.gitconfig)',
+    project: 'Project config',
+    env: 'Environment variables',
+};
+function formatSourceInfo(sources) {
+    const lines = [];
+    for (const source of sources) {
+        const label = SOURCE_LABELS[source.source] || source.source;
+        if (source.path) {
+            lines.push(`  ${chalk.green('✓')} ${label} ${chalk.dim(`(${source.path})`)}`);
+        }
+        else {
+            lines.push(`  ${chalk.green('✓')} ${label}`);
+        }
+    }
+    return lines;
+}
+const handler$5 = async (argv, logger) => {
+    const config = loadConfig(argv);
+    const sources = getConfigSources();
+    logger.log(LOGO);
+    logger.log('');
+    logger.log(chalk.bold('coco doctor') + ' — checking your configuration\n');
+    // Show active config sources
+    logger.log(chalk.bold('Config sources') + chalk.dim(' (lowest → highest precedence):\n'));
+    const sourceLines = formatSourceInfo(sources);
+    for (const line of sourceLines) {
+        logger.log(line);
+    }
+    // Show inactive sources
+    const activeSources = new Set(sources.map((s) => s.source));
+    const allSources = ['xdg', 'git', 'project', 'env'];
+    const inactive = allSources.filter((s) => !activeSources.has(s));
+    if (inactive.length > 0) {
+        logger.log('');
+        for (const source of inactive) {
+            const label = SOURCE_LABELS[source] || source;
+            logger.log(`  ${chalk.dim('–')} ${chalk.dim(label)} ${chalk.dim('(not found)')}`);
+        }
+    }
+    logger.log('');
+    // Run diagnostics
+    const diagnostics = runDiagnostics(config);
+    if (diagnostics.length === 0) {
+        logger.log(chalk.green('✓ No issues found. Your configuration looks good!'));
+        return;
+    }
+    const errors = diagnostics.filter((d) => d.severity === 'error');
+    const warnings = diagnostics.filter((d) => d.severity === 'warn');
+    const infos = diagnostics.filter((d) => d.severity === 'info');
+    logger.log(chalk.bold('Diagnostics:\n'));
+    for (const diagnostic of diagnostics) {
+        const icon = SEVERITY_ICON[diagnostic.severity];
+        const label = SEVERITY_LABEL[diagnostic.severity];
+        logger.log(`${icon} ${label}: ${diagnostic.message}`);
+        if (diagnostic.fix) {
+            logger.log(chalk.dim(`  → ${diagnostic.fix}`));
+        }
+        logger.log('');
+    }
+    // Summary
+    const parts = [];
+    if (errors.length > 0)
+        parts.push(chalk.red(`${errors.length} error(s)`));
+    if (warnings.length > 0)
+        parts.push(chalk.yellow(`${warnings.length} warning(s)`));
+    if (infos.length > 0)
+        parts.push(chalk.blue(`${infos.length} info(s)`));
+    logger.log(`Found ${parts.join(', ')}.\n`);
+    // Auto-fix
+    if (argv.fix) {
+        const fixable = diagnostics.filter((d) => d.autoFix);
+        if (fixable.length === 0) {
+            logger.log(chalk.dim('No auto-fixable issues found.'));
+            return;
+        }
+        // Find the project config file to write to
+        const projectSource = sources.find((s) => s.source === 'project');
+        const configPath = projectSource?.path;
+        if (!configPath) {
+            logger.log(chalk.yellow('No project config file found. Run `coco init --scope project` first, then re-run `coco doctor --fix`.'));
+            logger.log(chalk.dim('  Auto-fix writes to the project config file (.coco.json or .coco.config.json).'));
+            // If config is coming from git or env, explain
+            const gitSource = sources.find((s) => s.source === 'git');
+            const envSource = sources.find((s) => s.source === 'env');
+            if (gitSource) {
+                logger.log(chalk.dim(`  Your config is loaded from ${gitSource.path} — edit that file manually, or create a project config.`));
+            }
+            if (envSource) {
+                logger.log(chalk.dim('  Some config comes from environment variables — update those in your shell profile.'));
+            }
+            return;
+        }
+        try {
+            const raw = JSON.parse(fs__namespace.readFileSync(configPath, 'utf-8'));
+            for (const diagnostic of fixable) {
+                diagnostic.autoFix(raw);
+                logger.log(chalk.green(`  ✓ Fixed: ${diagnostic.message}`));
+            }
+            // Ensure $schema is present
+            if (!raw.$schema) {
+                raw.$schema = SCHEMA_PUBLIC_URL;
+            }
+            fs__namespace.writeFileSync(configPath, JSON.stringify(raw, null, 2) + '\n');
+            logger.log(chalk.green(`\nWrote ${fixable.length} fix(es) to ${configPath}`));
+        }
+        catch (e) {
+            logger.log(chalk.red(`Failed to apply fixes: ${e.message}`));
+        }
+    }
+    else {
+        const fixable = diagnostics.filter((d) => d.autoFix);
+        if (fixable.length > 0) {
+            logger.log(chalk.dim(`${fixable.length} issue(s) can be auto-fixed. Run \`coco doctor --fix\` to apply.`));
+        }
+    }
+};
+
+var doctor = {
+    command: command$5,
+    desc: 'Check your coco configuration for common issues and suggest fixes',
     builder: builder$5,
     handler: commandExecutor(handler$5),
-    options: options$5,
 };
 
 const command$4 = 'init';
@@ -12828,7 +13266,11 @@ const questions = {
         message: 'where would you like to store the project config?',
         choices: [
             {
-                name: '.coco.config.json',
+                name: '.coco.json (recommended)',
+                value: '.coco.json',
+            },
+            {
+                name: '.coco.config.json (legacy)',
                 value: '.coco.config.json',
             },
             {
@@ -13489,10 +13931,11 @@ function applyCommitComposeAction(state, action) {
                 details: action.details,
             };
         case 'reset':
-            return createCommitComposeState({
-                message: state.message,
-                details: state.details,
-            });
+            // Drop message/details too — the post-commit "Created commit ..."
+            // notification is already on the runtime status line (footer); a
+            // duplicate copy lingering in the Compose panel reads as stale
+            // state once the user starts a fresh draft.
+            return createCommitComposeState();
         default:
             return state;
     }
@@ -13559,56 +14002,291 @@ async function createManualCommit({ git, summary, body, noVerify = false, }) {
     }
 }
 
-function createCommitWorkflowArgv(action) {
-    const split = action === 'split-plan' || action === 'split-apply';
-    const apply = action === 'split-apply';
-    const plan = action === 'split-plan';
-    return {
-        $0: 'coco',
-        _: split ? ['commit', 'split'] : ['commit'],
-        interactive: false,
-        verbose: false,
-        version: false,
-        help: false,
-        mode: 'stdout',
-        openInEditor: false,
-        ignoredFiles: [],
-        ignoredExtensions: [],
-        withPreviousCommits: 0,
-        conventional: false,
-        includeBranchName: true,
-        noVerify: false,
-        noDiff: false,
-        split,
-        plan,
-        apply,
-    };
-}
-function formatCommitWorkflowMessage(action, output) {
-    const normalized = output.trim();
-    if (normalized) {
-        return normalized.split('\n')[0];
-    }
-    if (action === 'split-plan') {
-        return 'Generated commit split plan.';
-    }
-    if (action === 'split-apply') {
-        return 'Applied commit split plan.';
-    }
-    return 'Generated commit message.';
-}
-function compactOutputLines$3(output) {
-    return output
-        .split('\n')
-        .map((line) => line.trim())
-        .filter(Boolean);
-}
-function formatCommitFailure(error) {
-    if (error instanceof PreCommitHookError) {
-        const details = compactOutputLines$3(error.hookOutput);
+const FORMAT_INSTRUCTIONS_TEMPLATE = (schemaDescription) => (`CRITICAL: You must return ONLY a valid JSON object with no additional text, explanations, or markdown formatting.
+
+REQUIRED JSON FORMAT:
+${schemaDescription}
+
+EXAMPLE (follow this EXACT format - compact JSON on a single line or minimal whitespace):
+{"title": "feat(auth): add user authentication system", "body": "Implement JWT-based authentication with login and logout functionality. Includes password hashing and session management."}
+
+IMPORTANT RULES:
+- Return ONLY the JSON object - NO markdown code blocks, NO backticks, NO extra text
+- ALL string values MUST be enclosed in double quotes
+- Use compact JSON format (minimal whitespace) for best compatibility
+- NO trailing commas
+- NO comments or additional text outside the JSON
+- The "title" and "body" values must be properly quoted strings`);
+/**
+ * Generate a commit message draft with no UI side effects.
+ *
+ * Mirrors the LLM-chain logic from `commit/handler.ts`'s agent callback but
+ * skips the review loop, ora spinners, Inquirer prompts, and stdout writes
+ * that would corrupt the surrounding Ink TUI alt screen. Validation failures
+ * are surfaced as `validationErrors`/`warnings` rather than driving an
+ * interactive retry flow — the TUI can re-invoke or let the user edit.
+ */
+async function generateCommitDraft({ git, argv, logger = new Logger({ silent: true }), }) {
+    const config = loadConfig(argv);
+    const key = getApiKeyForModel(config);
+    const { provider } = getModelAndProviderFromConfig(config);
+    const commitService = resolveDynamicService(config, 'commit');
+    const summaryService = resolveDynamicService(config, 'summarize');
+    const model = commitService.model;
+    if (config.service.authentication.type !== 'None' && !key) {
         return {
             ok: false,
-            message: `Commit blocked by hook: ${details[0] || 'hook failed'}`,
+            draft: '',
+            warnings: [],
+            validationErrors: ['No API key configured for the commit service.'],
+        };
+    }
+    const tokenizer = await getTokenCounter(provider === 'openai' ? model : 'gpt-4o');
+    const llm = getLlm(provider, model, { ...config, service: commitService });
+    const summaryLlm = getLlm(provider, summaryService.model, {
+        ...config,
+        service: summaryService,
+    });
+    const useConventional = Boolean(config.conventionalCommits || argv.conventional);
+    const changes = await (async () => {
+        if (config.noDiff) {
+            const status = await git.status();
+            return status.files.map((file) => ({
+                filePath: file.path,
+                status: (file.index === 'A' || file.index === '?'
+                    ? 'added'
+                    : 'modified'),
+                summary: file.path,
+            }));
+        }
+        const result = await getChanges({
+            git,
+            options: {
+                ignoredFiles: config.ignoredFiles || undefined,
+                ignoredExtensions: config.ignoredExtensions || undefined,
+            },
+        });
+        return result.staged;
+    })();
+    if (!changes || changes.length === 0) {
+        return {
+            ok: false,
+            draft: '',
+            warnings: ['No staged changes detected.'],
+            validationErrors: [],
+        };
+    }
+    const summary = config.noDiff
+        ? `Staged files:\n${changes.map((c) => `${c.status}: ${c.filePath}`).join('\n')}`
+        : await fileChangeParser({
+            changes,
+            commit: '--staged',
+            options: createFileChangeParserOptions({
+                command: 'commit',
+                tokenizer,
+                git,
+                llm: summaryLlm,
+                logger,
+                provider,
+                model: String(summaryService.model),
+                service: config.service,
+            }),
+        });
+    if (!summary || !summary.length) {
+        return {
+            ok: false,
+            draft: '',
+            warnings: ['Diff summary was empty after parsing staged changes.'],
+            validationErrors: [],
+        };
+    }
+    const schema = useConventional
+        ? ConventionalCommitMessageResponseSchema
+        : CommitMessageResponseSchema;
+    const promptTemplate = useConventional ? CONVENTIONAL_COMMIT_PROMPT : COMMIT_PROMPT;
+    const prompt = getPrompt({
+        template: config.prompt || promptTemplate.template,
+        variables: promptTemplate.inputVariables,
+        fallback: promptTemplate,
+    });
+    const formatInstructions = FORMAT_INSTRUCTIONS_TEMPLATE(schema.description || '');
+    const additionalContext = argv.additional ? `## Additional Context\n${argv.additional}` : '';
+    let commitHistory = '';
+    const previousCommitsCount = Number(argv.withPreviousCommits || 0);
+    if (previousCommitsCount > 0) {
+        const commitHistoryData = await getPreviousCommits({ git, count: previousCommitsCount });
+        if (commitHistoryData) {
+            commitHistory = `## Commit History\n${commitHistoryData}`;
+        }
+    }
+    const branchName = await getCurrentBranchName({ git });
+    const includeBranchName = argv.includeBranchName !== undefined
+        ? argv.includeBranchName
+        : config.includeBranchName !== false;
+    const branchNameContext = includeBranchName ? `Current git branch name: ${branchName}` : '';
+    const warnings = [];
+    const hasCommitLintConfig = await hasCommitlintConfig();
+    let commitlintRulesContext = '';
+    let validationEnabled = useConventional || hasCommitLintConfig;
+    if (validationEnabled) {
+        const { getCommitlintRulesContext, checkCommitlintAvailability } = await Promise.resolve().then(function () { return commitlintValidator; });
+        const availability = checkCommitlintAvailability();
+        if (!availability.available) {
+            warnings.push(`Skipping commitlint validation: missing packages (${availability.missingPackages.join(', ')}).`);
+            validationEnabled = false;
+        }
+        else {
+            commitlintRulesContext = await getCommitlintRulesContext();
+        }
+    }
+    const baseVariables = {
+        summary,
+        format_instructions: formatInstructions,
+        additional_context: additionalContext,
+        commit_history: commitHistory,
+        branch_name_context: branchNameContext,
+        commitlint_rules_context: commitlintRulesContext,
+    };
+    const maxParsingAttempts = config.service.provider === 'ollama' && 'maxParsingAttempts' in config.service
+        ? config.service.maxParsingAttempts || 3
+        : 3;
+    let lastValidationErrors = [];
+    let validationFeedback = '';
+    let lastDraft = '';
+    // Two attempts max — one initial generation plus one retry that incorporates
+    // commitlint feedback. Beyond that we surface warnings and let the TUI user
+    // edit the draft manually rather than driving an interactive prompt loop.
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        const variables = {
+            ...baseVariables,
+            additional_context: validationFeedback
+                ? `${baseVariables.additional_context}\n\n## Validation Errors from Previous Attempt\nPlease fix the following issues:\n${validationFeedback}`
+                : baseVariables.additional_context,
+        };
+        const budgetedPrompt = await enforcePromptBudget({
+            prompt,
+            variables,
+            tokenizer,
+            maxTokens: config.service.tokenLimit || 2048,
+        });
+        const commitMsg = await executeChainWithSchema(schema, llm, prompt, budgetedPrompt.variables, {
+            logger,
+            tokenizer,
+            metadata: {
+                task: useConventional ? 'commit-message-conventional' : 'commit-message',
+                command: 'commit-draft',
+                provider,
+                model: String(model),
+            },
+            retryOptions: {
+                maxAttempts: maxParsingAttempts,
+            },
+            fallbackParser: (text) => {
+                try {
+                    let cleanText = text.trim();
+                    const codeBlockMatch = cleanText.match(/```(?:json)?\s*(\{[\s\S]*?\})\s*```/);
+                    if (codeBlockMatch && codeBlockMatch[1]) {
+                        cleanText = codeBlockMatch[1].trim();
+                    }
+                    const parsed = JSON.parse(cleanText);
+                    if (parsed && typeof parsed === 'object' &&
+                        typeof parsed.title === 'string' &&
+                        typeof parsed.body === 'string' &&
+                        parsed.title.length > 0) {
+                        return parsed;
+                    }
+                }
+                catch {
+                    // fall through
+                }
+                return {
+                    title: text.split('\n')[0] || 'Auto-generated commit',
+                    body: text.split('\n').slice(1).join('\n') || 'Generated commit message',
+                };
+            },
+        });
+        const ticketId = extractTicketIdFromBranchName(branchName);
+        const fullMessage = formatCommitMessage(commitMsg, {
+            append: argv.append,
+            ticketId: ticketId || undefined,
+            appendTicket: argv.appendTicket,
+        });
+        lastDraft = fullMessage;
+        if (!validationEnabled) {
+            return { ok: true, draft: fullMessage, warnings, validationErrors: [] };
+        }
+        const { validateCommitMessage } = await Promise.resolve().then(function () { return commitlintValidator; });
+        const validationResult = await validateCommitMessage(fullMessage);
+        if (validationResult.missingDependencies && validationResult.missingDependencies.length > 0) {
+            warnings.push(`Skipping commitlint validation: missing packages (${validationResult.missingDependencies.join(', ')}).`);
+            return { ok: true, draft: fullMessage, warnings, validationErrors: [] };
+        }
+        if (validationResult.valid) {
+            return { ok: true, draft: fullMessage, warnings, validationErrors: [] };
+        }
+        lastValidationErrors = validationResult.errors;
+        validationFeedback = validationResult.errors.map((error) => `- ${error}`).join('\n');
+    }
+    // Both attempts failed validation — return the latest draft so the user can
+    // hand-edit in the compose surface, plus the validator output for context.
+    return {
+        ok: false,
+        draft: lastDraft,
+        warnings,
+        validationErrors: lastValidationErrors,
+    };
+}
+
+function createCommitWorkflowArgv(action) {
+    const split = action === 'split-plan' || action === 'split-apply';
+    const apply = action === 'split-apply';
+    const plan = action === 'split-plan';
+    return {
+        $0: 'coco',
+        _: split ? ['commit', 'split'] : ['commit'],
+        interactive: false,
+        verbose: false,
+        version: false,
+        help: false,
+        mode: 'stdout',
+        openInEditor: false,
+        ignoredFiles: [],
+        ignoredExtensions: [],
+        withPreviousCommits: 0,
+        conventional: false,
+        includeBranchName: true,
+        noVerify: false,
+        noDiff: false,
+        split,
+        plan,
+        apply,
+    };
+}
+function formatCommitWorkflowMessage(action, output) {
+    const normalized = output.trim();
+    if (normalized) {
+        return normalized.split('\n')[0];
+    }
+    if (action === 'split-plan') {
+        return 'Generated commit split plan.';
+    }
+    if (action === 'split-apply') {
+        return 'Applied commit split plan.';
+    }
+    return 'Generated commit message.';
+}
+function compactOutputLines$3(output) {
+    return output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+function formatCommitFailure(error) {
+    if (error instanceof PreCommitHookError) {
+        const details = compactOutputLines$3(error.hookOutput);
+        return {
+            ok: false,
+            message: `Commit blocked by hook: ${details[0] || 'hook failed'}`,
             details: details.slice(1, 6),
         };
     }
@@ -13633,7 +14311,7 @@ async function runCommitWorkflow({ action, git = getRepo(), noVerify = false, })
         return true;
     });
     try {
-        await handler$5(argv, logger);
+        await handler$6(argv, logger);
         const message = output.trim();
         if (action === 'commit' && message) {
             await createCommit(message, git, undefined, { noVerify: config.noVerify || false });
@@ -13658,41 +14336,45 @@ async function runCommitWorkflow({ action, git = getRepo(), noVerify = false, })
         process.stdout.write = originalWrite;
     }
 }
-async function runCommitDraftWorkflow() {
+async function runCommitDraftWorkflow(input = {}) {
+    const git = input.git || getRepo();
     const argv = createCommitWorkflowArgv('commit');
     const logger = new Logger({ silent: true });
-    const originalWrite = process.stdout.write.bind(process.stdout);
-    let output = '';
-    process.stdout.write = ((chunk, ...args) => {
-        output += typeof chunk === 'string' ? chunk : chunk.toString();
-        const callback = args.find((arg) => typeof arg === 'function');
-        callback?.();
-        return true;
-    });
     try {
-        await handler$5(argv, logger);
-        const draft = output.trim();
+        const result = await generateCommitDraft({ git, argv, logger });
+        const draft = result.draft.trim();
+        if (result.ok && draft) {
+            return {
+                ok: true,
+                message: formatCommitWorkflowMessage('commit', draft),
+                details: result.warnings,
+                draft,
+            };
+        }
+        const failureLines = [
+            ...(result.validationErrors || []),
+            ...(result.warnings || []),
+        ];
         return {
-            ok: Boolean(draft),
-            message: draft ? formatCommitWorkflowMessage('commit', draft) : 'AI draft was empty.',
+            ok: false,
+            message: failureLines[0] ||
+                (draft ? 'AI draft did not pass commitlint.' : 'AI draft was empty.'),
+            details: failureLines.slice(1, 6),
             draft,
         };
     }
     catch (error) {
         if (isCommandExitError(error)) {
-            const lines = compactOutputLines$3(output || error.message);
+            const lines = compactOutputLines$3(error.message);
             return {
                 ok: error.code === 0,
                 message: lines[0] || error.message,
                 details: lines.slice(1, 6),
-                draft: output.trim(),
+                draft: '',
             };
         }
         return formatCommitFailure(error);
     }
-    finally {
-        process.stdout.write = originalWrite;
-    }
 }
 
 const LOG_INK_CONTEXT_KEYS = [
@@ -14009,16 +14691,30 @@ const LOG_INK_KEY_BINDINGS = [
         id: 'previousSidebarTab',
         keys: ['['],
         label: 'previous tab',
-        description: 'Move to the previous repository sidebar tab.',
+        description: 'Move to the previous repository sidebar tab (outside diff view).',
         contexts: ['sidebar'],
     },
     {
         id: 'nextSidebarTab',
         keys: [']'],
         label: 'next tab',
-        description: 'Move to the next repository sidebar tab.',
+        description: 'Move to the next repository sidebar tab (outside diff view).',
         contexts: ['sidebar'],
     },
+    {
+        id: 'previousHunk',
+        keys: ['['],
+        label: 'previous hunk',
+        description: 'Jump to the previous diff hunk in the current diff view.',
+        contexts: ['commits'],
+    },
+    {
+        id: 'nextHunk',
+        keys: [']'],
+        label: 'next hunk',
+        description: 'Jump to the next diff hunk in the current diff view.',
+        contexts: ['commits'],
+    },
     {
         id: 'focusNext',
         keys: ['tab'],
@@ -14145,6 +14841,13 @@ const LOG_INK_KEY_BINDINGS = [
         description: 'Create a commit from staged changes with the current draft.',
         contexts: ['commits'],
     },
+    {
+        id: 'cycleSort',
+        keys: ['s'],
+        label: 'sort',
+        description: 'Cycle the sort mode in branches (name/recent/ahead) or tags (recent/name).',
+        contexts: ['commits'],
+    },
     {
         id: 'help',
         keys: ['?'],
@@ -14174,6 +14877,28 @@ const LOG_INK_KEY_BINDINGS = [
         contexts: ['normal', 'search'],
     },
 ];
+/**
+ * Surface the second-key continuations for a chord prefix (e.g. `g`)
+ * as a flat list, sourced from the canonical keymap so the help, footer
+ * hint, and which-key overlay all stay in sync. Continuations are sorted
+ * by key for stable, scannable output.
+ */
+function getLogInkChordContinuations(prefix) {
+    const continuations = [];
+    for (const binding of LOG_INK_KEY_BINDINGS) {
+        for (const keys of binding.keys) {
+            if (keys.length === 2 && keys.startsWith(prefix)) {
+                continuations.push({
+                    key: keys.charAt(1),
+                    label: binding.label,
+                    description: binding.description,
+                });
+                break;
+            }
+        }
+    }
+    return continuations.sort((a, b) => a.key.localeCompare(b.key));
+}
 /**
  * Bindings considered "global" — always available regardless of which view
  * or pane has focus. Surfaced as a separate group in the help overlay and
@@ -14218,9 +14943,23 @@ function formatLogInkBreadcrumb(viewStack) {
     if (viewStack.length === 1 && viewStack[0] === 'history') {
         return '';
     }
-    return viewStack.join(' › ');
+    // Trailing back-hint (P2.5) reminds the user how to walk back when
+    // they're nested deeper than the root view.
+    return `${viewStack.join(' › ')}   ← <`;
 }
 function getLogInkFooterHints(options) {
+    if (options.pendingKey) {
+        const continuations = getLogInkChordContinuations(options.pendingKey);
+        if (continuations.length > 0) {
+            return {
+                contextual: [
+                    `${options.pendingKey} …`,
+                    ...continuations.map((entry) => `${entry.key} ${entry.label}`),
+                ],
+                global: ['esc cancel'],
+            };
+        }
+    }
     if (options.filterMode) {
         return {
             contextual: ['enter apply', 'esc cancel', 'ctrl+u clear'],
@@ -14271,13 +15010,13 @@ function getLogInkFooterHints(options) {
     }
     if (options.activeView === 'branches') {
         return {
-            contextual: ['↑/↓ branches', 'D delete', 'X checkout', 'enter diff', 'esc back'],
+            contextual: ['↑/↓ branches', 's sort', 'D delete', 'X checkout', 'enter diff'],
             global: NORMAL_GLOBAL_HINTS,
         };
     }
     if (options.activeView === 'tags') {
         return {
-            contextual: ['↑/↓ tags', 'T create', 'X push', 'esc back'],
+            contextual: ['↑/↓ tags', 's sort', 'T create', 'X push', 'esc back'],
             global: NORMAL_GLOBAL_HINTS,
         };
     }
@@ -14431,6 +15170,110 @@ function filterLogInkPaletteCommands(commands, filter, recent) {
         .map((entry) => entry.command);
 }
 
+/**
+ * The chars `git log --graph` emits for branch topology — `*`, `|`, `\`,
+ * `/`, `_`, ` `. ASCII-only output is bulletproof for legacy terminals
+ * but the angles read poorly when many branches overlap.
+ *
+ * `substituteGraphChars` swaps them for box-drawing / geometric Unicode
+ * equivalents when the terminal can render them; falls back to ASCII
+ * under `theme.ascii` (TERM=dumb / vt100) and `theme.noColor` is
+ * orthogonal — the Unicode chars are still rendered, just without color.
+ *
+ * Kept ASCII-only intentionally:
+ *   - alphanumerics       (commit refs / annotations git sometimes injects)
+ *   - parens / brackets   (HEAD decoration markers, not part of the graph)
+ *   - hyphens / colons    (likewise)
+ */
+const ASCII_TO_UNICODE = {
+    '*': '●',
+    '|': '│',
+    '/': '╱',
+    '\\': '╲',
+    '_': '─',
+};
+function substituteGraphChars(graph, options) {
+    if (options.ascii) {
+        return graph;
+    }
+    let output = '';
+    for (const character of graph) {
+        output += ASCII_TO_UNICODE[character] ?? character;
+    }
+    return output;
+}
+
+/**
+ * OSC 8 hyperlink helpers for the Ink TUI (P5.1).
+ *
+ * Modern terminals (iTerm2, kitty, WezTerm, Ghostty, recent VS Code, Windows
+ * Terminal, Alacritty, foot) recognise the OSC 8 escape sequence and turn
+ * the wrapped text into a clickable / Cmd-clickable link. Older or
+ * minimal terminals ignore the sequence — but a few of them render the
+ * escape codes as raw garbage instead, so we feature-detect and fall back
+ * to plain text rather than always emitting.
+ *
+ * Sequence:  ESC ] 8 ; ; <url> ESC \  <text>  ESC ] 8 ; ;  ESC \
+ */
+const ESC = '\u001b';
+const OSC_PREFIX = `${ESC}]8;;`;
+const ST = `${ESC}\\`;
+/**
+ * Detect whether the host terminal will likely render OSC 8 hyperlinks.
+ *
+ * Conservative: only returns true for terminals that have publicly
+ * confirmed support. Unknown terminals fall back to plain text — making
+ * the wrap a no-op rather than risking garbage output. Set
+ * `FORCE_HYPERLINK=1` to override during testing.
+ */
+function supportsHyperlinks(env = process.env) {
+    if (env.FORCE_HYPERLINK) {
+        return env.FORCE_HYPERLINK !== '0';
+    }
+    // Honor NO_COLOR for parity with our color handling — users who opt out
+    // of color formatting generally want a clean plain-text output too.
+    if (env.NO_COLOR) {
+        return false;
+    }
+    // kitty publishes either of these markers.
+    if (env.KITTY_WINDOW_ID || env.TERM === 'xterm-kitty') {
+        return true;
+    }
+    // Windows Terminal sets WT_SESSION.
+    if (env.WT_SESSION) {
+        return true;
+    }
+    // Ghostty exposes its resources dir.
+    if (env.GHOSTTY_RESOURCES_DIR) {
+        return true;
+    }
+    switch (env.TERM_PROGRAM) {
+        case 'iTerm.app':
+        case 'WezTerm':
+        case 'vscode':
+        case 'ghostty':
+        case 'mintty':
+        case 'Hyper':
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * Wrap `text` in an OSC 8 hyperlink when the host terminal supports it,
+ * otherwise return the plain text unchanged. Empty / missing url falls
+ * back to the plain text.
+ */
+function formatHyperlink(text, url, env = process.env) {
+    if (!url) {
+        return text;
+    }
+    if (!supportsHyperlinks(env)) {
+        return text;
+    }
+    return `${OSC_PREFIX}${url}${ST}${text}${OSC_PREFIX}${ST}`;
+}
+
 function action(actionValue) {
     return {
         type: 'action',
@@ -14481,6 +15324,15 @@ function getLogInkPaletteExecuteEvents(command, state) {
             return [action({ type: 'previousSidebarTab' })];
         case 'nextSidebarTab':
             return [action({ type: 'nextSidebarTab' })];
+        case 'previousHunk':
+        case 'nextHunk':
+            // Palette execution can't reach the live worktree/commit hunk offsets
+            // (those live in runtime state, not the reducer). Surface a hint and
+            // let the user press the keystroke directly in diff view.
+            return [action({
+                    type: 'setStatus',
+                    value: 'open the diff view and press [ or ] to jump hunks',
+                })];
         case 'focusNext':
             return [action({ type: 'focusNext' })];
         case 'focusPrevious':
@@ -14553,9 +15405,23 @@ function getLogInkPaletteExecuteEvents(command, state) {
             // Aggregate entry; individual workflows are surfaced separately.
             return [];
         case 'quit':
+            if (hasUnsavedComposeDraft(state)) {
+                return [action({ type: 'setPendingMutationConfirmation', value: 'discard-draft' })];
+            }
             return [{ type: 'exit' }];
         case 'clearSearch':
             return [action({ type: 'clearFilter' })];
+        case 'cycleSort':
+            if (state.activeView === 'branches') {
+                return [action({ type: 'cycleBranchSort' })];
+            }
+            if (state.activeView === 'tags') {
+                return [action({ type: 'cycleTagSort' })];
+            }
+            return [action({
+                    type: 'setStatus',
+                    value: 'Sort cycle is available in the branches and tags views',
+                })];
         default:
             return [];
     }
@@ -14567,8 +15433,24 @@ const SIDEBAR_TAB_BY_NUMBER = {
     '4': 'stashes',
     '5': 'worktrees',
 };
+/**
+ * Returns true when the compose surface holds an unsaved commit message
+ * (any text in summary or body and no in-flight AI draft). Used by the
+ * quit confirmation flow (P2.3) so users can't lose drafts via a stray
+ * `q` / Ctrl+C.
+ */
+function hasUnsavedComposeDraft(state) {
+    const compose = state.commitCompose;
+    if (compose.loading) {
+        return false;
+    }
+    return Boolean(compose.summary.trim() || compose.body.trim());
+}
 function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
     if (key.ctrl && inputValue === 'c') {
+        if (hasUnsavedComposeDraft(state) && !state.pendingMutationConfirmation) {
+            return [action({ type: 'setPendingMutationConfirmation', value: 'discard-draft' })];
+        }
         return [{ type: 'exit' }];
     }
     if (state.commitCompose.editing) {
@@ -14600,7 +15482,17 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
         return [];
     }
     if (state.filterMode) {
-        if (key.return || key.escape) {
+        if (key.return) {
+            return [action({ type: 'toggleFilterMode' })];
+        }
+        // Two-stage Esc (P2.4 / P4.4): first Esc with a non-empty filter
+        // clears the input but keeps filterMode active so the user can keep
+        // typing; second Esc exits filterMode entirely. Matches vim and
+        // most modal TUIs.
+        if (key.escape) {
+            if (state.filter.length > 0) {
+                return [action({ type: 'clearFilterText' })];
+            }
             return [action({ type: 'toggleFilterMode' })];
         }
         if (key.backspace || key.delete) {
@@ -14623,14 +15515,19 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
                     action({ type: 'setPendingConfirmation', value: undefined }),
                 ];
             }
+            // Destructive + provider workflow actions (delete-branch, delete-tag,
+            // drop-stash, remove-worktree, abort-operation, create-pr, …) defer
+            // to the runtime — it has the live context needed to identify the
+            // selected item and run the right action function.
+            if (workflowAction) {
+                return [
+                    { type: 'runWorkflowAction', id: workflowAction.id },
+                    action({ type: 'setPendingConfirmation', value: undefined }),
+                ];
+            }
             return [
                 action({ type: 'setPendingConfirmation', value: undefined }),
-                action({
-                    type: 'setStatus',
-                    value: workflowAction
-                        ? `${workflowAction.label} queued for workflow execution`
-                        : 'workflow action queued',
-                }),
+                action({ type: 'setStatus', value: 'workflow action queued' }),
             ];
         }
         if (inputValue === 'n' || key.escape) {
@@ -14643,6 +15540,12 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
     }
     if (state.pendingMutationConfirmation) {
         if (inputValue === 'y') {
+            if (state.pendingMutationConfirmation === 'discard-draft') {
+                return [
+                    action({ type: 'setPendingMutationConfirmation', value: undefined }),
+                    { type: 'exit' },
+                ];
+            }
             return [
                 state.pendingMutationConfirmation === 'revert-hunk'
                     ? { type: 'revertSelectedHunk' }
@@ -14651,9 +15554,12 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
             ];
         }
         if (inputValue === 'n' || key.escape) {
+            const cancelMessage = state.pendingMutationConfirmation === 'discard-draft'
+                ? 'kept draft — press q again to quit without saving'
+                : 'revert cancelled';
             return [
                 action({ type: 'setPendingMutationConfirmation', value: undefined }),
-                action({ type: 'setStatus', value: 'revert cancelled' }),
+                action({ type: 'setStatus', value: cancelMessage }),
             ];
         }
         return [];
@@ -14661,6 +15567,11 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
     if (state.showCommandPalette) {
         const filtered = filterLogInkPaletteCommands(getLogInkPaletteCommands(), state.paletteFilter, state.paletteRecent);
         if (key.escape) {
+            // Two-stage Esc inside the palette: first Esc with non-empty
+            // input clears the filter; second Esc closes the palette. P2.4.
+            if (state.paletteFilter.length > 0) {
+                return [action({ type: 'clearPaletteFilter' })];
+            }
             return [action({ type: 'toggleCommandPalette' })];
         }
         if (key.return) {
@@ -14707,6 +15618,9 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
         return [action({ type: 'popView' })];
     }
     if (inputValue === 'q') {
+        if (hasUnsavedComposeDraft(state)) {
+            return [action({ type: 'setPendingMutationConfirmation', value: 'discard-draft' })];
+        }
         return [{ type: 'exit' }];
     }
     if (inputValue === '?') {
@@ -14787,13 +15701,51 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
     if (inputValue === 'r') {
         return [{ type: 'refreshContext' }];
     }
+    if (inputValue === 's') {
+        if (state.activeView === 'branches') {
+            return [action({ type: 'cycleBranchSort' })];
+        }
+        if (state.activeView === 'tags') {
+            return [action({ type: 'cycleTagSort' })];
+        }
+        // Falls through so other views (history/status/diff/compose/stash) still
+        // see the literal `s` for whatever per-view bindings they may grow.
+    }
     if (inputValue === ':') {
         return [action({ type: 'toggleCommandPalette' })];
     }
     if (inputValue === '[') {
+        if (state.activeView === 'diff' && context.worktreeHunkOffsets?.length) {
+            return [action({
+                    type: 'jumpWorktreeHunk',
+                    delta: -1,
+                    hunkOffsets: context.worktreeHunkOffsets,
+                })];
+        }
+        if (state.activeView === 'diff' && context.commitDiffHunkOffsets?.length) {
+            return [action({
+                    type: 'jumpCommitDiffHunk',
+                    delta: -1,
+                    hunkOffsets: context.commitDiffHunkOffsets,
+                })];
+        }
         return [action({ type: 'previousSidebarTab' })];
     }
     if (inputValue === ']') {
+        if (state.activeView === 'diff' && context.worktreeHunkOffsets?.length) {
+            return [action({
+                    type: 'jumpWorktreeHunk',
+                    delta: 1,
+                    hunkOffsets: context.worktreeHunkOffsets,
+                })];
+        }
+        if (state.activeView === 'diff' && context.commitDiffHunkOffsets?.length) {
+            return [action({
+                    type: 'jumpCommitDiffHunk',
+                    delta: 1,
+                    hunkOffsets: context.commitDiffHunkOffsets,
+                })];
+        }
         return [action({ type: 'nextSidebarTab' })];
     }
     if (SIDEBAR_TAB_BY_NUMBER[inputValue]) {
@@ -14813,11 +15765,22 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
                     fileCount: context.worktreeFileCount,
                 })];
         }
+        // Diff view: j/k scrolls the visible diff one line. Hunk navigation
+        // moved to ]/[ so single-hunk files (longer than the preview pane)
+        // can scroll bidirectionally instead of getting pinned to a hunk
+        // anchor.
         if (state.activeView === 'diff' && context.worktreeDiffLineCount) {
             return [action({
-                    type: 'jumpWorktreeHunk',
+                    type: 'pageWorktreeDiff',
                     delta: -1,
-                    hunkOffsets: context.worktreeHunkOffsets || [],
+                    lineCount: context.worktreeDiffLineCount,
+                })];
+        }
+        if (state.activeView === 'diff' && context.previewLineCount) {
+            return [action({
+                    type: 'pageDetailPreview',
+                    delta: -1,
+                    previewLineCount: context.previewLineCount,
                 })];
         }
         if (state.activeView === 'branches' && context.branchCount) {
@@ -14829,6 +15792,13 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
         if (state.activeView === 'stash' && context.stashCount) {
             return [action({ type: 'moveStash', delta: -1, count: context.stashCount })];
         }
+        if (state.activeView === 'history' &&
+            state.focus === 'commits' &&
+            state.selectedIndex === 0 &&
+            !state.pendingCommitFocused &&
+            context.worktreeDirty) {
+            return [action({ type: 'focusPendingCommit' })];
+        }
         return [
             action(state.focus === 'sidebar'
                 ? { type: 'previousSidebarTab' }
@@ -14836,6 +15806,9 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
         ];
     }
     if (key.downArrow || inputValue === 'j') {
+        if (state.activeView === 'history' && state.pendingCommitFocused) {
+            return [action({ type: 'unfocusPendingCommit' })];
+        }
         if (state.focus === 'detail' && context.detailFileCount) {
             return [action({ type: 'moveDetailFile', delta: 1, fileCount: context.detailFileCount })];
         }
@@ -14848,9 +15821,16 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
         }
         if (state.activeView === 'diff' && context.worktreeDiffLineCount) {
             return [action({
-                    type: 'jumpWorktreeHunk',
+                    type: 'pageWorktreeDiff',
+                    delta: 1,
+                    lineCount: context.worktreeDiffLineCount,
+                })];
+        }
+        if (state.activeView === 'diff' && context.previewLineCount) {
+            return [action({
+                    type: 'pageDetailPreview',
                     delta: 1,
-                    hunkOffsets: context.worktreeHunkOffsets || [],
+                    previewLineCount: context.previewLineCount,
                 })];
         }
         if (state.activeView === 'branches' && context.branchCount) {
@@ -14876,6 +15856,13 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
                     lineCount: context.worktreeDiffLineCount,
                 })];
         }
+        if (state.activeView === 'diff' && context.previewLineCount) {
+            return [action({
+                    type: 'pageDetailPreview',
+                    delta: -8,
+                    previewLineCount: context.previewLineCount,
+                })];
+        }
         if (state.focus === 'detail' && context.previewLineCount) {
             return [action({
                     type: 'pageDetailPreview',
@@ -14893,6 +15880,13 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
                     lineCount: context.worktreeDiffLineCount,
                 })];
         }
+        if (state.activeView === 'diff' && context.previewLineCount) {
+            return [action({
+                    type: 'pageDetailPreview',
+                    delta: 8,
+                    previewLineCount: context.previewLineCount,
+                })];
+        }
         if (state.focus === 'detail' && context.previewLineCount) {
             return [action({
                     type: 'pageDetailPreview',
@@ -14902,6 +15896,17 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
         }
         return [action({ type: 'page', delta: 10 })];
     }
+    // Enter on the synthetic "(+) new commit" row pushes the status view so
+    // the user can stage/commit. The pending flag is cleared on view push so
+    // popping back lands on the real commit at index 0.
+    if (key.return &&
+        state.activeView === 'history' &&
+        state.pendingCommitFocused) {
+        return [
+            action({ type: 'pushView', value: 'status' }),
+            action({ type: 'setStatus', value: 'staging worktree changes' }),
+        ];
+    }
     if (key.return &&
         state.activeView === 'history' &&
         state.focus === 'commits' &&
@@ -14918,6 +15923,25 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
             ];
         }
     }
+    // From the inspector / commit-diff detail panel, Enter opens (or refocuses)
+    // the diff view scoped to the currently-selected commit and file. Lets the
+    // user drive the explore flow entirely from the right panel: j/k picks a
+    // file, Enter opens the diff for it.
+    if (key.return &&
+        state.focus === 'detail' &&
+        (state.activeView === 'history' || state.activeView === 'diff') &&
+        context.detailFileCount &&
+        state.filteredCommits.length > 0) {
+        const selected = state.filteredCommits[state.selectedIndex];
+        if (selected) {
+            return [action({
+                    type: 'navigateOpenDiffForCommit',
+                    sha: selected.hash,
+                    commitIndex: state.selectedIndex,
+                    fileIndex: state.selectedFileIndex,
+                })];
+        }
+    }
     if (key.return && state.activeView === 'status' && context.worktreeFileCount) {
         return [action({
                 type: 'navigateOpenDiffForWorktreeFile',
@@ -14967,6 +15991,294 @@ function getLogInkInputEvents(state, inputValue, key = {}, context = {}) {
     return [];
 }
 
+/**
+ * Track whether the user has seen the first-launch onboarding overlay
+ * (P1.3 from #756) via an XDG-friendly marker file. We persist this
+ * outside of `.coco.config.json` so a fresh repo doesn't re-show the
+ * tip when the user already dismissed it elsewhere.
+ *
+ * The marker is touched empty — its existence is the signal. Writes
+ * are best-effort: filesystem failures (read-only $HOME, permissions)
+ * fall back to "already seen" so we never block startup.
+ */
+const MARKER_BASENAME = 'onboarding.seen';
+function resolveCacheDir() {
+    const xdg = process.env.XDG_CACHE_HOME;
+    if (xdg && xdg.trim().length > 0) {
+        return path__namespace$1.join(xdg, 'coco');
+    }
+    return path__namespace$1.join(os__namespace$1.homedir(), '.cache', 'coco');
+}
+function getOnboardingMarkerPath() {
+    return path__namespace$1.join(resolveCacheDir(), MARKER_BASENAME);
+}
+function hasSeenOnboarding() {
+    try {
+        return fs__namespace$1.existsSync(getOnboardingMarkerPath());
+    }
+    catch {
+        // If we can't even stat the path (sandboxed env, etc.), treat the
+        // user as "seen" so we don't keep showing a panel they can never
+        // dismiss persistently.
+        return true;
+    }
+}
+function markOnboardingSeen() {
+    const markerPath = getOnboardingMarkerPath();
+    try {
+        fs__namespace$1.mkdirSync(path__namespace$1.dirname(markerPath), { recursive: true });
+        fs__namespace$1.writeFileSync(markerPath, '');
+    }
+    catch {
+        // Best-effort persistence; swallow.
+    }
+}
+
+/**
+ * Promoted-view selection rectification on filter changes (P4.5).
+ *
+ * Without this, the reducer used to snap selectedBranchIndex/Tag/Stash to 0
+ * on every filter keystroke — which kept the cursor in range but lost the
+ * user's place even when the previously-selected item was still in the
+ * filtered result.
+ *
+ * The proper behavior (called out in #756 P4.5):
+ *   - If the previously-selected item is still in the filtered list, the
+ *     cursor follows it (its new index in the filtered list).
+ *   - If it dropped out of the filtered list, snap to result[0].
+ *   - If no filter change happened, leave the cursor alone.
+ *
+ * Implementation: the runtime computes a `PromotedSelectionsSnapshot` from
+ * existing context items + the predicted next filter, attaches it to the
+ * filter-mutating action, and the reducer applies the precomputed indexes.
+ *
+ * The rectification is a pure function over (lookup, filteredKeys); see
+ * inkSelectionRectify.test.ts for the cases it covers.
+ */
+/**
+ * Map (filtered keys, previously-selected key) → new selected index.
+ * Falls back to 0 when the key dropped out or no key was provided —
+ * matching the spec's "snap to result[0]" requirement.
+ *
+ * The runtime is responsible for producing `filteredKeys` using the same
+ * match function the renderer uses (multi-field haystacks per item).
+ */
+function rectifyPromotedSelectionIndex(filteredKeys, selectedKey) {
+    if (filteredKeys.length === 0) {
+        return 0;
+    }
+    if (!selectedKey) {
+        return 0;
+    }
+    const next = filteredKeys.indexOf(selectedKey);
+    return next < 0 ? 0 : next;
+}
+
+const DEFAULT_DEBOUNCE_MS = 250;
+const DEFAULT_SCHEDULER = {
+    // `callback` is typed `() => void` (a function reference, never a string),
+    // and `ms` is a number, so the eval-injection vector behind DevSkim
+    // DS172411 doesn't apply here.
+    // DevSkim: ignore DS172411
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+/**
+ * Pure debouncer that coalesces a burst of `trigger` calls into one
+ * `onSettle` invocation. Tracks the highest-severity kind across the
+ * window so a fast sequence of worktree-then-HEAD changes still produces
+ * a single `full` refresh.
+ *
+ * Extracted from the watcher so it's testable without touching `fs.watch`.
+ */
+function createRefreshDebouncer(options) {
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+    const scheduler = options.scheduler ?? DEFAULT_SCHEDULER;
+    let timer = null;
+    let pendingKind = null;
+    const onTimerFire = () => {
+        timer = null;
+        const kindToEmit = pendingKind || 'worktree';
+        pendingKind = null;
+        options.onSettle(kindToEmit);
+    };
+    const trigger = (kind) => {
+        pendingKind = pendingKind === 'full' ? 'full' : kind;
+        if (timer !== null) {
+            scheduler.clearTimeout(timer);
+        }
+        // The first arg is a function value defined above (`onTimerFire`),
+        // never a string, so the eval-injection vector that drives
+        // DevSkim DS172411 doesn't apply here. The second arg is also our
+        // own `debounceMs` constant — no caller-supplied data flows in.
+        // DevSkim: ignore DS172411
+        timer = scheduler.setTimeout(onTimerFire, debounceMs);
+    };
+    const close = () => {
+        if (timer !== null) {
+            scheduler.clearTimeout(timer);
+            timer = null;
+        }
+        pendingKind = null;
+    };
+    return { trigger, close };
+}
+/**
+ * Watch the repo's `.git` metadata + the working tree root for changes
+ * that should refresh the TUI's repository context. Best-effort: missing
+ * paths or platforms without `fs.watch` support degrade gracefully — the
+ * user can still manually refresh with `r`.
+ *
+ * The watch surface is deliberately narrow:
+ *
+ * - `.git/index` (worktree refresh) — fires on `git add` / `rm` / `commit`
+ * - `.git/HEAD` (full refresh)      — fires on branch switches
+ * - `.git/refs/heads` recursively (full refresh) — fires on commits to a
+ *   branch tip, branch creation/deletion
+ * - repo root non-recursively (worktree refresh) — picks up top-level
+ *   create/delete/rename. Subdirectory unstaged edits do NOT trigger an
+ *   auto-refresh; the user can press `r` for those, which keeps watch
+ *   overhead negligible on large repos.
+ */
+function createRefreshWatcher(options) {
+    const debouncer = createRefreshDebouncer({
+        debounceMs: options.debounceMs,
+        onSettle: options.onChange,
+    });
+    const watchers = [];
+    const safeWatch = (pathname, kind, watchOptions = {}) => {
+        try {
+            const watcher = fs__namespace$1.watch(pathname, watchOptions, () => debouncer.trigger(kind));
+            // fs.watch errors at runtime (e.g. file removed) shouldn't crash the
+            // TUI — the watcher is best-effort.
+            watcher.on('error', () => { });
+            watchers.push(watcher);
+        }
+        catch {
+            // Path may not exist (fresh repo with no commits yet) or the platform
+            // may not support fs.watch on this entry. Skip silently.
+        }
+    };
+    safeWatch(path__namespace$1.join(options.gitDir, 'index'), 'worktree');
+    safeWatch(path__namespace$1.join(options.gitDir, 'HEAD'), 'full');
+    safeWatch(path__namespace$1.join(options.gitDir, 'refs', 'heads'), 'full', { recursive: true });
+    safeWatch(options.repoRoot, 'worktree');
+    return {
+        close: () => {
+            debouncer.close();
+            for (const watcher of watchers) {
+                try {
+                    watcher.close();
+                }
+                catch {
+                    // already closed; ignore
+                }
+            }
+            watchers.length = 0;
+        },
+    };
+}
+
+/**
+ * Install panic + suspend handlers around an Ink instance so the terminal
+ * never gets left in alt-screen / raw-mode / hidden-cursor state when:
+ *
+ *   - an uncaught exception throws past Ink's render loop (P1.4)
+ *   - the user hits Ctrl+Z and the kernel raises SIGTSTP (P1.5)
+ *
+ * `dispose()` removes every registered listener so a clean exit doesn't
+ * leak global handlers on subsequent runs.
+ *
+ * The escape sequences here are the standard ANSI/xterm trio:
+ *   - `\x1b[?25h`  — show the cursor
+ *   - `\x1b[?25l`  — hide the cursor
+ *   - `\x1b[?1049l` — exit alt screen
+ *   - `\x1b[?1049h` — enter alt screen
+ */
+const SHOW_CURSOR = '\x1b[?25h';
+const HIDE_CURSOR = '\x1b[?25l';
+const ENTER_ALT_SCREEN = '\x1b[?1049h';
+const EXIT_ALT_SCREEN = '\x1b[?1049l';
+const tryWrite = (output, sequence) => {
+    try {
+        output.write(sequence);
+    }
+    catch {
+        // stream may already be closed during shutdown; ignore
+    }
+};
+const trySetRawMode = (input, value) => {
+    try {
+        input.setRawMode?.(value);
+    }
+    catch {
+        // stdin may not be a TTY; ignore
+    }
+};
+const tryUnmount = (instance) => {
+    try {
+        instance.unmount();
+    }
+    catch {
+        // Ink may have already cleaned up; ignore
+    }
+};
+function installTerminalLifecycle(options) {
+    const { input, instance, output } = options;
+    const restoreTerminal = () => {
+        // Belt-and-suspenders: tell Ink to unmount AND write the escape
+        // sequences directly. Ink's unmount handles most cases but we've
+        // seen it leave artifacts when a render is in flight at panic time.
+        tryUnmount(instance);
+        trySetRawMode(input, false);
+        tryWrite(output, `${SHOW_CURSOR}${EXIT_ALT_SCREEN}`);
+    };
+    const handlePanic = (error) => {
+        restoreTerminal();
+        if (options.onPanic) {
+            options.onPanic(error);
+        }
+        else if (error instanceof Error) {
+            process.stderr.write(`\n${error.stack || error.message}\n`);
+        }
+        else {
+            process.stderr.write(`\n${String(error)}\n`);
+        }
+        // Exit with non-zero so callers (CI, scripts) see the failure.
+        process.exit(1);
+    };
+    const onUncaughtException = (error) => handlePanic(error);
+    const onUnhandledRejection = (reason) => handlePanic(reason);
+    // Ctrl+Z: leave the alt screen + restore the cursor + drop raw mode
+    // BEFORE the kernel actually suspends us. We don't unmount Ink — the
+    // tree stays alive so SIGCONT can repaint without re-mounting.
+    const onSigtstp = () => {
+        trySetRawMode(input, false);
+        tryWrite(output, `${SHOW_CURSOR}${EXIT_ALT_SCREEN}`);
+        process.kill(process.pid, 'SIGSTOP');
+    };
+    // Resume: re-enter alt screen + hide cursor + raw mode back on, then
+    // ask the runtime to nudge React so the user lands on a painted screen
+    // instead of an empty alt buffer.
+    const onSigcont = () => {
+        tryWrite(output, `${ENTER_ALT_SCREEN}${HIDE_CURSOR}`);
+        trySetRawMode(input, true);
+        options.onResume?.();
+    };
+    process.on('uncaughtException', onUncaughtException);
+    process.on('unhandledRejection', onUnhandledRejection);
+    process.on('SIGTSTP', onSigtstp);
+    process.on('SIGCONT', onSigcont);
+    return {
+        dispose: () => {
+            process.off('uncaughtException', onUncaughtException);
+            process.off('unhandledRejection', onUnhandledRejection);
+            process.off('SIGTSTP', onSigtstp);
+            process.off('SIGCONT', onSigcont);
+        },
+    };
+}
+
 const LOG_INK_MIN_COLUMNS = 80;
 const LOG_INK_MIN_ROWS = 24;
 const LOG_INK_DEFAULT_COLUMNS = 120;
@@ -14974,16 +16286,83 @@ const LOG_INK_DEFAULT_ROWS = 40;
 function getLogInkLayout(input) {
     const columns = input.columns || LOG_INK_DEFAULT_COLUMNS;
     const rows = input.rows || LOG_INK_DEFAULT_ROWS;
+    const detailWidth = Math.max(30, Math.min(56, Math.floor(columns * 0.34)));
+    const sidebarWidth = Math.max(22, Math.min(34, Math.floor(columns * 0.24)));
     return {
         bodyRows: Math.max(8, rows - 5),
         columns,
-        detailWidth: Math.max(30, Math.min(56, Math.floor(columns * 0.34))),
+        detailWidth,
+        mainPanelWidth: Math.max(20, columns - sidebarWidth - detailWidth),
         rows,
-        sidebarWidth: Math.max(22, Math.min(34, Math.floor(columns * 0.24))),
+        sidebarWidth,
         tooSmall: columns < LOG_INK_MIN_COLUMNS || rows < LOG_INK_MIN_ROWS,
     };
 }
 
+/**
+ * Explicit color-level detection for the Ink TUI (P5.2).
+ *
+ * Chalk already approximates hex colors when the terminal can't render
+ * truecolor — but we want an explicit signal so the catppuccin / gruvbox
+ * presets (which use hex) can fall back to the ANSI-named `default` preset
+ * cleanly on minimal SSH sessions, instead of relying on chalk's
+ * heuristics. Users who set `NO_COLOR` or pick the `monochrome` preset
+ * still get the manual override.
+ *
+ * Levels (matching the chalk taxonomy):
+ *   - 'mono'      → no ANSI escapes at all (NO_COLOR / TERM=dumb)
+ *   - '16'        → standard 16-color ANSI palette
+ *   - '256'       → xterm-256color
+ *   - 'truecolor' → 24-bit RGB (COLORTERM=truecolor or known terminals)
+ */
+function getColorLevel(env = process.env) {
+    if (env.NO_COLOR)
+        return 'mono';
+    switch (env.FORCE_COLOR) {
+        case '0':
+            return 'mono';
+        case '1':
+            return '16';
+        case '2':
+            return '256';
+        case '3':
+            return 'truecolor';
+    }
+    const colorterm = env.COLORTERM?.toLowerCase();
+    if (colorterm === 'truecolor' || colorterm === '24bit') {
+        return 'truecolor';
+    }
+    // Modern terminal emulators that publicly advertise truecolor support.
+    if (env.KITTY_WINDOW_ID || env.TERM === 'xterm-kitty') {
+        return 'truecolor';
+    }
+    if (env.WT_SESSION) {
+        return 'truecolor';
+    }
+    switch (env.TERM_PROGRAM) {
+        case 'iTerm.app':
+        case 'WezTerm':
+        case 'vscode':
+        case 'ghostty':
+        case 'Hyper':
+            return 'truecolor';
+    }
+    if (env.TERM === 'dumb')
+        return 'mono';
+    if (env.TERM?.includes('256color'))
+        return '256';
+    return '16';
+}
+const TRUECOLOR_PRESETS = new Set(['catppuccin', 'gruvbox']);
+/**
+ * `true` when the named preset relies on hex colors that look best under
+ * 24-bit RGB. Used by `createLogInkTheme` to decide whether to downgrade
+ * to the ANSI-named `default` palette on lower-capability terminals.
+ */
+function presetUsesTrueColor(preset) {
+    return preset !== undefined && TRUECOLOR_PRESETS.has(preset);
+}
+
 const THEME_PRESET_COLORS = {
     default: {
         accent: 'cyan',
@@ -15038,7 +16417,15 @@ function createLogInkTheme(options = {}) {
     const noColor = (options.noColor ?? Boolean(process.env.NO_COLOR)) ||
         options.preset === 'monochrome';
     const ascii = options.ascii ?? shouldUseAscii(options.term ?? process.env.TERM);
-    const preset = options.preset && options.preset !== 'monochrome' ? options.preset : 'default';
+    const requestedPreset = options.preset && options.preset !== 'monochrome' ? options.preset : 'default';
+    // P5.2 — gracefully downgrade hex presets (catppuccin / gruvbox) when
+    // the host terminal can't render truecolor. Chalk approximates hex in
+    // those modes anyway, but the default preset's ANSI-named palette
+    // renders far more faithfully on 16-color terminals.
+    const colorLevel = getColorLevel(options.env ?? process.env);
+    const preset = !noColor && presetUsesTrueColor(requestedPreset) && colorLevel !== 'truecolor'
+        ? 'default'
+        : requestedPreset;
     const colors = noColor
         ? {}
         : {
@@ -15053,6 +16440,313 @@ function createLogInkTheme(options = {}) {
     };
 }
 
+/**
+ * Iconography helpers for the Ink TUI surfaces.
+ *
+ * Letters always carry the meaning; symbols enhance. Glyphs come from the
+ * Geometric Shapes / Arrows blocks (high-compat Unicode, no emoji), and all
+ * helpers degrade cleanly under `theme.ascii` and `theme.noColor`.
+ */
+/**
+ * Format a branch's relationship to its upstream.
+ * - no upstream  → "no upstream"
+ * - even         → "even with <upstream>"
+ * - divergent    → "↑<ahead> ↓<behind> <upstream>" (only the non-zero side
+ *   is rendered so the line stays tight). ASCII mode falls back to the
+ *   legacy `+N/-N` form.
+ */
+function formatBranchDivergence(branch, options = {}) {
+    if (!branch.upstream) {
+        return 'no upstream';
+    }
+    if (branch.ahead === 0 && branch.behind === 0) {
+        return `even with ${branch.upstream}`;
+    }
+    if (options.ascii) {
+        return `+${branch.ahead}/-${branch.behind} ${branch.upstream}`;
+    }
+    const parts = [];
+    if (branch.ahead > 0)
+        parts.push(`↑${branch.ahead}`);
+    if (branch.behind > 0)
+        parts.push(`↓${branch.behind}`);
+    return `${parts.join(' ')} ${branch.upstream}`;
+}
+/**
+ * Single-cell marker shown to the left of a branch name in lists.
+ * `*` = current, `◌` = no upstream (detached from a remote), space otherwise.
+ */
+function branchRowMarker(branch, options = {}) {
+    if (branch.current)
+        return '*';
+    if (!branch.upstream)
+        return options.ascii ? '?' : '◌';
+    return ' ';
+}
+/**
+ * Pick the glyph + color for a PR state badge.
+ * Returns an empty glyph under ASCII mode so the textual state (OPEN /
+ * MERGED / DRAFT / CLOSED) carries the meaning alone.
+ */
+function getPullRequestStateGlyph(pr, theme) {
+    if (theme.ascii) {
+        return { glyph: '', color: undefined, dim: false };
+    }
+    if (pr.isDraft) {
+        return { glyph: '◇', color: undefined, dim: true };
+    }
+    switch (pr.state.toUpperCase()) {
+        case 'OPEN':
+            return { glyph: '◉', color: theme.colors.success, dim: false };
+        case 'MERGED':
+            return { glyph: '●', color: theme.noColor ? undefined : 'magenta', dim: false };
+        case 'CLOSED':
+            return { glyph: '×', color: theme.colors.danger, dim: false };
+        default:
+            return { glyph: '·', color: undefined, dim: true };
+    }
+}
+/**
+ * Color for the leading dot in a status row. `undefined` means "skip the
+ * dot" — under noColor or ascii mode the dot carries no information so the
+ * raw porcelain codes (M / ?? / etc.) and the textual state carry meaning
+ * alone.
+ */
+function getStageStatusDotColor(state, theme) {
+    if (theme.noColor || theme.ascii)
+        return undefined;
+    switch (state) {
+        case 'unstaged':
+            return theme.colors.danger;
+        case 'staged':
+            return theme.colors.warning;
+        case 'untracked':
+            return theme.colors.muted;
+        default:
+            return undefined;
+    }
+}
+const STAGE_STATUS_DOT = '●';
+/**
+ * Count to show next to a sidebar tab name, or `undefined` when the
+ * underlying data has not loaded yet (so the label renders without a `(N)`
+ * rather than a misleading `(0)`).
+ */
+function sidebarTabCount(tab, context) {
+    switch (tab) {
+        case 'status':
+            return context.worktree?.files.length;
+        case 'branches':
+            return context.branches?.localBranches.length;
+        case 'tags':
+            return context.tags?.tags.length;
+        case 'stashes':
+            return context.stashes?.stashes.length;
+        case 'worktrees':
+            return context.worktreeList?.worktrees.length;
+        default:
+            return undefined;
+    }
+}
+
+/**
+ * Idle status-line tip rotation (P4.3).
+ *
+ * Off by default; opt-in via `logTui.idleTips: true`. The runtime drives a
+ * tick counter that this module turns into a tip — pure mapping so the
+ * cadence + content can be tested without spinning React or timers.
+ *
+ * Convention:
+ *   - tickIndex 0   → no tip (initial grace, before the first idle window).
+ *   - tickIndex N>0 → IDLE_TIPS[(N - 1) % IDLE_TIPS.length].
+ *
+ * The runtime keeps tickIndex at 0 whenever the user is active or
+ * `state.statusMessage` is non-empty, so the tip only appears during true
+ * idle stretches.
+ */
+const IDLE_TIPS = [
+    'press : to search every command',
+    'g h returns home from anywhere',
+    '/ filters the active view',
+    'press ? to see the full keymap',
+    's cycles sort modes in branches and tags',
+    'gz opens the stash view',
+    '< or esc walks the navigation stack back',
+];
+/**
+ * Threshold (in ms) of idle time before the first tip appears. Picked at 10s
+ * to match the spec in #756 — long enough that an active user never sees
+ * one, short enough to be useful when the user genuinely paused.
+ */
+const IDLE_TIPS_GRACE_MS = 10000;
+/** Cadence between subsequent tips in ms. */
+const IDLE_TIPS_INTERVAL_MS = 8000;
+function pickIdleTip(tickIndex) {
+    if (tickIndex <= 0)
+        return undefined;
+    if (IDLE_TIPS.length === 0)
+        return undefined;
+    return IDLE_TIPS[(tickIndex - 1) % IDLE_TIPS.length];
+}
+
+/**
+ * Preview-pane content formatters for the promoted views (P4.1).
+ *
+ * Each formatter turns an existing context entry into a list of lines the
+ * detail panel renders on the right. Pure — no git calls, no React — so the
+ * shape is easy to assert in unit tests and the renderer stays a simple map
+ * over the result.
+ *
+ * Designed to mirror what `lazygit` / `yazi` show in their preview pane:
+ * the answer to "what am I about to act on" without forcing a checkout / show.
+ */
+const heading = (text) => ({ text, emphasis: 'heading' });
+const dim = (text) => ({ text, emphasis: 'dim' });
+const line = (text) => ({ text });
+const blank = () => ({ text: '' });
+function shortHash(hash) {
+    return hash ? hash.slice(0, 7) : '<none>';
+}
+/* ------------------------------- branch -------------------------------- */
+function describeBranchDivergence(branch) {
+    if (branch.ahead === 0 && branch.behind === 0) {
+        return 'in sync';
+    }
+    return `${branch.ahead} ahead, ${branch.behind} behind`;
+}
+function formatBranchPreview(branch) {
+    if (!branch) {
+        return [dim('Select a branch to preview.')];
+    }
+    const out = [
+        heading(branch.shortName),
+        blank(),
+        line(`Tip:    ${shortHash(branch.hash)}`),
+        line(`Date:   ${branch.date || '<unknown>'}`),
+        line(`Subject: ${branch.subject || '<no subject>'}`),
+        blank(),
+    ];
+    if (branch.upstream) {
+        out.push(line(`Upstream: ${branch.upstream}`));
+        out.push(line(`Status:   ${describeBranchDivergence(branch)}`));
+    }
+    else {
+        out.push(dim('No upstream tracking.'));
+    }
+    if (branch.current) {
+        out.push(blank());
+        out.push(dim('* current branch'));
+    }
+    return out;
+}
+/* --------------------------------- tag --------------------------------- */
+function formatTagPreview(tag) {
+    if (!tag) {
+        return [dim('Select a tag to preview.')];
+    }
+    return [
+        heading(tag.name),
+        blank(),
+        line(`Commit:  ${shortHash(tag.hash)}`),
+        line(`Date:    ${tag.date || '<unknown>'}`),
+        blank(),
+        line('Subject:'),
+        line(`  ${tag.subject || '<no subject>'}`),
+    ];
+}
+function formatStashPreview(stash, options = {}) {
+    if (!stash) {
+        return [dim('Select a stash to preview.')];
+    }
+    const cap = options.fileCap ?? 10;
+    const out = [
+        heading(stash.ref),
+        blank(),
+        line(`On:      ${stash.branch || '<unknown>'}`),
+        line(`Commit:  ${shortHash(stash.hash)}`),
+        line(`Date:    ${stash.date || '<unknown>'}`),
+        blank(),
+        line('Message:'),
+        line(`  ${stash.message || '<no message>'}`),
+    ];
+    const files = stash.files || [];
+    if (files.length > 0) {
+        out.push(blank());
+        out.push(line(`Files (${files.length}):`));
+        files.slice(0, cap).forEach((path) => out.push(line(`  ${path}`)));
+        if (files.length > cap) {
+            out.push(dim(`  … ${files.length - cap} more`));
+        }
+    }
+    else {
+        out.push(blank());
+        out.push(dim('No files in stash.'));
+    }
+    return out;
+}
+
+/**
+ * Sort modes for the promoted views (P4.2).
+ *
+ * Pure: takes existing context entries + the active mode, returns a sorted
+ * copy. Tested in isolation; the runtime just calls these helpers.
+ *
+ * Display label uses `▼` (U+25BC) under truecolor / UTF-8 and falls back to
+ * `v` under ASCII. Letters (`recent` / `name` / `ahead`) carry meaning;
+ * shape enhances.
+ */
+const BRANCH_SORT_MODES = ['name', 'recent', 'ahead'];
+const DEFAULT_BRANCH_SORT_MODE = 'name';
+function cycleBranchSort(mode) {
+    const index = BRANCH_SORT_MODES.indexOf(mode);
+    if (index < 0)
+        return BRANCH_SORT_MODES[0];
+    return BRANCH_SORT_MODES[(index + 1) % BRANCH_SORT_MODES.length];
+}
+function sortBranches(branches, mode) {
+    const copy = branches.slice();
+    switch (mode) {
+        case 'name':
+            return copy.sort((a, b) => a.shortName.localeCompare(b.shortName));
+        case 'recent':
+            // ISO-shaped dates compare byte-for-byte; descending so the freshest
+            // branch sits at the top.
+            return copy.sort((a, b) => (b.date || '').localeCompare(a.date || '') ||
+                a.shortName.localeCompare(b.shortName));
+        case 'ahead':
+            // ahead-first; ties broken by behind, then by name. Keeps "this branch
+            // has unmerged work" in the user's first scroll.
+            return copy.sort((a, b) => b.ahead - a.ahead || b.behind - a.behind ||
+                a.shortName.localeCompare(b.shortName));
+        default:
+            return copy;
+    }
+}
+const TAG_SORT_MODES = ['recent', 'name'];
+const DEFAULT_TAG_SORT_MODE = 'recent';
+function cycleTagSort(mode) {
+    const index = TAG_SORT_MODES.indexOf(mode);
+    if (index < 0)
+        return TAG_SORT_MODES[0];
+    return TAG_SORT_MODES[(index + 1) % TAG_SORT_MODES.length];
+}
+function sortTags(tags, mode) {
+    const copy = tags.slice();
+    switch (mode) {
+        case 'name':
+            return copy.sort((a, b) => a.name.localeCompare(b.name));
+        case 'recent':
+            return copy.sort((a, b) => (b.date || '').localeCompare(a.date || '') ||
+                a.name.localeCompare(b.name));
+        default:
+            return copy;
+    }
+}
+/* ---------------------------- header indicator -------------------------- */
+function formatSortIndicator(mode, options = {}) {
+    return `${options.ascii ? 'v' : '▼'} ${mode}`;
+}
+
 /**
  * Empty- and loading-state messages for each TUI surface.
  *
@@ -15147,6 +16841,73 @@ function characterWidth(character) {
 function cellWidth(value) {
     return Array.from(value).reduce((width, character) => width + characterWidth(character), 0);
 }
+/**
+ * Word-wrap `value` into lines that each fit within `width` cells. Breaks
+ * on whitespace where possible; falls back to mid-word splits when a single
+ * word is wider than the budget. Preserves blank input as a single empty
+ * line so `value.split('\n').flatMap(wrapCells)` round-trips cleanly.
+ */
+function wrapCells(value, width) {
+    if (width < 1) {
+        return [value];
+    }
+    if (cellWidth(value) <= width) {
+        return [value];
+    }
+    const lines = [];
+    let current = '';
+    let currentWidth = 0;
+    const flush = () => {
+        if (current.length > 0) {
+            lines.push(current);
+            current = '';
+            currentWidth = 0;
+        }
+    };
+    // Tokenize into runs of whitespace + non-whitespace so we can keep word
+    // boundaries when possible.
+    const tokens = value.match(/\s+|\S+/g) || [];
+    for (const token of tokens) {
+        const tokenWidth = cellWidth(token);
+        if (currentWidth + tokenWidth <= width) {
+            current += token;
+            currentWidth += tokenWidth;
+            continue;
+        }
+        if (/^\s+$/.test(token)) {
+            // Drop boundary whitespace at line breaks.
+            flush();
+            continue;
+        }
+        flush();
+        if (tokenWidth <= width) {
+            current = token;
+            currentWidth = tokenWidth;
+            continue;
+        }
+        // Word longer than budget — hard-split into chunks.
+        let remaining = token;
+        while (cellWidth(remaining) > width) {
+            let chunk = '';
+            let chunkWidth = 0;
+            for (const character of Array.from(remaining)) {
+                const charW = characterWidth(character);
+                if (chunkWidth + charW > width)
+                    break;
+                chunk += character;
+                chunkWidth += charW;
+            }
+            lines.push(chunk);
+            remaining = remaining.slice(chunk.length);
+        }
+        if (remaining.length > 0) {
+            current = remaining;
+            currentWidth = cellWidth(remaining);
+        }
+    }
+    flush();
+    return lines.length > 0 ? lines : [value];
+}
 function truncateCells(value, width) {
     if (width < 1) {
         return '';
@@ -15268,6 +17029,8 @@ function withPushedView(state, value) {
         viewStack,
         worktreeDiffOffset: value === 'diff' ? state.worktreeDiffOffset : 0,
         selectedWorktreeHunkIndex: value === 'diff' ? state.selectedWorktreeHunkIndex : 0,
+        diffSource: value === 'diff' ? state.diffSource : undefined,
+        pendingCommitFocused: value === 'history' ? state.pendingCommitFocused : false,
         pendingKey: undefined,
     };
 }
@@ -15283,6 +17046,8 @@ function withPoppedView(state) {
         viewStack,
         worktreeDiffOffset: next === 'diff' ? state.worktreeDiffOffset : 0,
         selectedWorktreeHunkIndex: next === 'diff' ? state.selectedWorktreeHunkIndex : 0,
+        diffSource: next === 'diff' ? state.diffSource : undefined,
+        pendingCommitFocused: next === 'history' ? state.pendingCommitFocused : false,
         pendingKey: undefined,
     };
 }
@@ -15297,17 +17062,35 @@ function withReplacedView(state, value) {
         viewStack,
         worktreeDiffOffset: value === 'diff' ? state.worktreeDiffOffset : 0,
         selectedWorktreeHunkIndex: value === 'diff' ? state.selectedWorktreeHunkIndex : 0,
+        diffSource: value === 'diff' ? state.diffSource : undefined,
+        pendingCommitFocused: value === 'history' ? state.pendingCommitFocused : false,
         pendingKey: undefined,
     };
 }
-function withFilter$1(state, filter) {
+function withFilter$1(state, filter, promotedSelections) {
     const filteredCommits = filterCommits$1(state.commits, filter);
+    // P4.5: rectify promoted-view selections when the filter changes. Prefer
+    // the runtime-supplied snapshot — which preserves the cursor on the same
+    // item when it's still in the filtered list and only snaps to result[0]
+    // when the previously-selected item dropped out. Falls back to the older
+    // "snap to 0" behavior when no snapshot was provided (test paths,
+    // dispatchers without context).
+    const filterChanged = state.filter !== filter;
+    const branchIndex = promotedSelections?.branchIndex ??
+        (filterChanged ? 0 : state.selectedBranchIndex);
+    const tagIndex = promotedSelections?.tagIndex ??
+        (filterChanged ? 0 : state.selectedTagIndex);
+    const stashIndex = promotedSelections?.stashIndex ??
+        (filterChanged ? 0 : state.selectedStashIndex);
     return {
         ...state,
         filter,
         filteredCommits,
         selectedIndex: clampIndex$1(state.selectedIndex, filteredCommits.length),
         selectedFileIndex: 0,
+        selectedBranchIndex: branchIndex,
+        selectedTagIndex: tagIndex,
+        selectedStashIndex: stashIndex,
         diffPreviewOffset: 0,
         pendingKey: undefined,
     };
@@ -15343,11 +17126,11 @@ function nextHunkOffset(currentOffset, hunkOffsets, delta) {
         return currentOffset;
     }
     if (delta > 0) {
-        return hunkOffsets.find((offset) => offset > currentOffset) ||
-            hunkOffsets[hunkOffsets.length - 1];
+        const nextOffset = hunkOffsets.find((offset) => offset > currentOffset);
+        return nextOffset === undefined ? currentOffset : nextOffset;
     }
-    return [...hunkOffsets].reverse().find((offset) => offset < currentOffset) ||
-        hunkOffsets[0];
+    const previousOffset = [...hunkOffsets].reverse().find((offset) => offset < currentOffset);
+    return previousOffset === undefined ? currentOffset : previousOffset;
 }
 function nextHunkIndex(currentOffset, hunkOffsets, delta) {
     const offset = nextHunkOffset(currentOffset, hunkOffsets, delta);
@@ -15372,6 +17155,8 @@ function createLogInkState(rows, options = {}) {
         selectedBranchIndex: 0,
         selectedTagIndex: 0,
         selectedStashIndex: 0,
+        branchSort: DEFAULT_BRANCH_SORT_MODE,
+        tagSort: DEFAULT_TAG_SORT_MODE,
         paletteFilter: '',
         paletteSelectedIndex: 0,
         paletteRecent: [],
@@ -15392,6 +17177,12 @@ function createLogInkState(rows, options = {}) {
     };
 }
 function getSelectedInkCommit(state) {
+    if (state.pendingCommitFocused) {
+        // The cursor is on the synthetic "(+) new commit" row, not a real
+        // commit; callers (detail loaders, diff intents) should treat this as
+        // "no commit selected" and route to the worktree summary instead.
+        return undefined;
+    }
     return state.filteredCommits[state.selectedIndex];
 }
 function applyLogInkAction(state, action) {
@@ -15399,14 +17190,18 @@ function applyLogInkAction(state, action) {
         case 'appendRows':
             return appendRows(state, action.rows);
         case 'appendFilter':
-            return withFilter$1(state, `${state.filter}${action.value}`);
+            return withFilter$1(state, `${state.filter}${action.value}`, action.promotedSelections);
         case 'backspaceFilter':
-            return withFilter$1(state, state.filter.slice(0, -1));
+            return withFilter$1(state, state.filter.slice(0, -1), action.promotedSelections);
         case 'clearFilter':
             return withFilter$1({
                 ...state,
                 filterMode: false,
-            }, '');
+            }, '', action.promotedSelections);
+        case 'clearFilterText':
+            // Clears the filter input but stays in filterMode so the user can
+            // keep typing. P2.4 / P4.4: pairs with the two-stage Esc semantics.
+            return withFilter$1(state, '', action.promotedSelections);
         case 'commitCompose':
             return {
                 ...state,
@@ -15431,6 +17226,24 @@ function applyLogInkAction(state, action) {
                 selectedIndex: clampIndex$1(state.selectedIndex + action.delta, state.filteredCommits.length),
                 selectedFileIndex: 0,
                 diffPreviewOffset: 0,
+                pendingCommitFocused: false,
+                pendingKey: undefined,
+            };
+        case 'focusPendingCommit':
+            return {
+                ...state,
+                pendingCommitFocused: true,
+                selectedFileIndex: 0,
+                diffPreviewOffset: 0,
+                pendingKey: undefined,
+            };
+        case 'unfocusPendingCommit':
+            return {
+                ...state,
+                pendingCommitFocused: false,
+                selectedIndex: 0,
+                selectedFileIndex: 0,
+                diffPreviewOffset: 0,
                 pendingKey: undefined,
             };
         case 'moveDetailFile':
@@ -15467,12 +17280,29 @@ function applyLogInkAction(state, action) {
                 selectedStashIndex: clampIndex$1(state.selectedStashIndex + action.delta, action.count),
                 pendingKey: undefined,
             };
+        case 'cycleBranchSort':
+            return {
+                ...state,
+                branchSort: cycleBranchSort(state.branchSort),
+                // Snap to the top of the (newly ordered) list so the user always
+                // sees what's now most relevant under the new mode.
+                selectedBranchIndex: 0,
+                pendingKey: undefined,
+            };
+        case 'cycleTagSort':
+            return {
+                ...state,
+                tagSort: cycleTagSort(state.tagSort),
+                selectedTagIndex: 0,
+                pendingKey: undefined,
+            };
         case 'moveToBottom':
             return {
                 ...state,
                 selectedIndex: clampIndex$1(state.filteredCommits.length - 1, state.filteredCommits.length),
                 selectedFileIndex: 0,
                 diffPreviewOffset: 0,
+                pendingCommitFocused: false,
                 pendingKey: undefined,
             };
         case 'moveToTop':
@@ -15481,6 +17311,7 @@ function applyLogInkAction(state, action) {
                 selectedIndex: 0,
                 selectedFileIndex: 0,
                 diffPreviewOffset: 0,
+                pendingCommitFocused: false,
                 pendingKey: undefined,
             };
         case 'nextSidebarTab':
@@ -15516,6 +17347,12 @@ function applyLogInkAction(state, action) {
                 selectedWorktreeHunkIndex: nextHunkIndex(state.worktreeDiffOffset, action.hunkOffsets, action.delta),
                 pendingKey: undefined,
             };
+        case 'jumpCommitDiffHunk':
+            return {
+                ...state,
+                diffPreviewOffset: nextHunkOffset(state.diffPreviewOffset, action.hunkOffsets, action.delta),
+                pendingKey: undefined,
+            };
         case 'previousSidebarTab':
             return {
                 ...state,
@@ -15523,7 +17360,7 @@ function applyLogInkAction(state, action) {
                 pendingKey: undefined,
             };
         case 'setFilter':
-            return withFilter$1(state, action.value);
+            return withFilter$1(state, action.value, action.promotedSelections);
         case 'setActiveView':
             return withReplacedView(state, action.value);
         case 'pushView':
@@ -15542,6 +17379,7 @@ function applyLogInkAction(state, action) {
                 viewStack: [HOME_VIEW],
                 worktreeDiffOffset: 0,
                 selectedWorktreeHunkIndex: 0,
+                pendingCommitFocused: false,
                 pendingKey: undefined,
             };
         }
@@ -15553,8 +17391,9 @@ function applyLogInkAction(state, action) {
             return {
                 ...next,
                 selectedIndex: clampIndex$1(selectedIndex, filteredCommits.length),
-                selectedFileIndex: 0,
+                selectedFileIndex: Math.max(0, action.fileIndex ?? 0),
                 diffPreviewOffset: 0,
+                diffSource: 'commit',
             };
         }
         case 'navigateOpenDiffForWorktreeFile': {
@@ -15564,6 +17403,7 @@ function applyLogInkAction(state, action) {
                 selectedWorktreeFileIndex: Math.max(0, action.fileIndex),
                 selectedWorktreeHunkIndex: 0,
                 worktreeDiffOffset: 0,
+                diffSource: 'worktree',
             };
         }
         case 'navigateOpenComposeForFile': {
@@ -15776,7 +17616,7 @@ function formatCapturedAiOutput(output) {
 }
 async function runChangelogAction(argv) {
     try {
-        const output = await captureStdout(() => handler$6(argv, new Logger({
+        const output = await captureStdout(() => handler$7(argv, new Logger({
             verbose: true,
             silent: false,
         })));
@@ -17217,7 +19057,7 @@ function truncate$2(value, width) {
     }
     return `${value.slice(0, width - 3)}...`;
 }
-function formatChangedFile$1(file) {
+function formatChangedFile(file) {
     if (file.oldPath) {
         return `${file.status}  ${file.oldPath} -> ${file.path}`;
     }
@@ -17245,7 +19085,7 @@ function renderCommitList(state, maxRows, width) {
         return truncate$2(row, width);
     });
 }
-function formatDivergence$1(branch) {
+function formatDivergence(branch) {
     if (!branch.upstream) {
         return 'no upstream';
     }
@@ -17273,7 +19113,7 @@ function renderBranchOverview(overview, ui, width) {
         .map((branch) => {
         const marker = branch.current ? '*' : ' ';
         const selected = isBranchFocused && selectedBranches[ui.branchIndex || 0] === branch ? '>' : ' ';
-        return `${selected}${marker} ${branch.shortName} ${formatDivergence$1(branch)}`;
+        return `${selected}${marker} ${branch.shortName} ${formatDivergence(branch)}`;
     });
     const remoteBranches = overview.remoteBranches.slice(0, 6).map((branch) => {
         const selected = isBranchFocused && selectedBranches[ui.branchIndex || 0] === branch ? '>' : ' ';
@@ -17287,7 +19127,7 @@ function renderBranchOverview(overview, ui, width) {
         : [];
     return [
         `Branches: ${overview.currentBranch || '<detached>'} | ${dirty}`,
-        current ? `Upstream: ${formatDivergence$1(current)}` : 'Upstream: none',
+        current ? `Upstream: ${formatDivergence(current)}` : 'Upstream: none',
         ui.pendingDeleteBranch
             ? `Pending delete: press D to delete ${ui.pendingDeleteBranch}`
             : 'Branch actions: tab focus | enter checkout/track | f fetch | p push | P pull | d delete',
@@ -17540,7 +19380,7 @@ function renderDetail(detail, width) {
     const refs = detail.refs.length ? ` (${detail.refs.join(', ')})` : '';
     const body = detail.body ? ['', ...detail.body.split('\n').map((line) => `  ${line}`)] : [];
     const files = detail.files.length
-        ? detail.files.slice(0, 12).map((file) => `  ${formatChangedFile$1(file)}`)
+        ? detail.files.slice(0, 12).map((file) => `  ${formatChangedFile(file)}`)
         : ['  No changed files found.'];
     const hiddenFiles = detail.files.length > 12
         ? [`  ... ${detail.files.length - 12} more file(s)`]
@@ -18894,18 +20734,6 @@ const truncate$1 = truncateCells;
 function compactHash(hash) {
     return hash ? hash.slice(0, 7) : '<none>';
 }
-function formatChangedFile(file) {
-    const stats = file.binary
-        ? 'bin'
-        : file.additions !== undefined || file.deletions !== undefined
-            ? `+${file.additions || 0}/-${file.deletions || 0}`
-            : '';
-    const suffix = stats ? ` ${stats}` : '';
-    if (file.oldPath) {
-        return `${file.status} ${file.oldPath} -> ${file.path}${suffix}`;
-    }
-    return `${file.status} ${file.path}${suffix}`;
-}
 async function safe(promise) {
     try {
         return await promise;
@@ -18991,6 +20819,70 @@ function focusBorderColor(theme, focused) {
 function panelTitle(title, focused) {
     return focused ? `${title} *` : title;
 }
+/**
+ * Map a unified-diff line to the props passed to an Ink `<Text>` so the
+ * standard +/-/@@ prefixes render in their conventional colors. File
+ * headers (`+++`, `---`, `diff --git`, `index`) get a softer treatment so
+ * they don't compete with the actual hunk content.
+ *
+ * `theme.noColor` collapses everything to dim/normal so we stay readable
+ * under `NO_COLOR` and the `monochrome` preset.
+ */
+function diffLineProps(line, theme) {
+    if (theme.noColor) {
+        return { dimColor: line.startsWith(' ') || line.startsWith('diff ') || line.startsWith('index ') };
+    }
+    if (line.startsWith('diff ') || line.startsWith('index ') || line.startsWith('+++') || line.startsWith('---')) {
+        return { dimColor: true };
+    }
+    if (line.startsWith('@@')) {
+        return { color: theme.colors.accent };
+    }
+    if (line.startsWith('+')) {
+        return { color: theme.colors.gitAdded };
+    }
+    if (line.startsWith('-')) {
+        return { color: theme.colors.gitDeleted };
+    }
+    return {};
+}
+/**
+ * Pick a theme color for a single name-status code (`A`, `M`, `D`,
+ * `R100`, etc.) so the inspector and commit-diff file list render with
+ * familiar git colors at a glance. Letters stay in the line so the
+ * meaning survives `NO_COLOR`.
+ */
+function statusCodeColor(status, theme) {
+    if (theme.noColor) {
+        return undefined;
+    }
+    const head = status.charAt(0);
+    switch (head) {
+        case 'A':
+            return theme.colors.gitAdded;
+        case 'D':
+            return theme.colors.gitDeleted;
+        case 'U':
+            return theme.colors.danger;
+        case 'M':
+        case 'T':
+            return theme.colors.gitModified;
+        case 'R':
+        case 'C':
+            return theme.colors.accent;
+        default:
+            return undefined;
+    }
+}
+function formatChangedFileStats(file) {
+    if (file.binary) {
+        return 'bin';
+    }
+    if (file.additions === undefined && file.deletions === undefined) {
+        return '';
+    }
+    return `+${file.additions || 0}/-${file.deletions || 0}`;
+}
 function sidebarTabLabel(tab) {
     switch (tab) {
         case 'status':
@@ -19007,16 +20899,7 @@ function sidebarTabLabel(tab) {
             return tab;
     }
 }
-function formatDivergence(branch) {
-    if (!branch.upstream) {
-        return 'no upstream';
-    }
-    if (branch.ahead === 0 && branch.behind === 0) {
-        return `even with ${branch.upstream}`;
-    }
-    return `+${branch.ahead}/-${branch.behind} ${branch.upstream}`;
-}
-function sidebarLines(context, contextStatus, tab, width) {
+function sidebarLines(context, contextStatus, tab, width, state, theme) {
     if (tab === 'status') {
         const worktree = context.worktree;
         if (isLogInkContextKeyLoading(contextStatus, 'worktree')) {
@@ -19041,20 +20924,22 @@ function sidebarLines(context, contextStatus, tab, width) {
         if (!branches) {
             return ['Branches unavailable'];
         }
+        const sortedBranches = sortBranches(branches.localBranches, state.branchSort);
         return [
             `Current: ${branches.currentBranch || '<detached>'}`,
             branches.dirty ? 'Worktree: dirty' : 'Worktree: clean',
             '',
-            ...branches.localBranches.slice(0, 8).map((branch) => `${branch.current ? '*' : ' '} ${truncate$1(branch.shortName, width - 4)}`),
-            ...branches.localBranches.slice(0, 4).map((branch) => `  ${truncate$1(formatDivergence(branch), width - 2)}`),
+            ...sortedBranches.slice(0, 8).map((branch) => `${branchRowMarker(branch, { ascii: theme.ascii })} ${truncate$1(branch.shortName, width - 4)}`),
+            ...sortedBranches.slice(0, 4).map((branch) => `  ${truncate$1(formatBranchDivergence(branch, { ascii: theme.ascii }), width - 2)}`),
         ];
     }
     if (tab === 'tags') {
         if (isLogInkContextKeyLoading(contextStatus, 'tags')) {
             return ['Loading tags...'];
         }
-        return context.tags?.tags.length
-            ? context.tags.tags.slice(0, 12).map((tag) => `${truncate$1(tag.name, 16)} ${truncate$1(tag.subject, Math.max(8, width - 18))}`)
+        const sortedTags = sortTags(context.tags?.tags || [], state.tagSort);
+        return sortedTags.length
+            ? sortedTags.slice(0, 12).map((tag) => `${truncate$1(tag.name, 16)} ${truncate$1(tag.subject, Math.max(8, width - 18))}`)
             : ['No tags found'];
     }
     if (tab === 'stashes') {
@@ -19076,35 +20961,127 @@ function sidebarLines(context, contextStatus, tab, width) {
         })
         : ['No linked worktrees'];
 }
-async function startInkInteractiveLog(git, rows, streams = {}, options = {}) {
-    const input = streams.input || process.stdin;
-    const output = streams.output || process.stdout;
-    const error = streams.error || process.stderr;
-    if (!canStartLogInkTui(input, output)) {
-        await startInteractiveLog(git, rows, {
-            appLabel: options.appLabel,
-            input,
-            output,
-        });
-        return;
+async function startInkInteractiveLog(git, rows, streams = {}, options = {}) {
+    const input = streams.input || process.stdin;
+    const output = streams.output || process.stdout;
+    const error = streams.error || process.stderr;
+    if (!canStartLogInkTui(input, output)) {
+        await startInteractiveLog(git, rows, {
+            appLabel: options.appLabel,
+            input,
+            output,
+        });
+        return;
+    }
+    const runtime = await loadInkRuntime();
+    const { ink, React } = runtime;
+    // Forward declared so the lifecycle handler can call back into the React
+    // tree on SIGCONT to force a repaint after the user `fg`s.
+    const resumeRef = { current: null };
+    const app = React.createElement(LogInkApp, {
+        appLabel: options.appLabel || 'coco log',
+        git,
+        idleTipsEnabled: Boolean(options.idleTips),
+        ink,
+        initialView: options.initialView || 'history',
+        logArgv: options.logArgv,
+        React,
+        rows,
+        theme: createLogInkTheme(options.theme),
+        resumeRef,
+    });
+    const instance = ink.render(app, getLogInkRenderOptions({ input, output, error }));
+    const lifecycle = installTerminalLifecycle({
+        input,
+        output,
+        instance,
+        onResume: () => resumeRef.current?.(),
+    });
+    try {
+        await instance.waitUntilExit();
+    }
+    finally {
+        lifecycle.dispose();
+    }
+}
+/**
+ * Predict the filter value that a filter-mutating action would land on, so
+ * the runtime can compute the post-filter selection snapshot before the
+ * reducer ever runs (P4.5). Returns undefined when the action isn't a
+ * filter action.
+ */
+function predictNextFilter(action, currentFilter) {
+    switch (action.type) {
+        case 'appendFilter':
+            return `${currentFilter}${action.value}`;
+        case 'backspaceFilter':
+            return currentFilter.slice(0, -1);
+        case 'clearFilter':
+        case 'clearFilterText':
+            return '';
+        case 'setFilter':
+            return action.value;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Build the post-filter selection snapshot for branches / tags / stash so
+ * the reducer can preserve the cursor when the previously-selected item is
+ * still in the filtered result. Identifies items by a single key per view
+ * (branch shortName, tag name, stash ref) — the same matchesPromotedFilter
+ * the surfaces use covers the multi-field haystacks.
+ */
+function computePromotedSelectionsSnapshot(state, context, nextFilter) {
+    const allBranches = context.branches?.localBranches || [];
+    const filteredBranches = nextFilter
+        ? allBranches.filter((branch) => matchesPromotedFilter([branch.shortName, branch.upstream || ''], nextFilter))
+        : allBranches;
+    const currentBranches = state.filter
+        ? allBranches.filter((branch) => matchesPromotedFilter([branch.shortName, branch.upstream || ''], state.filter))
+        : allBranches;
+    const previousBranchKey = currentBranches[state.selectedBranchIndex]?.shortName;
+    const branchIndex = rectifyPromotedSelectionIndex(filteredBranches.map((branch) => branch.shortName), previousBranchKey);
+    const allTags = context.tags?.tags || [];
+    const filteredTags = nextFilter
+        ? allTags.filter((tag) => matchesPromotedFilter([tag.name, tag.subject], nextFilter))
+        : allTags;
+    const currentTags = state.filter
+        ? allTags.filter((tag) => matchesPromotedFilter([tag.name, tag.subject], state.filter))
+        : allTags;
+    const previousTagKey = currentTags[state.selectedTagIndex]?.name;
+    const tagIndex = rectifyPromotedSelectionIndex(filteredTags.map((tag) => tag.name), previousTagKey);
+    const allStashes = context.stashes?.stashes || [];
+    const filteredStashes = nextFilter
+        ? allStashes.filter((stash) => matchesPromotedFilter([stash.ref, stash.message], nextFilter))
+        : allStashes;
+    const currentStashes = state.filter
+        ? allStashes.filter((stash) => matchesPromotedFilter([stash.ref, stash.message], state.filter))
+        : allStashes;
+    const previousStashKey = currentStashes[state.selectedStashIndex]?.ref;
+    const stashIndex = rectifyPromotedSelectionIndex(filteredStashes.map((stash) => stash.ref), previousStashKey);
+    return { branchIndex, tagIndex, stashIndex };
+}
+function enrichFilterActionWithRectification(action, state, context) {
+    const nextFilter = predictNextFilter(action, state.filter);
+    if (nextFilter === undefined) {
+        return action;
+    }
+    const promotedSelections = computePromotedSelectionsSnapshot(state, context, nextFilter);
+    switch (action.type) {
+        case 'appendFilter':
+        case 'setFilter':
+            return { ...action, promotedSelections };
+        case 'backspaceFilter':
+        case 'clearFilter':
+        case 'clearFilterText':
+            return { ...action, promotedSelections };
+        default:
+            return action;
     }
-    const runtime = await loadInkRuntime();
-    const { ink, React } = runtime;
-    const app = React.createElement(LogInkApp, {
-        appLabel: options.appLabel || 'coco log',
-        git,
-        ink,
-        initialView: options.initialView || 'history',
-        logArgv: options.logArgv,
-        React,
-        rows,
-        theme: createLogInkTheme(options.theme),
-    });
-    const instance = ink.render(app, getLogInkRenderOptions({ input, output, error }));
-    await instance.waitUntilExit();
 }
 function LogInkApp(deps) {
-    const { appLabel, git, ink, initialView, logArgv, React, rows, theme } = deps;
+    const { appLabel, git, idleTipsEnabled, ink, initialView, logArgv, React, resumeRef, rows, theme } = deps;
     const { Box, Text, useApp, useInput, useWindowSize } = ink;
     const h = React.createElement;
     const { exit } = useApp();
@@ -19113,6 +21090,22 @@ function LogInkApp(deps) {
         columns: windowSize.columns || process.stdout.columns || LOG_INK_DEFAULT_COLUMNS,
         rows: windowSize.rows || process.stdout.rows || LOG_INK_DEFAULT_ROWS,
     });
+    // Bumping this on SIGCONT forces the existing tree to repaint so users
+    // land on a drawn screen after `fg` instead of an empty alt buffer.
+    const [, setResumeTick] = React.useState(0);
+    React.useEffect(() => {
+        if (!resumeRef) {
+            return;
+        }
+        resumeRef.current = () => setResumeTick((tick) => tick + 1);
+        return () => {
+            resumeRef.current = null;
+        };
+    }, [resumeRef]);
+    // First-launch onboarding (P1.3). Persisted via a marker file in the
+    // user's cache dir so the tip never reappears once dismissed. Lazy
+    // initializer so the fs check only runs on mount, not every render.
+    const [showOnboarding, setShowOnboarding] = React.useState(() => !hasSeenOnboarding());
     const [state, setState] = React.useState(() => createLogInkState(rows, { activeView: initialView }));
     const [context, setContext] = React.useState({});
     const [contextStatus, setContextStatus] = React.useState(() => createLogInkContextStatus('loading'));
@@ -19130,21 +21123,66 @@ function LogInkApp(deps) {
     const loadingMoreCommitsRef = React.useRef(false);
     const loadMoreRequestRef = React.useRef(0);
     const mountedRef = React.useRef(true);
+    // P4.3 — idle tip rotation. tickIndex 0 ⇒ no tip; the hook bumps it after
+    // a grace window of empty statusMessage and then on a steady cadence, so
+    // the footer surfaces a different hint every interval until the user does
+    // anything that sets statusMessage.
+    const [idleTipIndex, setIdleTipIndex] = React.useState(0);
+    React.useEffect(() => {
+        if (!idleTipsEnabled)
+            return;
+        if (state.statusMessage) {
+            // Any explicit message resets the cycle; next idle stretch starts
+            // from the grace window again.
+            setIdleTipIndex(0);
+            return;
+        }
+        let interval;
+        // Both timer callbacks are function literals (never strings) and the
+        // delays are our own `IDLE_TIPS_*_MS` constants — no caller-supplied
+        // data flows in, so the eval-injection vector that drives
+        // DevSkim DS172411 doesn't apply here.
+        // DevSkim: ignore DS172411
+        const grace = setTimeout(() => {
+            setIdleTipIndex(1);
+            // DevSkim: ignore DS172411
+            interval = setInterval(() => setIdleTipIndex((tick) => tick + 1), IDLE_TIPS_INTERVAL_MS);
+        }, IDLE_TIPS_GRACE_MS);
+        return () => {
+            clearTimeout(grace);
+            if (interval)
+                clearInterval(interval);
+        };
+    }, [idleTipsEnabled, state.statusMessage]);
+    const idleTip = idleTipsEnabled && !state.statusMessage ? pickIdleTip(idleTipIndex) : undefined;
     const selected = getSelectedInkCommit(state);
     const selectedDetailFile = detail?.files[state.selectedFileIndex];
     const selectedWorktreeFile = context.worktree?.files[state.selectedWorktreeFileIndex];
     const dispatch = React.useCallback((action) => {
         setState((current) => applyLogInkAction(current, action));
     }, []);
-    const refreshContext = React.useCallback(async () => {
-        dispatch({ type: 'setStatus', value: 'refreshing repository context' });
-        setContextStatus(createLogInkContextStatus('loading'));
-        setContext(await loadLogInkContext(git));
+    const refreshContext = React.useCallback(async (options = {}) => {
+        // Loud refresh (manual `r`): flip everything to 'loading' so the user
+        // sees the surfaces clear, then settle to 'ready' on completion.
+        // Silent refresh (fs.watch trigger): keep the existing data on screen
+        // (stale-while-revalidate) and quietly swap it in once the new fetch
+        // resolves — avoids the every-second flicker the watcher would
+        // otherwise produce on busy repos.
+        if (!options.silent) {
+            dispatch({ type: 'setStatus', value: 'refreshing repository context' });
+            setContextStatus(createLogInkContextStatus('loading'));
+        }
+        const next = await loadLogInkContext(git);
+        setContext(next);
         setContextStatus(createLogInkContextStatus('ready'));
-        dispatch({ type: 'setStatus', value: 'repository context refreshed' });
+        if (!options.silent) {
+            dispatch({ type: 'setStatus', value: 'repository context refreshed' });
+        }
     }, [dispatch, git]);
-    const refreshWorktreeContext = React.useCallback(async () => {
-        setContextStatus((current) => updateLogInkContextStatus(current, 'worktree', 'loading'));
+    const refreshWorktreeContext = React.useCallback(async (options = {}) => {
+        if (!options.silent) {
+            setContextStatus((current) => updateLogInkContextStatus(current, 'worktree', 'loading'));
+        }
         const worktree = await safe(getWorktreeOverview(git));
         setContext((current) => ({
             ...current,
@@ -19152,6 +21190,56 @@ function LogInkApp(deps) {
         }));
         setContextStatus((current) => updateLogInkContextStatus(current, 'worktree', 'ready'));
     }, [git]);
+    // Live refresh: watch .git metadata + the working tree root and reload
+    // context when something changes outside the TUI (editor save, external
+    // git commands, branch switch in another terminal). Best-effort — the
+    // watcher quietly skips paths that don't exist or platforms where
+    // fs.watch fails. Subdirectory unstaged edits don't fire; users can
+    // press `r` for those.
+    React.useEffect(() => {
+        let cancelled = false;
+        let watcher = null;
+        void (async () => {
+            try {
+                const [repoRoot, gitDir] = await Promise.all([
+                    git.revparse(['--show-toplevel']),
+                    git.revparse(['--absolute-git-dir']),
+                ]);
+                if (cancelled) {
+                    return;
+                }
+                watcher = createRefreshWatcher({
+                    repoRoot: repoRoot.trim(),
+                    gitDir: gitDir.trim(),
+                    // Editor saves and git background processes can produce a steady
+                    // drip of fs events on busy repos. The default 250ms debounce
+                    // was tight enough that the watcher fired ~once per second; 750
+                    // batches the steady-state better without delaying the user's
+                    // perception of an actual change.
+                    debounceMs: 750,
+                    onChange: (kind) => {
+                        if (!mountedRef.current) {
+                            return;
+                        }
+                        if (kind === 'full') {
+                            void refreshContext({ silent: true });
+                        }
+                        else {
+                            void refreshWorktreeContext({ silent: true });
+                        }
+                    },
+                });
+            }
+            catch {
+                // Not in a git worktree, or revparse failed. Skip — manual `r`
+                // refresh still works.
+            }
+        })();
+        return () => {
+            cancelled = true;
+            watcher?.close();
+        };
+    }, [git, refreshContext, refreshWorktreeContext]);
     React.useEffect(() => {
         let active = true;
         async function loadWorktreeHunks() {
@@ -19362,6 +21450,72 @@ function LogInkApp(deps) {
         });
         dispatch({ type: 'setStatus', value: result.message });
     }, [dispatch]);
+    // Resolve the destructive-action target from the live filtered+sorted
+    // list the user is looking at, run the action against it, surface the
+    // result on the status line, and silently refresh so the deleted item
+    // disappears. Called from the y-confirm path for delete-branch / delete-
+    // tag / drop-stash / remove-worktree / abort-operation.
+    const runWorkflowAction = React.useCallback(async (id) => {
+        const handlers = {
+            'delete-branch': async () => {
+                const all = sortBranches(context.branches?.localBranches || [], state.branchSort);
+                const visible = state.filter
+                    ? all.filter((b) => matchesPromotedFilter([b.shortName, b.upstream || ''], state.filter))
+                    : all;
+                const branch = visible[Math.min(state.selectedBranchIndex, visible.length - 1)];
+                if (!branch)
+                    return { ok: false, message: 'No branch selected' };
+                return deleteBranch(git, branch);
+            },
+            'delete-tag': async () => {
+                const all = sortTags(context.tags?.tags || [], state.tagSort);
+                const visible = state.filter
+                    ? all.filter((t) => matchesPromotedFilter([t.name, t.subject], state.filter))
+                    : all;
+                const tag = visible[Math.min(state.selectedTagIndex, visible.length - 1)];
+                if (!tag)
+                    return { ok: false, message: 'No tag selected' };
+                return deleteLocalTag(git, tag.name);
+            },
+            'drop-stash': async () => {
+                const all = context.stashes?.stashes || [];
+                const visible = state.filter
+                    ? all.filter((s) => matchesPromotedFilter([s.ref, s.message], state.filter))
+                    : all;
+                const stash = visible[Math.min(state.selectedStashIndex, visible.length - 1)];
+                if (!stash)
+                    return { ok: false, message: 'No stash selected' };
+                return dropStash(git, stash);
+            },
+            'remove-worktree': async () => {
+                const all = context.worktreeList?.worktrees || [];
+                // No dedicated cursor for the worktrees tab yet — operate on the
+                // first non-current worktree as a safe default.
+                const target = all.find((w) => !w.current);
+                if (!target)
+                    return { ok: false, message: 'No removable worktree' };
+                return removeWorktree(git, target);
+            },
+            'abort-operation': async () => {
+                const operation = context.operation?.operation;
+                if (!operation) {
+                    return { ok: false, message: 'No git operation in progress' };
+                }
+                return abortOperation(git, operation);
+            },
+        };
+        const handler = handlers[id];
+        if (!handler) {
+            dispatch({ type: 'setStatus', value: `Workflow action ${id} not yet wired` });
+            return;
+        }
+        const result = await handler();
+        dispatch({ type: 'setStatus', value: result?.message || 'Workflow action complete' });
+        // Silent refresh so the deleted item disappears from the list without
+        // flickering the surfaces through a 'loading' phase.
+        await refreshContext({ silent: true });
+    }, [context, dispatch, git, refreshContext, state.branchSort, state.filter, state.selectedBranchIndex,
+        state.selectedStashIndex, state.selectedTagIndex, state.tagSort]);
     React.useEffect(() => {
         let active = true;
         async function loadPreview() {
@@ -19439,16 +21593,50 @@ function LogInkApp(deps) {
         state.filteredCommits.length,
         state.selectedIndex,
     ]);
+    const commitDiffHunkOffsets = React.useMemo(() => (filePreview?.hunks
+        .map((line, index) => (line.startsWith('@@') ? index : -1))
+        .filter((index) => index >= 0)), [filePreview]);
+    const worktreeDirty = Boolean(context.worktree &&
+        (context.worktree.stagedCount + context.worktree.unstagedCount + context.worktree.untrackedCount) > 0);
     useInput((inputValue, key) => {
+        // First-launch onboarding (P1.3): any keystroke dismisses the overlay
+        // and writes the seen-marker. Swallow the keystroke so the same key
+        // doesn't also trigger normal input dispatch.
+        if (showOnboarding) {
+            setShowOnboarding(false);
+            markOnboardingSeen();
+            return;
+        }
+        // P4.5: navigation in branches/tags/stash uses the FILTERED list
+        // length when a filter is active so j/k stay live instead of getting
+        // stuck against a full-list count that no longer matches what's on
+        // screen.
+        const branchVisibleCount = state.filter
+            ? (context.branches?.localBranches || [])
+                .filter((branch) => matchesPromotedFilter([branch.shortName, branch.upstream || ''], state.filter))
+                .length
+            : context.branches?.localBranches.length;
+        const tagVisibleCount = state.filter
+            ? (context.tags?.tags || [])
+                .filter((tag) => matchesPromotedFilter([tag.name, tag.subject], state.filter))
+                .length
+            : context.tags?.tags.length;
+        const stashVisibleCount = state.filter
+            ? (context.stashes?.stashes || [])
+                .filter((stash) => matchesPromotedFilter([stash.ref, stash.message], state.filter))
+                .length
+            : context.stashes?.stashes.length;
         getLogInkInputEvents(state, inputValue, key, {
             detailFileCount: detail?.files.length,
             previewLineCount: filePreview?.hunks.length,
             worktreeDiffLineCount: worktreeDiff?.lines.length,
             worktreeFileCount: context.worktree?.files.length,
             worktreeHunkOffsets: worktreeDiff?.hunkOffsets,
-            branchCount: context.branches?.localBranches.length,
-            tagCount: context.tags?.tags.length,
-            stashCount: context.stashes?.stashes.length,
+            commitDiffHunkOffsets,
+            branchCount: branchVisibleCount,
+            tagCount: tagVisibleCount,
+            stashCount: stashVisibleCount,
+            worktreeDirty,
         }).forEach((event) => {
             if (event.type === 'exit') {
                 exit();
@@ -19474,8 +21662,18 @@ function LogInkApp(deps) {
             else if (event.type === 'runAiCommitDraft') {
                 void runAiCommitDraft();
             }
+            else if (event.type === 'runWorkflowAction') {
+                void runWorkflowAction(event.id);
+            }
             else {
-                dispatch(event.action);
+                // P4.5: enrich filter-mutating actions with a precomputed
+                // selection snapshot so the reducer can preserve the cursor on
+                // the same item when it's still in the filtered result, only
+                // snapping to result[0] when the previously selected item drops
+                // out. The snapshot lives in the action so the reducer never
+                // needs context items.
+                const enriched = enrichFilterActionWithRectification(event.action, state, context);
+                dispatch(enriched);
             }
         });
     });
@@ -19487,7 +21685,12 @@ function LogInkApp(deps) {
             paddingY: 1,
         }, h(Text, { bold: true }, appLabel), h(Text, undefined, `Terminal too small: ${layout.columns}x${layout.rows}`), h(Text, { dimColor: true }, `Minimum size is ${LOG_INK_MIN_COLUMNS}x${LOG_INK_MIN_ROWS}.`), h(Text, { dimColor: true }, 'Resize the terminal or run plain coco log.'));
     }
-    return h(Box, { flexDirection: 'column', height: layout.rows }, renderHeader(h, { Box, Text }, state, context, contextStatus, layout.columns, theme, appLabel), h(Box, { flexDirection: 'row', height: layout.bodyRows }, renderSidebar(h, { Box, Text }, state, context, contextStatus, layout.sidebarWidth, theme), renderMainPanel(h, { Box, Text }, state, context, contextStatus, worktreeDiff, worktreeDiffLoading, worktreeHunks, worktreeHunksLoading, layout.bodyRows, theme, hasMoreCommits, loadingMoreCommits), renderDetailPanel(h, { Box, Text }, state, context, contextStatus, detail, detailLoading, filePreview, filePreviewLoading, layout.detailWidth, theme)), renderFooter(h, { Box, Text }, state, theme));
+    // First-launch onboarding overlay (P1.3) replaces the entire UI for
+    // one render — any keystroke dismisses it and persists the seen-marker.
+    if (showOnboarding) {
+        return renderOnboardingOverlay(h, { Box, Text }, layout.rows, layout.columns, theme, appLabel);
+    }
+    return h(Box, { flexDirection: 'column', height: layout.rows }, renderHeader(h, { Box, Text }, state, context, contextStatus, layout.columns, theme, appLabel), h(Box, { flexDirection: 'row', height: layout.bodyRows }, renderSidebar(h, { Box, Text }, state, context, contextStatus, layout.sidebarWidth, theme), renderMainPanel(h, { Box, Text }, state, context, contextStatus, worktreeDiff, worktreeDiffLoading, worktreeHunks, worktreeHunksLoading, filePreview, filePreviewLoading, commitDiffHunkOffsets, selectedDetailFile, layout.bodyRows, layout.mainPanelWidth, theme, hasMoreCommits, loadingMoreCommits), renderDetailPanel(h, { Box, Text }, state, context, contextStatus, detail, detailLoading, filePreview, filePreviewLoading, layout.detailWidth, theme)), renderFooter(h, { Box, Text }, state, theme, idleTip));
 }
 function renderHeader(h, components, state, context, contextStatus, columns, theme, appLabel) {
     const { Box, Text } = components;
@@ -19496,27 +21699,54 @@ function renderHeader(h, components, state, context, contextStatus, columns, the
     const repo = context.provider?.repository.owner && context.provider.repository.name
         ? `${context.provider.repository.owner}/${context.provider.repository.name}`
         : 'local repository';
-    const pr = context.provider?.currentPullRequest
-        ? `PR #${context.provider.currentPullRequest.number} ${context.provider.currentPullRequest.state}`
-        : context.pullRequest?.currentPullRequest
-            ? `PR #${context.pullRequest.currentPullRequest.number} ${context.pullRequest.currentPullRequest.state}`
-            : 'no PR';
+    const prInfo = context.provider?.currentPullRequest || context.pullRequest?.currentPullRequest;
+    const prGlyph = prInfo ? getPullRequestStateGlyph(prInfo, theme) : null;
+    const prLabel = prInfo
+        ? `PR #${prInfo.number} ${prInfo.isDraft ? 'DRAFT' : prInfo.state}`
+        : 'no PR';
     const search = state.filterMode ? `search: ${state.filter}_` : state.filter ? `filter: ${state.filter}` : '';
     const loading = isLogInkContextLoading(contextStatus) ? '  loading context' : '';
     const breadcrumb = formatLogInkBreadcrumb(state.viewStack);
     const view = breadcrumb ? `  ${breadcrumb}` : '';
-    const title = truncate$1(`${appLabel}  ${repo}  ${branch}  ${dirty}  ${pr}${view}${loading}`, columns - 2);
+    // Mode indicator (P2.2) — surfaces the current input mode so users
+    // never wonder why `q` doesn't quit while they're editing or filtering.
+    const mode = state.commitCompose.editing
+        ? '[EDIT]'
+        : state.filterMode
+            ? '[FILTER]'
+            : '[NORMAL]';
+    const titlePrefix = `${appLabel}  ${repo}  ${branch}  ${dirty}  `;
+    const glyphPart = prGlyph?.glyph ? `${prGlyph.glyph} ` : '';
+    const titleSuffix = `${view}${loading}`;
+    const fullTitle = `${titlePrefix}${glyphPart}${prLabel}${titleSuffix}`;
+    const titleBudget = columns - mode.length - 4;
+    const truncatedTitle = truncate$1(fullTitle, titleBudget);
+    // Only split into colored fragments when the prefix + glyph + label all
+    // fit unmodified — otherwise the truncate ellipsis can land mid-fragment
+    // and we'd render half a glyph in the wrong color.
+    const splitFragments = truncatedTitle === fullTitle && glyphPart.length > 0;
+    const modeColor = theme.noColor
+        ? undefined
+        : state.filterMode || state.commitCompose.editing
+            ? theme.colors.warning
+            : theme.colors.accent;
     return h(Box, {
         borderColor: theme.colors.border,
         borderStyle: theme.borderStyle,
         height: 3,
         paddingX: 1,
-    }, h(Text, { bold: true, color: theme.colors.accent }, title), search ? h(Text, { dimColor: true }, `  ${truncate$1(search, 36)}`) : undefined);
+    }, splitFragments
+        ? h(Text, { bold: true, color: theme.colors.accent }, titlePrefix)
+        : h(Text, { bold: true, color: theme.colors.accent }, truncatedTitle), splitFragments
+        ? h(Text, { bold: true, color: prGlyph?.color, dimColor: prGlyph?.dim }, glyphPart)
+        : undefined, splitFragments
+        ? h(Text, { bold: true, color: theme.colors.accent }, `${prLabel}${titleSuffix}`)
+        : undefined, h(Text, { bold: true, color: modeColor }, `  ${mode}`), search ? h(Text, { dimColor: true }, `  ${truncate$1(search, 36)}`) : undefined);
 }
 function renderSidebar(h, components, state, context, contextStatus, width, theme) {
     const { Box, Text } = components;
     const focused = state.focus === 'sidebar';
-    const lines = sidebarLines(context, contextStatus, state.sidebarTab, width - 4);
+    const lines = sidebarLines(context, contextStatus, state.sidebarTab, width - 4, state, theme);
     const tabs = getLogInkSidebarTabs();
     return h(Box, {
         borderColor: focusBorderColor(theme, focused),
@@ -19524,33 +21754,48 @@ function renderSidebar(h, components, state, context, contextStatus, width, them
         flexDirection: 'column',
         width,
         paddingX: 1,
-    }, h(Text, { bold: true }, panelTitle('Repository', focused)), h(Text, { dimColor: true }, tabs.map((tab) => tab === state.sidebarTab ? `[${sidebarTabLabel(tab)}]` : sidebarTabLabel(tab)).join(' ')), h(Text, undefined, ''), ...lines.map((line, index) => h(Text, { key: `sidebar-${index}` }, truncate$1(line, width - 4))));
-}
-function renderMainPanel(h, components, state, context, contextStatus, worktreeDiff, worktreeDiffLoading, worktreeHunks, worktreeHunksLoading, bodyRows, theme, hasMoreCommits, loadingMoreCommits) {
+    }, h(Text, { bold: true }, panelTitle('Repository', focused)), h(Text, { dimColor: true }, tabs.map((tab) => {
+        const count = sidebarTabCount(tab, context);
+        const labelWithCount = count !== undefined
+            ? `${sidebarTabLabel(tab)} (${count})`
+            : sidebarTabLabel(tab);
+        return tab === state.sidebarTab ? `[${labelWithCount}]` : labelWithCount;
+    }).join(' ')), h(Text, undefined, ''), ...lines.map((line, index) => h(Text, { key: `sidebar-${index}` }, truncate$1(line, width - 4))));
+}
+function renderMainPanel(h, components, state, context, contextStatus, worktreeDiff, worktreeDiffLoading, worktreeHunks, worktreeHunksLoading, filePreview, filePreviewLoading, commitDiffHunkOffsets, selectedDetailFile, bodyRows, width, theme, hasMoreCommits, loadingMoreCommits) {
     if (state.activeView === 'status') {
-        return renderStatusSurface(h, components, state, context, contextStatus, bodyRows, theme);
+        return renderStatusSurface(h, components, state, context, contextStatus, bodyRows, width, theme);
     }
     if (state.activeView === 'diff') {
-        return renderDiffSurface(h, components, state, context, contextStatus, worktreeDiff, worktreeDiffLoading, worktreeHunks, worktreeHunksLoading, bodyRows, theme);
+        return renderDiffSurface(h, components, state, context, contextStatus, worktreeDiff, worktreeDiffLoading, worktreeHunks, worktreeHunksLoading, filePreview, filePreviewLoading, commitDiffHunkOffsets, selectedDetailFile, bodyRows, width, theme);
     }
     if (state.activeView === 'compose') {
-        return renderComposeSurface(h, components, state, context, contextStatus, bodyRows, theme);
+        return renderComposeSurface(h, components, state, context, contextStatus, bodyRows, width, theme);
     }
     if (state.activeView === 'branches') {
-        return renderBranchesSurface(h, components, state, context, contextStatus, bodyRows, theme);
+        return renderBranchesSurface(h, components, state, context, contextStatus, bodyRows, width, theme);
     }
     if (state.activeView === 'tags') {
-        return renderTagsSurface(h, components, state, context, contextStatus, bodyRows, theme);
+        return renderTagsSurface(h, components, state, context, contextStatus, bodyRows, width, theme);
     }
     if (state.activeView === 'stash') {
-        return renderStashSurface(h, components, state, context, contextStatus, bodyRows, theme);
+        return renderStashSurface(h, components, state, context, contextStatus, bodyRows, width, theme);
     }
-    return renderHistoryPanel(h, components, state, bodyRows, theme, hasMoreCommits, loadingMoreCommits);
+    return renderHistoryPanel(h, components, state, context, bodyRows, width, theme, hasMoreCommits, loadingMoreCommits);
 }
-function renderHistoryPanel(h, components, state, bodyRows, theme, hasMoreCommits, loadingMoreCommits) {
+function renderHistoryPanel(h, components, state, context, bodyRows, width, theme, hasMoreCommits, loadingMoreCommits) {
     const { Box, Text } = components;
     const focused = state.focus === 'commits';
-    const listRows = Math.max(3, bodyRows - 4);
+    const worktree = context.worktree;
+    const worktreeDirty = Boolean(worktree && (worktree.stagedCount + worktree.unstagedCount + worktree.untrackedCount) > 0);
+    // The synthetic "(+) new commit" row only appears when the worktree is
+    // dirty AND the visible window is anchored at the top of the list — i.e.
+    // the first real commit (selectedIndex 0) is in view. Scroll past that
+    // and the row slides off naturally; the user can `gg` to bring it back.
+    const showPendingRow = worktreeDirty &&
+        !state.filter &&
+        state.selectedIndex === 0;
+    const listRows = Math.max(3, bodyRows - (showPendingRow ? 5 : 4));
     const visible = getVisibleLogInkHistory(state, listRows);
     const loadState = loadingMoreCommits
         ? 'loading older commits'
@@ -19559,13 +21804,21 @@ function renderHistoryPanel(h, components, state, bodyRows, theme, hasMoreCommit
             : 'loaded';
     const title = `${state.filteredCommits.length}/${state.commits.length} commits`;
     const graphMode = state.fullGraph ? 'full graph' : 'compact graph';
+    const pendingRowSelected = showPendingRow && Boolean(state.pendingCommitFocused) && focused;
+    // Real-commit selection is suppressed while the cursor is on the pending
+    // row so the visible cursor only renders in one place at a time.
+    const realSelectionSuppressed = state.pendingCommitFocused;
+    const pendingNode = showPendingRow
+        ? renderPendingCommitRow(h, Text, worktree, pendingRowSelected, theme)
+        : null;
     return h(Box, {
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
         flexDirection: 'column',
-        flexGrow: 1,
+        flexShrink: 0,
         paddingX: 1,
-    }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Commits', focused)), h(Text, { dimColor: true }, `${title} | ${graphMode} | ${loadState}`)), visible.items.length === 0
+        width,
+    }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Commits', focused)), h(Text, { dimColor: true }, `${title} | ${graphMode} | ${loadState}`)), ...(pendingNode ? [pendingNode] : []), visible.items.length === 0
         ? h(Text, { dimColor: true }, formatLogInkHistoryEmpty({
             filter: state.filter,
             totalCommits: state.commits.length,
@@ -19574,36 +21827,97 @@ function renderHistoryPanel(h, components, state, bodyRows, theme, hasMoreCommit
             if (item.type === 'graph') {
                 return h(Text, {
                     key: `graph-${index}-${item.graph}`,
-                    dimColor: true,
-                }, truncate$1(item.graph.padEnd(visible.graphWidth), 140));
+                    color: theme.noColor ? undefined : theme.colors.muted,
+                    dimColor: theme.noColor,
+                }, truncate$1(substituteGraphChars(item.graph.padEnd(visible.graphWidth), { ascii: theme.ascii }), 140));
             }
-            const { commit, selected } = item;
-            const graph = item.graph.padEnd(visible.graphWidth);
-            const row = `${graph} ${commit.shortHash} ${commit.date} ${commit.message}${formatInkRefLabels(commit.refs)}`;
-            return h(Text, {
-                key: `${commit.hash}-${index}`,
-                backgroundColor: selected && !theme.noColor ? theme.colors.selection : undefined,
-                inverse: selected,
-            }, truncate$1(row, 140));
+            return renderCommitHistoryRow(h, Text, item.commit, item.graph, visible.graphWidth, Boolean(item.selected) && !realSelectionSuppressed, theme, index);
         }));
 }
-function renderStatusSurface(h, components, state, context, contextStatus, bodyRows, theme) {
+/**
+ * Render a single commit row with each segment in its own colored span.
+ * Graph chars render in `theme.colors.muted` so the topology visually
+ * recedes; shortHash takes the accent so the eye lands on the commit
+ * identifier first; date is dimmed; message is normal; ref labels
+ * (`[HEAD -> main]`) trail in accent. Selection styling is applied at
+ * the outer span via `backgroundColor` / `inverse` so the highlight
+ * fills the whole row regardless of inner-span coloring.
+ *
+ * Truncation is per-segment so the variable-length message field gets
+ * the leftover budget after fixed segments are accounted for.
+ */
+function renderCommitHistoryRow(h, Text, commit, graph, graphWidth, selected, theme, index) {
+    const renderedGraph = substituteGraphChars(graph.padEnd(graphWidth), { ascii: theme.ascii });
+    const refs = formatInkRefLabels(commit.refs);
+    const totalWidth = 140;
+    const fixedWidth = graphWidth + 1 + commit.shortHash.length + 1 + commit.date.length + 1;
+    const messageRoom = Math.max(8, totalWidth - fixedWidth - cellWidth(refs));
+    const message = truncate$1(commit.message, messageRoom);
+    const selectedBg = selected && !theme.noColor ? theme.colors.selection : undefined;
+    const accent = theme.noColor ? undefined : theme.colors.accent;
+    const muted = theme.noColor ? undefined : theme.colors.muted;
+    return h(Text, {
+        key: `${commit.hash}-${index}`,
+        backgroundColor: selectedBg,
+        inverse: selected,
+    }, h(Text, { color: muted, dimColor: theme.noColor }, renderedGraph), ' ', h(Text, { color: accent, bold: selected }, commit.shortHash), ' ', h(Text, { dimColor: true }, commit.date), ' ', h(Text, undefined, message), refs ? h(Text, { color: accent }, refs) : null);
+}
+/**
+ * Render the synthetic "(+) new commit" affordance shown above the real
+ * commit list when the worktree is dirty. Pressing up at `selectedIndex 0`
+ * focuses this row; pressing Enter pushes the status view so the user can
+ * stage / commit.
+ */
+function renderPendingCommitRow(h, Text, worktree, selected, theme) {
+    const parts = [];
+    if (worktree.stagedCount) {
+        parts.push(`${worktree.stagedCount} staged`);
+    }
+    if (worktree.unstagedCount) {
+        parts.push(`${worktree.unstagedCount} unstaged`);
+    }
+    if (worktree.untrackedCount) {
+        parts.push(`${worktree.untrackedCount} untracked`);
+    }
+    const summary = parts.length ? parts.join(' · ') : 'pending changes';
+    const label = `${theme.ascii ? '[+]' : '(+)'} New commit · ${summary}`;
+    return h(Text, {
+        key: 'pending-commit-row',
+        bold: true,
+        color: theme.noColor ? undefined : theme.colors.accent,
+        inverse: selected,
+        backgroundColor: selected && !theme.noColor ? theme.colors.selection : undefined,
+    }, truncate$1(label, 140));
+}
+function renderStatusSurface(h, components, state, context, contextStatus, bodyRows, width, theme) {
     const { Box, Text } = components;
     const focused = state.focus === 'commits';
     const worktree = context.worktree;
     const listRows = Math.max(4, bodyRows - 5);
     const selectedIndex = state.selectedWorktreeFileIndex;
     const cleanHint = formatLogInkStatusEmpty({ hasChanges: Boolean(worktree?.files.length) });
-    const lines = isLogInkContextKeyLoading(contextStatus, 'worktree')
+    const startIndex = Math.max(0, selectedIndex - Math.floor(listRows / 2));
+    const isLoading = isLogInkContextKeyLoading(contextStatus, 'worktree');
+    const fileRows = isLoading || !worktree?.files.length
+        ? []
+        : worktree.files.slice(startIndex).slice(0, listRows).map((file, offset) => {
+            const index = startIndex + offset;
+            const isSelected = index === selectedIndex;
+            const cursorPart = `${isSelected ? '>' : ' '} `;
+            const dotColor = getStageStatusDotColor(file.state, theme);
+            const useDot = dotColor !== undefined;
+            const dotCells = useDot ? cellWidth(STAGE_STATUS_DOT) + 1 : 0;
+            const tail = `${file.indexStatus}${file.worktreeStatus} ${file.state.padEnd(9)} ${file.path}`;
+            const tailTrunc = truncate$1(tail, Math.max(0, 140 - cellWidth(cursorPart) - dotCells));
+            return h(Text, {
+                key: `status-row-${index}`,
+                dimColor: offset > 0,
+            }, cursorPart, ...(useDot ? [h(Text, { color: dotColor }, STAGE_STATUS_DOT), ' '] : []), tailTrunc);
+        });
+    const fallbackLines = isLoading
         ? [formatLogInkLoading({ resource: 'worktree status' })]
         : worktree?.files.length
-            ? worktree.files
-                .slice(Math.max(0, selectedIndex - Math.floor(listRows / 2)))
-                .slice(0, listRows)
-                .map((file, offset) => {
-                const index = Math.max(0, selectedIndex - Math.floor(listRows / 2)) + offset;
-                return `${index === selectedIndex ? '>' : ' '} ${file.indexStatus}${file.worktreeStatus} ${file.state.padEnd(9)} ${file.path}`;
-            })
+            ? []
             : cleanHint
                 ? [cleanHint]
                 : ['Worktree clean'];
@@ -19611,16 +21925,17 @@ function renderStatusSurface(h, components, state, context, contextStatus, bodyR
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
         flexDirection: 'column',
-        flexGrow: 1,
+        flexShrink: 0,
         paddingX: 1,
+        width,
     }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Worktree', focused)), h(Text, { dimColor: true }, worktree
         ? `${worktree.stagedCount} staged | ${worktree.unstagedCount} unstaged | ${worktree.untrackedCount} untracked`
-        : 'status loading')), ...lines.map((line, index) => h(Text, {
-        key: `status-surface-${index}`,
+        : 'status loading')), ...fileRows, ...fallbackLines.map((line, index) => h(Text, {
+        key: `status-surface-fallback-${index}`,
         dimColor: index > 0,
     }, truncate$1(line, 140))));
 }
-function renderComposeSurface(h, components, state, context, contextStatus, bodyRows, theme) {
+function renderComposeSurface(h, components, state, context, contextStatus, bodyRows, width, theme) {
     const { Box, Text } = components;
     const compose = state.commitCompose;
     const focused = state.focus === 'commits';
@@ -19633,52 +21948,65 @@ function renderComposeSurface(h, components, state, context, contextStatus, body
     const summaryCursor = compose.editing && compose.field === 'summary' ? '_' : '';
     const bodyCursor = compose.editing && compose.field === 'body' ? '_' : '';
     const bodyRowsAvailable = Math.max(4, bodyRows - 10);
-    const bodyLines = compose.body
-        ? compose.body.split('\n').slice(0, bodyRowsAvailable)
+    // Wrap each source line of the body to the panel width so long messages
+    // line-wrap inside the compose surface instead of getting trimmed by an
+    // outer truncate(line, 140). The 2-space indent eats 2 cells; chrome
+    // (border + paddingX) eats 4 — same budget as renderCommitPanel.
+    const bodyTextWidth = Math.max(8, width - 6);
+    const bodyVisualLines = compose.body
+        ? compose.body.split('\n').flatMap((line) => wrapCells(line, bodyTextWidth)).slice(0, bodyRowsAvailable)
         : ['<empty>'];
-    const stateLine = compose.loading
-        ? 'Working...'
-        : compose.editing
-            ? 'Editing — Enter switches summary↔body, Esc exits edit mode.'
-            : 'Press e to edit, c to commit, I for AI draft, esc to leave.';
-    const stagedFileLines = (worktree?.files || [])
-        .filter((file) => file.indexStatus !== ' ' && file.indexStatus !== '?')
-        .slice(0, 5)
-        .map((file) => `  ${file.indexStatus} ${file.path}`);
+    const summaryVisualLines = wrapCells(`${compose.summary || '<empty>'}${summaryCursor}`, Math.max(8, width - 11) // "Summary  " (9) + 2 chrome = 11
+    );
+    const stateLine = compose.editing
+        ? 'Editing — Enter switches summary↔body, Esc exits edit mode.'
+        : 'Press e to edit, c to commit, I for AI draft, esc to leave.';
+    const hasStagedFiles = (worktree?.files || [])
+        .some((file) => file.indexStatus !== ' ' && file.indexStatus !== '?');
+    // Staged file list is rendered in the right Worktree panel
+    // (renderComposeContextPanel); duplicating it here was confusing.
+    // Keep only the actionable "stage something first" hint when nothing is
+    // staged yet.
     const noStagedHint = !isLogInkContextKeyLoading(contextStatus, 'worktree')
-        ? formatLogInkComposeEmpty({ hasStaged: stagedFileLines.length > 0 })
+        ? formatLogInkComposeEmpty({ hasStaged: hasStagedFiles })
         : undefined;
     return h(Box, {
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
         flexDirection: 'column',
-        flexGrow: 1,
+        flexShrink: 0,
         paddingX: 1,
+        width,
     }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Compose commit', focused)), h(Text, { dimColor: true }, statusLine)), h(Text, undefined, ''), h(Text, {
         bold: compose.field === 'summary' && compose.editing,
-    }, truncate$1(`Summary  ${compose.summary || '<empty>'}${summaryCursor}`, 140)), h(Text, undefined, ''), h(Text, {
+    }, `Summary  ${summaryVisualLines[0] || ''}`), ...summaryVisualLines.slice(1).map((line, index) => h(Text, {
+        key: `compose-summary-${index}`,
+        bold: compose.field === 'summary' && compose.editing,
+    }, `         ${line}`)), h(Text, undefined, ''), h(Text, {
         bold: compose.field === 'body' && compose.editing,
-    }, 'Body'), ...bodyLines.map((line, index) => h(Text, {
-        key: `compose-body-${index}`,
-        dimColor: line === '<empty>',
-    }, truncate$1(`  ${line}${bodyCursor && index === bodyLines.length - 1 ? bodyCursor : ''}`, 140))), h(Text, undefined, ''), h(Text, { dimColor: true }, stateLine), ...(compose.message ? [h(Text, { key: 'compose-msg' }, truncate$1(compose.message, 140))] : []), ...(compose.details || []).map((line, index) => h(Text, {
+    }, 'Body'), ...bodyVisualLines.map((line, index) => {
+        const isLast = index === bodyVisualLines.length - 1;
+        return h(Text, {
+            key: `compose-body-${index}`,
+            dimColor: line === '<empty>',
+        }, `  ${line}${bodyCursor && isLast ? bodyCursor : ''}`);
+    }), h(Text, undefined, ''), ...(compose.loading
+        ? [h(Text, {
+                key: 'compose-loading',
+                bold: true,
+                color: theme.noColor ? undefined : theme.colors.accent,
+            }, theme.ascii
+                ? '[...] Generating AI commit draft (this can take a moment)'
+                : '⏳ Generating AI commit draft… (this can take a moment)')]
+        : [h(Text, { dimColor: true }, stateLine)]), ...(compose.message ? [h(Text, { key: 'compose-msg' }, truncate$1(compose.message, 140))] : []), ...(compose.details || []).map((line, index) => h(Text, {
         key: `compose-detail-${index}`,
         dimColor: true,
-    }, truncate$1(`  ${line}`, 140))), ...(stagedFileLines.length > 0
+    }, truncate$1(`  ${line}`, 140))), ...(!hasStagedFiles && noStagedHint
         ? [
-            h(Text, { key: 'compose-staged-spacer' }, ''),
-            h(Text, { key: 'compose-staged-title', bold: true }, 'Staged'),
-            ...stagedFileLines.map((line, index) => h(Text, {
-                key: `compose-staged-${index}`,
-                dimColor: true,
-            }, truncate$1(line, 140))),
+            h(Text, { key: 'compose-no-staged-spacer' }, ''),
+            h(Text, { key: 'compose-no-staged', dimColor: true }, truncate$1(noStagedHint, 140)),
         ]
-        : noStagedHint
-            ? [
-                h(Text, { key: 'compose-no-staged-spacer' }, ''),
-                h(Text, { key: 'compose-no-staged', dimColor: true }, truncate$1(noStagedHint, 140)),
-            ]
-            : []));
+        : []));
 }
 function matchesPromotedFilter(haystacks, filter) {
     if (!filter.trim()) {
@@ -19687,23 +22015,24 @@ function matchesPromotedFilter(haystacks, filter) {
     const needle = filter.toLowerCase();
     return haystacks.some((value) => value.toLowerCase().includes(needle));
 }
-function renderBranchesSurface(h, components, state, context, contextStatus, bodyRows, theme) {
+function renderBranchesSurface(h, components, state, context, contextStatus, bodyRows, width, theme) {
     const { Box, Text } = components;
     const focused = state.focus === 'commits';
     const branches = context.branches;
     const loading = isLogInkContextKeyLoading(contextStatus, 'branches');
-    const allLocalBranches = branches?.localBranches || [];
+    const sortedAll = sortBranches(branches?.localBranches || [], state.branchSort);
     const localBranches = state.filter
-        ? allLocalBranches.filter((branch) => matchesPromotedFilter([branch.shortName, branch.upstream || ''], state.filter))
-        : allLocalBranches;
+        ? sortedAll.filter((branch) => matchesPromotedFilter([branch.shortName, branch.upstream || ''], state.filter))
+        : sortedAll;
     const selected = Math.max(0, Math.min(state.selectedBranchIndex, Math.max(0, localBranches.length - 1)));
     const listRows = Math.max(4, bodyRows - 4);
     const startIndex = Math.max(0, selected - Math.floor(listRows / 2));
     const visible = localBranches.slice(startIndex, startIndex + listRows);
     const filterLabel = state.filter ? ` | filter: ${state.filter}` : '';
+    const sortLabel = ` | ${formatSortIndicator(state.branchSort, { ascii: theme.ascii })}`;
     const headerRight = loading
         ? 'loading branches'
-        : `${localBranches.length}/${allLocalBranches.length} local | current: ${branches?.currentBranch || '<detached>'}${filterLabel}`;
+        : `${localBranches.length}/${sortedAll.length} local | current: ${branches?.currentBranch || '<detached>'}${filterLabel}${sortLabel}`;
     const emptyLabel = formatLogInkBranchesEmpty({ filter: state.filter });
     const loadingLabel = formatLogInkLoading({ resource: 'branches' });
     const lines = loading
@@ -19714,8 +22043,8 @@ function renderBranchesSurface(h, components, state, context, contextStatus, bod
                 const index = startIndex + offset;
                 const isSelected = index === selected;
                 const cursor = isSelected ? '>' : ' ';
-                const marker = branch.current ? '*' : ' ';
-                const divergence = formatDivergence(branch);
+                const marker = branchRowMarker(branch, { ascii: theme.ascii });
+                const divergence = formatBranchDivergence(branch, { ascii: theme.ascii });
                 return h(Text, {
                     key: `branch-${index}`,
                     bold: isSelected,
@@ -19726,26 +22055,28 @@ function renderBranchesSurface(h, components, state, context, contextStatus, bod
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
         flexDirection: 'column',
-        flexGrow: 1,
+        flexShrink: 0,
         paddingX: 1,
-    }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Branches', focused)), h(Text, { dimColor: true }, headerRight)), ...lines);
+        width,
+    }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Branches', focused)), h(Text, { dimColor: true }, headerRight)), ...renderPromotedFilterAffordance(h, Text, state, theme), ...lines);
 }
-function renderTagsSurface(h, components, state, context, contextStatus, bodyRows, theme) {
+function renderTagsSurface(h, components, state, context, contextStatus, bodyRows, width, theme) {
     const { Box, Text } = components;
     const focused = state.focus === 'commits';
     const loading = isLogInkContextKeyLoading(contextStatus, 'tags');
-    const allTags = context.tags?.tags || [];
+    const sortedAll = sortTags(context.tags?.tags || [], state.tagSort);
     const tags = state.filter
-        ? allTags.filter((tag) => matchesPromotedFilter([tag.name, tag.subject], state.filter))
-        : allTags;
+        ? sortedAll.filter((tag) => matchesPromotedFilter([tag.name, tag.subject], state.filter))
+        : sortedAll;
     const selected = Math.max(0, Math.min(state.selectedTagIndex, Math.max(0, tags.length - 1)));
     const listRows = Math.max(4, bodyRows - 4);
     const startIndex = Math.max(0, selected - Math.floor(listRows / 2));
     const visible = tags.slice(startIndex, startIndex + listRows);
     const filterLabel = state.filter ? ` | filter: ${state.filter}` : '';
+    const sortLabel = ` | ${formatSortIndicator(state.tagSort, { ascii: theme.ascii })}`;
     const headerRight = loading
         ? 'loading tags'
-        : `${tags.length}/${allTags.length} tags${filterLabel}`;
+        : `${tags.length}/${sortedAll.length} tags${filterLabel}${sortLabel}`;
     const emptyLabel = formatLogInkTagsEmpty({ filter: state.filter });
     const loadingLabel = formatLogInkLoading({ resource: 'tags' });
     const lines = loading
@@ -19756,21 +22087,39 @@ function renderTagsSurface(h, components, state, context, contextStatus, bodyRow
                 const index = startIndex + offset;
                 const isSelected = index === selected;
                 const cursor = isSelected ? '>' : ' ';
+                // P5.1 — link the tag name to its GitHub tree page when we know
+                // the remote. Truncation runs on the visible (pre-OSC) text;
+                // formatHyperlink wraps just the tag name, leaving width math
+                // intact.
+                const url = buildRefUrl(context.provider?.repository, tag.name);
+                const namePadded = tag.name.padEnd(20);
+                const lineText = truncate$1(`${cursor} ${namePadded} ${tag.subject}`, 140);
+                if (!url || lineText.indexOf(namePadded) < 0) {
+                    return h(Text, {
+                        key: `tag-${index}`,
+                        bold: isSelected,
+                        dimColor: !isSelected,
+                    }, lineText);
+                }
+                const linkStart = lineText.indexOf(namePadded);
+                const before = lineText.slice(0, linkStart);
+                const after = lineText.slice(linkStart + namePadded.length);
                 return h(Text, {
                     key: `tag-${index}`,
                     bold: isSelected,
                     dimColor: !isSelected,
-                }, truncate$1(`${cursor} ${tag.name.padEnd(20)} ${tag.subject}`, 140));
+                }, before, formatHyperlink(namePadded, url), after);
             });
     return h(Box, {
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
         flexDirection: 'column',
-        flexGrow: 1,
+        flexShrink: 0,
         paddingX: 1,
-    }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Tags', focused)), h(Text, { dimColor: true }, headerRight)), ...lines);
+        width,
+    }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Tags', focused)), h(Text, { dimColor: true }, headerRight)), ...renderPromotedFilterAffordance(h, Text, state, theme), ...lines);
 }
-function renderStashSurface(h, components, state, context, contextStatus, bodyRows, theme) {
+function renderStashSurface(h, components, state, context, contextStatus, bodyRows, width, theme) {
     const { Box, Text } = components;
     const focused = state.focus === 'commits';
     const loading = isLogInkContextKeyLoading(contextStatus, 'stashes');
@@ -19806,26 +22155,91 @@ function renderStashSurface(h, components, state, context, contextStatus, bodyRo
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
         flexDirection: 'column',
-        flexGrow: 1,
+        flexShrink: 0,
         paddingX: 1,
-    }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Stash', focused)), h(Text, { dimColor: true }, headerRight)), ...lines);
+        width,
+    }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Stash', focused)), h(Text, { dimColor: true }, headerRight)), ...renderPromotedFilterAffordance(h, Text, state, theme), ...lines);
+}
+/**
+ * Filter input cursor for the promoted views (branches/tags/stash).
+ * History already shows the same `filter: foo_` affordance in its header
+ * — this mirrors that into the other surfaces so the user can see what
+ * they're typing instead of watching the list silently shrink (P2.1).
+ *
+ * Returns an empty array when the surface isn't in filter mode so call
+ * sites can spread it unconditionally.
+ */
+function renderPromotedFilterAffordance(h, Text, state, theme) {
+    if (!state.filterMode) {
+        return [];
+    }
+    const accent = theme.noColor ? undefined : theme.colors.accent;
+    return [
+        h(Text, { key: 'promoted-filter-input', color: accent }, `filter: ${state.filter}_`),
+    ];
 }
-function renderDiffSurface(h, components, state, context, contextStatus, worktreeDiff, worktreeDiffLoading, worktreeHunks, worktreeHunksLoading, bodyRows, theme) {
+function renderDiffSurface(h, components, state, context, contextStatus, worktreeDiff, worktreeDiffLoading, worktreeHunks, worktreeHunksLoading, filePreview, filePreviewLoading, commitDiffHunkOffsets, selectedDetailFile, bodyRows, width, theme) {
     const { Box, Text } = components;
     const focused = state.focus === 'commits';
     const worktree = context.worktree;
-    const selectedFile = worktree?.files[state.selectedWorktreeFileIndex];
+    const worktreeFile = worktree?.files[state.selectedWorktreeFileIndex];
     const visibleRows = Math.max(4, bodyRows - 4);
+    // diffSource disambiguates: 'commit' was set when the user opened the
+    // diff via history → Enter (read-only commit-diff explore), 'worktree'
+    // was set when they came from status → Enter (stage / hunk / revert).
+    // Falls back to the previous heuristic when no source is recorded so
+    // older entry paths still render something sensible.
+    const useCommitDiff = state.diffSource === 'commit' ||
+        (state.diffSource === undefined && !worktreeFile && Boolean(selectedDetailFile));
+    if (useCommitDiff) {
+        const previewHunks = filePreview?.hunks || [];
+        const visiblePreviewHunks = previewHunks.slice(state.diffPreviewOffset, state.diffPreviewOffset + visibleRows);
+        const hunkCount = commitDiffHunkOffsets?.length || 0;
+        const currentHunkIndex = hunkCount > 0
+            ? Math.max(0, [...(commitDiffHunkOffsets || [])]
+                .reverse()
+                .findIndex((offset) => offset <= state.diffPreviewOffset))
+            : 0;
+        const currentHunkLabel = hunkCount > 0
+            ? `Hunk ${Math.min(hunkCount - currentHunkIndex, hunkCount)}/${hunkCount}`
+            : 'No hunks for this file.';
+        const headerLines = filePreviewLoading
+            ? [`Loading diff for ${selectedDetailFile?.path || 'selected file'}...`]
+            : previewHunks.length
+                ? [
+                    `Selected file: ${selectedDetailFile?.path || ''}`,
+                    currentHunkLabel,
+                    `Lines ${Math.min(state.diffPreviewOffset + 1, previewHunks.length || 1)}-${Math.min(state.diffPreviewOffset + visiblePreviewHunks.length, previewHunks.length)}/${previewHunks.length}`,
+                    '',
+                ]
+                : ['No diff preview available for this file.'];
+        return h(Box, {
+            borderColor: focusBorderColor(theme, focused),
+            borderStyle: theme.borderStyle,
+            flexDirection: 'column',
+            flexShrink: 0,
+            paddingX: 1,
+            width,
+        }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Diff', focused)), h(Text, { dimColor: true }, selectedDetailFile?.path || 'no file')), ...headerLines.map((line, index) => h(Text, {
+            key: `diff-surface-header-${index}`,
+            dimColor: index > 0,
+        }, truncate$1(line, 140))), ...(filePreviewLoading || !previewHunks.length
+            ? []
+            : visiblePreviewHunks.map((line, index) => h(Text, {
+                key: `diff-surface-line-${state.diffPreviewOffset + index}`,
+                ...diffLineProps(line, theme),
+            }, truncate$1(line, 140)))));
+    }
     const diffLines = worktreeDiff?.lines || [];
     const selectedHunk = worktreeHunks?.hunks[state.selectedWorktreeHunkIndex];
     const visibleDiffLines = diffLines.slice(state.worktreeDiffOffset, state.worktreeDiffOffset + visibleRows);
-    const lines = isLogInkContextKeyLoading(contextStatus, 'worktree')
+    const headerLines = isLogInkContextKeyLoading(contextStatus, 'worktree')
         ? ['Loading file context...']
         : worktreeDiffLoading
-            ? [`Loading diff for ${selectedFile?.path || 'selected file'}...`]
-            : selectedFile
+            ? [`Loading diff for ${worktreeFile?.path || 'selected file'}...`]
+            : worktreeFile
                 ? [
-                    `Selected file: ${selectedFile.path}`,
+                    `Selected file: ${worktreeFile.path}`,
                     worktreeHunksLoading
                         ? 'Hunks loading...'
                         : worktreeHunks?.hunks.length
@@ -19833,22 +22247,29 @@ function renderDiffSurface(h, components, state, context, contextStatus, worktre
                             : 'No stageable hunks for this file.',
                     `Lines ${Math.min(state.worktreeDiffOffset + 1, diffLines.length || 1)}-${Math.min(state.worktreeDiffOffset + visibleDiffLines.length, diffLines.length)}/${diffLines.length}`,
                     '',
-                    ...visibleDiffLines,
                 ]
                 : ['No changed file selected.'];
+    const showDiffLines = Boolean(worktreeFile) &&
+        !worktreeDiffLoading &&
+        !isLogInkContextKeyLoading(contextStatus, 'worktree');
     return h(Box, {
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
         flexDirection: 'column',
-        flexGrow: 1,
+        flexShrink: 0,
         paddingX: 1,
-    }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Diff', focused)), h(Text, { dimColor: true }, selectedFile ? selectedFile.path : 'no file')), ...lines.map((line, index) => h(Text, {
-        key: `diff-surface-${index}`,
-        dimColor: index > 1,
-    }, truncate$1(line, 140))));
+        width,
+    }, h(Box, { justifyContent: 'space-between' }, h(Text, { bold: true }, panelTitle('Diff', focused)), h(Text, { dimColor: true }, worktreeFile ? worktreeFile.path : 'no file')), ...headerLines.map((line, index) => h(Text, {
+        key: `diff-surface-header-${index}`,
+        dimColor: index > 0,
+    }, truncate$1(line, 140))), ...(showDiffLines
+        ? visibleDiffLines.map((line, index) => h(Text, {
+            key: `diff-surface-line-${state.worktreeDiffOffset + index}`,
+            ...diffLineProps(line, theme),
+        }, truncate$1(line, 140)))
+        : []));
 }
 function renderDetailPanel(h, components, state, context, contextStatus, detail, loading, filePreview, filePreviewLoading, width, theme) {
-    const { Box, Text } = components;
     const focused = state.focus === 'detail';
     if (state.showHelp) {
         return renderHelpPanel(h, components, state, width, theme, focused);
@@ -19859,69 +22280,351 @@ function renderDetailPanel(h, components, state, context, contextStatus, detail,
     if (state.pendingConfirmationId || state.pendingMutationConfirmation) {
         return renderConfirmationPanel(h, components, state, width, theme, focused);
     }
-    if (state.activeView === 'status' || state.activeView === 'diff') {
+    // which-key style overlay — shows the available chord continuations
+    // when the user has pressed the prefix and we're waiting for the
+    // second key. Mirrors helix / which-key.nvim / doom-emacs.
+    if (state.pendingKey) {
+        return renderChordOverlay(h, components, state, width, theme, focused);
+    }
+    // The synthetic "(+) new commit" row routes the inspector through the
+    // worktree summary so the user sees what's staged / unstaged at a glance
+    // — same surface as the compose view's right panel.
+    if (state.activeView === 'history' && state.pendingCommitFocused) {
+        return renderComposeContextPanel(h, components, state, context, contextStatus, width, theme, focused);
+    }
+    // Status + worktree-sourced diff keep the staging compose panel — it's
+    // the action surface for stage / hunk / commit. Commit-sourced diff (from
+    // history → Enter) gets a dedicated explore panel: subject, body, and a
+    // navigable file list whose selection swaps the center diff.
+    if (state.activeView === 'status') {
+        return renderCommitPanel(h, components, state, context, contextStatus, width, theme, focused);
+    }
+    if (state.activeView === 'diff') {
+        if (state.diffSource === 'commit') {
+            return renderCommitDiffDetail(h, components, state, detail, loading, width, theme, focused);
+        }
         return renderCommitPanel(h, components, state, context, contextStatus, width, theme, focused);
     }
+    // Compose view: the right panel had been falling through to the inspector
+    // and showing the last selected commit's data, which is wrong context for
+    // an in-progress commit. Show the worktree summary instead.
+    if (state.activeView === 'compose') {
+        return renderComposeContextPanel(h, components, state, context, contextStatus, width, theme, focused);
+    }
+    // Preview pane (P4.1) — fzf / yazi / lazygit style: branches, tags, and
+    // stash views each get a tailored summary of the selected entry instead
+    // of falling through to the (stale) history inspector.
+    if (state.activeView === 'branches') {
+        return renderBranchPreviewPanel(h, components, state, context, contextStatus, width, theme, focused);
+    }
+    if (state.activeView === 'tags') {
+        return renderTagPreviewPanel(h, components, state, context, contextStatus, width, theme, focused);
+    }
+    if (state.activeView === 'stash') {
+        return renderStashPreviewPanel(h, components, state, context, contextStatus, width, theme, focused);
+    }
+    return renderHistoryInspector(h, components, state, context, contextStatus, detail, loading, filePreview, filePreviewLoading, width, theme, focused);
+}
+function renderHistoryInspector(h, components, state, context, contextStatus, detail, loading, _filePreview, _filePreviewLoading, width, theme, focused) {
+    const { Box, Text } = components;
     const selected = getSelectedInkCommit(state);
-    const selectedFile = detail?.files[state.selectedFileIndex];
-    const previewWindow = filePreview?.hunks.slice(state.diffPreviewOffset, state.diffPreviewOffset + 8);
-    const statLine = detail
-        ? `${detail.stats.filesChanged} files  +${detail.stats.insertions}/-${detail.stats.deletions}`
-        : '';
     const workflowSections = getLogInkWorkflowSections({
         ...context,
         contextLoading: isLogInkContextLoading(contextStatus),
         selectedCommit: selected,
     });
-    const lines = detail
-        ? [
-            detail.message,
-            '',
-            `Commit: ${compactHash(detail.hash)}`,
-            `Author: ${detail.author}`,
-            `Date: ${detail.date}`,
-            detail.refs.length ? `Refs: ${detail.refs.join(', ')}` : 'Refs: none',
-            statLine,
-            '',
-            ...(detail.body ? detail.body.split('\n').slice(0, 6) : ['No commit body.']),
-            '',
-            'Changed files:',
-            ...(detail.files.length
-                ? detail.files.slice(0, 8).map((file, index) => `${index === state.selectedFileIndex ? '>' : ' '} ${formatChangedFile(file)}`)
-                : ['No changed files found.']),
-            '',
-            selectedFile
-                ? `Preview: ${formatChangedFile(selectedFile)}`
-                : 'Preview: no file selected',
-            filePreviewLoading
-                ? 'Loading diff preview...'
-                : previewWindow?.length
-                    ? `Lines ${state.diffPreviewOffset + 1}-${state.diffPreviewOffset + previewWindow.length}/${filePreview?.hunks.length || 0}`
-                    : 'No hunk preview available.',
-            ...(previewWindow || []).map((line) => `  ${line}`),
-            '',
-            'Workflows:',
-            ...workflowSections.flatMap((section) => [
-                section.title,
-                ...section.lines.slice(0, 3).map((line) => `  ${line}`),
-            ]).slice(0, 14),
-        ]
-        : [
+    if (!detail) {
+        const fallbackLines = [
             selected?.message || 'No commit selected.',
             '',
             loading ? 'Loading commit details...' : 'Commit details unavailable.',
         ];
+        return h(Box, {
+            borderColor: focusBorderColor(theme, focused),
+            borderStyle: theme.borderStyle,
+            flexDirection: 'column',
+            width,
+            paddingX: 1,
+        }, h(Text, { bold: true }, panelTitle('Inspector', focused)), ...fallbackLines.map((line, index) => h(Text, {
+            key: `detail-${index}`,
+            dimColor: index > 1,
+        }, truncate$1(line, width - 4))));
+    }
+    const statLine = `${detail.stats.filesChanged} files  +${detail.stats.insertions}/-${detail.stats.deletions}`;
+    // P5.1 — link the commit hash and each ref out to GitHub when we know
+    // the remote. OSC 8 escapes embed inline; supportsHyperlinks() decides
+    // whether to wrap or fall through to plain text.
+    const repository = context.provider?.repository;
+    const commitLink = formatHyperlink(compactHash(detail.hash), buildCommitUrl(repository, detail.hash));
+    const refNodes = detail.refs.length
+        ? renderInspectorRefs(h, Text, detail.refs, repository)
+        : null;
+    const headerNodes = [
+        h(Text, { key: 'detail-msg' }, truncate$1(detail.message, width - 4)),
+        h(Text, { key: 'detail-spacer-1' }, ''),
+        h(Text, { key: 'detail-commit', dimColor: true }, 'Commit: ', commitLink),
+        h(Text, { key: 'detail-author', dimColor: true }, truncate$1(`Author: ${detail.author}`, width - 4)),
+        h(Text, { key: 'detail-date', dimColor: true }, truncate$1(`Date: ${detail.date}`, width - 4)),
+        refNodes
+            ? h(Text, { key: 'detail-refs', dimColor: true }, 'Refs: ', ...refNodes)
+            : h(Text, { key: 'detail-refs', dimColor: true }, 'Refs: none'),
+        h(Text, { key: 'detail-stat', dimColor: true }, truncate$1(statLine, width - 4)),
+        h(Text, { key: 'detail-spacer-2' }, ''),
+        ...(detail.body ? detail.body.split('\n').slice(0, 6) : ['No commit body.']).map((line, index) => h(Text, {
+            key: `detail-body-${index}`,
+            dimColor: true,
+        }, truncate$1(line, width - 4))),
+        h(Text, { key: 'detail-spacer-3' }, ''),
+        h(Text, { key: 'detail-files-title' }, 'Changed files:'),
+    ];
+    const fileListMaxRows = Math.max(4, Math.min(detail.files.length, 10));
+    const fileListNodes = renderCommitFileList(h, Text, detail.files, state.selectedFileIndex, focused, fileListMaxRows, width, theme);
+    const trailerLines = [
+        '',
+        'Workflows:',
+        ...workflowSections.flatMap((section) => [
+            section.title,
+            ...section.lines.slice(0, 3).map((line) => `  ${line}`),
+        ]).slice(0, 12),
+    ];
     return h(Box, {
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
         flexDirection: 'column',
         width,
         paddingX: 1,
-    }, h(Text, { bold: true }, panelTitle('Inspector', focused)), ...lines.map((line, index) => h(Text, {
-        key: `detail-${index}`,
-        dimColor: index > 1 && line !== 'Changed files:',
+    }, h(Text, { bold: true }, panelTitle('Inspector', focused)), ...headerNodes, ...fileListNodes, ...trailerLines.map((line, index) => h(Text, {
+        key: `detail-trailer-${index}`,
+        dimColor: index > 0,
     }, truncate$1(line, width - 4))));
 }
+/**
+ * Build a commit URL for the repo when GitHub provider info is available.
+ * Returns undefined for unsupported remotes — formatHyperlink falls through
+ * to plain text in that case.
+ */
+function buildCommitUrl(repository, hash) {
+    if (!repository)
+        return undefined;
+    return buildProviderUrl(repository, { type: 'commit', commit: hash });
+}
+/**
+ * Build a branch URL for a ref name. Strips the `HEAD -> ` and `tag: `
+ * prefixes git decoration uses. For everything else we treat the ref as a
+ * branch — GitHub's `/tree/<ref>` resolves both branches and tags.
+ */
+function buildRefUrl(repository, ref) {
+    if (!repository)
+        return undefined;
+    const stripped = ref.replace(/^HEAD -> /, '').replace(/^tag: /, '').trim();
+    if (!stripped)
+        return undefined;
+    return buildProviderUrl(repository, { type: 'branch', branch: stripped });
+}
+/**
+ * Render `refs` as a comma-separated sequence of <Text> fragments, each
+ * wrapped in OSC 8 (no-op when the terminal can't render hyperlinks).
+ */
+function renderInspectorRefs(h, Text, refs, repository) {
+    const out = [];
+    refs.forEach((ref, index) => {
+        if (index > 0) {
+            out.push(h(Text, { key: `ref-sep-${index}` }, ', '));
+        }
+        out.push(h(Text, { key: `ref-${index}` }, formatHyperlink(ref, buildRefUrl(repository, ref))));
+    });
+    return out;
+}
+function renderCommitDiffDetail(h, components, state, detail, loading, width, theme, focused) {
+    const { Box, Text } = components;
+    const selected = getSelectedInkCommit(state);
+    if (!detail) {
+        const fallbackLines = [
+            selected?.message || 'No commit selected.',
+            '',
+            loading ? 'Loading commit details...' : 'Commit details unavailable.',
+        ];
+        return h(Box, {
+            borderColor: focusBorderColor(theme, focused),
+            borderStyle: theme.borderStyle,
+            flexDirection: 'column',
+            width,
+            paddingX: 1,
+        }, h(Text, { bold: true }, panelTitle('Commit', focused)), ...fallbackLines.map((line, index) => h(Text, {
+            key: `commit-diff-${index}`,
+            dimColor: index > 1,
+        }, truncate$1(line, width - 4))));
+    }
+    const statLine = `${detail.stats.filesChanged} files  +${detail.stats.insertions}/-${detail.stats.deletions}`;
+    const headerLines = [
+        detail.message,
+        '',
+        `${compactHash(detail.hash)}  ${detail.date}  ${detail.author}`,
+        detail.refs.length ? `Refs: ${detail.refs.join(', ')}` : 'Refs: none',
+        statLine,
+        '',
+    ];
+    const bodyLines = detail.body ? detail.body.split('\n').slice(0, 5) : [];
+    const filesHeader = ['Files:'];
+    const fileListMaxRows = Math.max(4, Math.min(detail.files.length, 12));
+    const fileListNodes = renderCommitFileList(h, Text, detail.files, state.selectedFileIndex, focused, fileListMaxRows, width, theme);
+    const hint = focused
+        ? 'j/k pick file · enter swaps the center diff'
+        : 'tab focuses the file list';
+    return h(Box, {
+        borderColor: focusBorderColor(theme, focused),
+        borderStyle: theme.borderStyle,
+        flexDirection: 'column',
+        width,
+        paddingX: 1,
+    }, h(Text, { bold: true }, panelTitle('Commit', focused)), ...headerLines.map((line, index) => h(Text, {
+        key: `commit-diff-header-${index}`,
+        bold: index === 0,
+        dimColor: index > 0 && index < headerLines.length - 1,
+    }, truncate$1(line, width - 4))), ...bodyLines.map((line, index) => h(Text, {
+        key: `commit-diff-body-${index}`,
+        dimColor: true,
+    }, truncate$1(line, width - 4))), ...(bodyLines.length ? [h(Text, { key: 'commit-diff-body-spacer' }, '')] : []), ...filesHeader.map((line, index) => h(Text, {
+        key: `commit-diff-files-${index}`,
+        bold: true,
+    }, truncate$1(line, width - 4))), ...fileListNodes, h(Text, undefined, ''), h(Text, { dimColor: true }, truncate$1(hint, width - 4)));
+}
+function renderComposeContextPanel(h, components, state, context, contextStatus, width, theme, focused) {
+    const { Box, Text } = components;
+    const worktree = context.worktree;
+    const compose = state.commitCompose;
+    const loadingWorktree = isLogInkContextKeyLoading(contextStatus, 'worktree');
+    const summary = loadingWorktree
+        ? 'Worktree status loading'
+        : worktree
+            ? `${worktree.stagedCount} staged · ${worktree.unstagedCount} unstaged · ${worktree.untrackedCount} untracked`
+            : 'No worktree information yet';
+    const stagedFiles = (worktree?.files || [])
+        .filter((file) => file.indexStatus !== ' ' && file.indexStatus !== '?')
+        .slice(0, 12);
+    const unstagedFiles = (worktree?.files || [])
+        .filter((file) => file.worktreeStatus !== ' ' && file.indexStatus !== '?')
+        .slice(0, 6);
+    return h(Box, {
+        borderColor: focusBorderColor(theme, focused),
+        borderStyle: theme.borderStyle,
+        flexDirection: 'column',
+        width,
+        paddingX: 1,
+    }, h(Text, { bold: true }, panelTitle('Worktree', focused)), h(Text, { dimColor: true }, truncate$1(summary, width - 4)), h(Text, undefined, ''), ...(compose.loading
+        ? [h(Text, {
+                key: 'compose-context-loading',
+                bold: true,
+                color: theme.noColor ? undefined : theme.colors.accent,
+            }, truncate$1(theme.ascii ? '[...] AI draft in progress' : '⏳ AI draft in progress', width - 4))]
+        : []), ...(stagedFiles.length
+        ? [
+            h(Text, { key: 'compose-context-staged-title', bold: true }, 'Staged'),
+            ...stagedFiles.map((file, index) => h(Text, {
+                key: `compose-context-staged-${index}`,
+                color: theme.noColor ? undefined : theme.colors.gitAdded,
+            }, truncate$1(`  ${file.indexStatus} ${file.path}`, width - 4))),
+            h(Text, { key: 'compose-context-staged-spacer' }, ''),
+        ]
+        : []), ...(unstagedFiles.length
+        ? [
+            h(Text, { key: 'compose-context-unstaged-title', bold: true }, 'Unstaged'),
+            ...unstagedFiles.map((file, index) => h(Text, {
+                key: `compose-context-unstaged-${index}`,
+                color: theme.noColor ? undefined : theme.colors.gitModified,
+            }, truncate$1(`  ${file.worktreeStatus} ${file.path}`, width - 4))),
+        ]
+        : !stagedFiles.length && !loadingWorktree
+            ? [h(Text, { dimColor: true }, 'No worktree changes detected.')]
+            : []));
+}
+/**
+ * Render a list of changed files with status-code colors and stats. Used
+ * by both the history inspector and the commit-diff detail panel so the
+ * two surfaces stay visually consistent.
+ *
+ * `focused` only controls whether the cursor row is inverse-highlighted —
+ * keys j/k and Enter dispatch via the input handler regardless.
+ */
+function renderCommitFileList(h, Text, files, selectedIndex, focused, maxRows, width, theme) {
+    if (!files.length) {
+        return [h(Text, { key: 'commit-file-list-empty', dimColor: true }, 'No changed files found.')];
+    }
+    const clamped = Math.max(0, Math.min(selectedIndex, files.length - 1));
+    const startIndex = Math.max(0, clamped - Math.floor(maxRows / 2));
+    const visible = files.slice(startIndex, startIndex + maxRows);
+    return visible.map((file, offset) => {
+        const index = startIndex + offset;
+        const isSelected = index === clamped;
+        const cursor = isSelected ? '>' : ' ';
+        const stats = formatChangedFileStats(file);
+        const renamed = file.oldPath ? ` (was ${file.oldPath})` : '';
+        const statusCode = file.status.padEnd(3);
+        const label = `${cursor} ${statusCode} ${file.path}${renamed}${stats ? `  ${stats}` : ''}`;
+        return h(Text, {
+            key: `commit-file-${index}`,
+            color: statusCodeColor(file.status, theme),
+            inverse: isSelected && focused && !theme.noColor,
+            bold: isSelected,
+        }, truncate$1(label, width - 4));
+    });
+}
+function renderPreviewPanel(h, components, title, lines, width, theme, focused) {
+    const { Box, Text } = components;
+    return h(Box, {
+        borderColor: focusBorderColor(theme, focused),
+        borderStyle: theme.borderStyle,
+        flexDirection: 'column',
+        width,
+        paddingX: 1,
+    }, h(Text, { bold: true }, panelTitle(title, focused)), ...lines.map((line, index) => {
+        const isHeading = line.emphasis === 'heading' && index > 0;
+        return h(Text, {
+            key: `preview-${index}`,
+            bold: isHeading,
+            dimColor: line.emphasis === 'dim',
+        }, truncate$1(line.text, width - 4));
+    }));
+}
+function renderBranchPreviewPanel(h, components, state, context, contextStatus, width, theme, focused) {
+    const { Box, Text } = components;
+    if (isLogInkContextKeyLoading(contextStatus, 'branches')) {
+        return renderPreviewPanel(h, { Box, Text }, 'Branch preview', [{ text: formatLogInkLoading({ resource: 'branches' }), emphasis: 'dim' }], width, theme, focused);
+    }
+    const all = context.branches?.localBranches || [];
+    const visible = state.filter
+        ? all.filter((branch) => matchesPromotedFilter([branch.shortName, branch.upstream || ''], state.filter))
+        : all;
+    const index = Math.max(0, Math.min(state.selectedBranchIndex, Math.max(0, visible.length - 1)));
+    const branch = visible[index];
+    return renderPreviewPanel(h, { Box, Text }, 'Branch preview', formatBranchPreview(branch), width, theme, focused);
+}
+function renderTagPreviewPanel(h, components, state, context, contextStatus, width, theme, focused) {
+    const { Box, Text } = components;
+    if (isLogInkContextKeyLoading(contextStatus, 'tags')) {
+        return renderPreviewPanel(h, { Box, Text }, 'Tag preview', [{ text: formatLogInkLoading({ resource: 'tags' }), emphasis: 'dim' }], width, theme, focused);
+    }
+    const all = context.tags?.tags || [];
+    const visible = state.filter
+        ? all.filter((tag) => matchesPromotedFilter([tag.name, tag.subject], state.filter))
+        : all;
+    const index = Math.max(0, Math.min(state.selectedTagIndex, Math.max(0, visible.length - 1)));
+    const tag = visible[index];
+    return renderPreviewPanel(h, { Box, Text }, 'Tag preview', formatTagPreview(tag), width, theme, focused);
+}
+function renderStashPreviewPanel(h, components, state, context, contextStatus, width, theme, focused) {
+    const { Box, Text } = components;
+    if (isLogInkContextKeyLoading(contextStatus, 'stashes')) {
+        return renderPreviewPanel(h, { Box, Text }, 'Stash preview', [{ text: formatLogInkLoading({ resource: 'stashes' }), emphasis: 'dim' }], width, theme, focused);
+    }
+    const all = context.stashes?.stashes || [];
+    const visible = state.filter
+        ? all.filter((stash) => matchesPromotedFilter([stash.ref, stash.message], state.filter))
+        : all;
+    const index = Math.max(0, Math.min(state.selectedStashIndex, Math.max(0, visible.length - 1)));
+    const stash = visible[index];
+    return renderPreviewPanel(h, { Box, Text }, 'Stash preview', formatStashPreview(stash), width, theme, focused);
+}
 function renderCommitPanel(h, components, state, context, contextStatus, width, theme, focused) {
     const { Box, Text } = components;
     const compose = state.commitCompose;
@@ -19933,31 +22636,55 @@ function renderCommitPanel(h, components, state, context, contextStatus, width,
         : `${stagedCount} staged | ${unstagedCount} unstaged`;
     const summaryCursor = compose.editing && compose.field === 'summary' ? '_' : '';
     const bodyCursor = compose.editing && compose.field === 'body' ? '_' : '';
-    const bodyLines = compose.body ? compose.body.split('\n').slice(0, 4) : ['<empty>'];
-    const lines = [
+    const bodyTextWidth = Math.max(8, width - 6); // 4 for chrome + 2 for indent
+    // Wrap each source line of the body so long messages don't get cut off
+    // by the previous truncate(line, width - 4). The 12-line cap is generous
+    // — most commit bodies fit, and the panel's column layout absorbs the
+    // height naturally.
+    const bodyHasContent = Boolean(compose.body);
+    const bodyVisualLines = bodyHasContent
+        ? compose.body.split('\n').flatMap((line) => wrapCells(line, bodyTextWidth)).slice(0, 12)
+        : ['<empty>'];
+    const summaryWrapped = wrapCells(`${compose.summary || '<empty>'}${summaryCursor}`, bodyTextWidth);
+    const summaryFirst = `${compose.field === 'summary' && compose.editing ? '>' : ' '} Summary: ${summaryWrapped[0] || ''}`;
+    const summaryRest = summaryWrapped.slice(1).map((line) => `           ${line}`);
+    const headerLines = [
         statusLine,
         '',
-        `${compose.field === 'summary' && compose.editing ? '>' : ' '} Summary: ${compose.summary || '<empty>'}${summaryCursor}`,
+        summaryFirst,
+        ...summaryRest,
         `${compose.field === 'body' && compose.editing ? '>' : ' '} Body:`,
-        ...bodyLines.map((line) => `  ${line}${bodyCursor && line === bodyLines[bodyLines.length - 1] ? bodyCursor : ''}`),
+        ...bodyVisualLines.map((line, index) => {
+            const isLast = index === bodyVisualLines.length - 1;
+            return `  ${line}${bodyCursor && isLast ? bodyCursor : ''}`;
+        }),
         '',
-        loading
-            ? 'Working...'
-            : compose.editing
-                ? 'Enter/tab edits fields, Esc exits edit mode.'
-                : 'e edit | c commit | I AI draft',
+    ];
+    const trailerLines = [
         ...(compose.message ? ['', compose.message] : []),
         ...(compose.details || []).map((line) => `  ${line}`),
     ];
+    const stateLine = compose.editing
+        ? 'Enter/tab edits fields, Esc exits edit mode.'
+        : 'e edit | c commit | I AI draft';
     return h(Box, {
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
         flexDirection: 'column',
         width,
         paddingX: 1,
-    }, h(Text, { bold: true }, panelTitle('Commit', focused)), ...lines.map((line, index) => h(Text, {
-        key: `commit-${index}`,
+    }, h(Text, { bold: true }, panelTitle('Commit', focused)), ...headerLines.map((line, index) => h(Text, {
+        key: `commit-header-${index}`,
         dimColor: index < 2 || line.startsWith('  ') || line === '<empty>',
+    }, truncate$1(line, width - 4))), loading
+        ? h(Text, {
+            key: 'commit-loading',
+            bold: true,
+            color: theme.noColor ? undefined : theme.colors.accent,
+        }, truncate$1(theme.ascii ? '[...] Generating AI draft' : '⏳ Generating AI draft…', width - 4))
+        : h(Text, { key: 'commit-state', dimColor: true }, truncate$1(stateLine, width - 4)), ...trailerLines.map((line, index) => h(Text, {
+        key: `commit-trailer-${index}`,
+        dimColor: line.startsWith('  '),
     }, truncate$1(line, width - 4))));
 }
 function renderConfirmationPanel(h, components, state, width, theme, focused) {
@@ -19967,13 +22694,17 @@ function renderConfirmationPanel(h, components, state, width, theme, focused) {
         ? 'Revert selected hunk'
         : state.pendingMutationConfirmation === 'revert-file'
             ? 'Revert selected file'
-            : undefined;
+            : state.pendingMutationConfirmation === 'discard-draft'
+                ? 'Quit and discard the in-progress commit draft'
+                : undefined;
     const label = action?.label || mutationLabel || 'Workflow action';
-    const warning = state.pendingMutationConfirmation
-        ? 'This discards local changes and cannot be undone by Coco.'
-        : action?.kind === 'ai'
-            ? `AI action requires confirmation. Estimated ${action.estimatedTokens || '<unknown>'} tokens.`
-            : 'Destructive Git action requires confirmation.';
+    const warning = state.pendingMutationConfirmation === 'discard-draft'
+        ? 'You have an unsaved commit draft. Press y to discard it and quit.'
+        : state.pendingMutationConfirmation
+            ? 'This discards local changes and cannot be undone by Coco.'
+            : action?.kind === 'ai'
+                ? `AI action requires confirmation. Estimated ${action.estimatedTokens || '<unknown>'} tokens.`
+                : 'Destructive Git action requires confirmation.';
     return h(Box, {
         borderColor: focusBorderColor(theme, focused),
         borderStyle: theme.borderStyle,
@@ -19982,6 +22713,78 @@ function renderConfirmationPanel(h, components, state, width, theme, focused) {
         paddingX: 1,
     }, h(Text, { bold: true }, panelTitle('Confirm', focused)), h(Text, undefined, truncate$1(label, width - 4)), h(Text, { dimColor: true }, truncate$1(warning, width - 4)), h(Text, undefined, ''), h(Text, undefined, 'Press y to confirm or n/Esc to cancel.'));
 }
+/**
+ * First-launch onboarding overlay (P1.3). Shown once per machine, gated
+ * by an XDG-style cache marker so subsequent launches go straight to the
+ * normal UI. Auto-dismisses on the next keystroke.
+ *
+ * Replaces the whole layout for the first render rather than overlaying
+ * a transient banner — Ink doesn't support floating elements, and a full
+ * takeover keeps the message readable on small terminals while still
+ * being instantly dismissible.
+ */
+function renderOnboardingOverlay(h, components, rows, columns, theme, appLabel) {
+    const { Box, Text } = components;
+    const accent = theme.noColor ? undefined : theme.colors.accent;
+    const tips = [
+        { keys: '?', text: 'open the help panel' },
+        { keys: ':', text: 'open the command palette' },
+        { keys: 'g h', text: 'jump to history (g s status, g d diff, g c compose, g b branches, g t tags, g z stash)' },
+        { keys: '<  esc', text: 'pop the navigation stack / go back' },
+        { keys: '/', text: 'filter the active list' },
+        { keys: 'q  ctrl+c', text: 'quit' },
+    ];
+    const maxKeys = tips.reduce((max, tip) => Math.max(max, tip.keys.length), 0);
+    const lineWidth = Math.max(40, columns - 4);
+    return h(Box, {
+        flexDirection: 'column',
+        height: rows,
+        paddingX: 2,
+        paddingY: 1,
+    }, h(Text, { bold: true, color: accent }, `Welcome to ${appLabel}`), h(Text, { dimColor: true }, 'A quick keyboard tour — press any key to dismiss.'), h(Text, undefined, ''), ...tips.map((tip, index) => h(Text, { key: `onboarding-tip-${index}` }, h(Text, { color: accent, bold: true }, `  ${tip.keys.padEnd(maxKeys)}  `), h(Text, undefined, truncate$1(tip.text, lineWidth - maxKeys - 4)))), h(Text, undefined, ''), h(Text, { dimColor: true }, 'This tip is shown once per machine. Press any key to continue.'));
+}
+/**
+ * Which-key style chord overlay (P1.1). When the user presses a chord
+ * prefix (currently just `g`), the dispatcher sets `state.pendingKey`
+ * and waits for the second key. This panel surfaces the available
+ * continuations so newcomers don't have to memorize the chord set.
+ *
+ * Renders in the detail panel slot; auto-dismisses when the chord
+ * completes or `pendingKey` is otherwise cleared.
+ */
+function renderChordOverlay(h, components, state, width, theme, focused) {
+    const { Box, Text } = components;
+    const prefix = state.pendingKey || '';
+    const continuations = getLogInkChordContinuations(prefix);
+    const accent = theme.noColor ? undefined : theme.colors.accent;
+    const lines = [
+        h(Text, { key: 'chord-title', bold: true }, panelTitle(`${prefix} … jump`, focused)),
+        h(Text, { key: 'chord-spacer' }, ''),
+    ];
+    if (continuations.length === 0) {
+        lines.push(h(Text, {
+            key: 'chord-empty',
+            dimColor: true,
+        }, truncate$1(`No bindings registered for the ${prefix} prefix.`, width - 4)));
+    }
+    else {
+        for (const entry of continuations) {
+            lines.push(h(Text, { key: `chord-${entry.key}` }, h(Text, { color: accent, bold: true }, `  ${entry.key}  `), h(Text, undefined, truncate$1(`${entry.label.padEnd(10)} ${entry.description}`, width - 9))));
+        }
+    }
+    lines.push(h(Text, { key: 'chord-foot-spacer' }, ''));
+    lines.push(h(Text, {
+        key: 'chord-hint',
+        dimColor: true,
+    }, truncate$1('press the second key to jump · esc cancels', width - 4)));
+    return h(Box, {
+        borderColor: focusBorderColor(theme, focused),
+        borderStyle: theme.borderStyle,
+        flexDirection: 'column',
+        width,
+        paddingX: 1,
+    }, ...lines);
+}
 function renderHelpPanel(h, components, state, width, theme, focused) {
     const { Box, Text } = components;
     const children = [
@@ -20056,16 +22859,20 @@ function renderCommandPalette(h, components, state, width, theme, focused) {
         ? [h(Text, { key: 'palette-recent-hint', dimColor: true }, '· marks recently-used')]
         : []), ...itemLines);
 }
-function renderFooter(h, components, state, theme) {
+function renderFooter(h, components, state, theme, idleTip) {
     const { Box, Text } = components;
     const hints = getLogInkFooterHints({
         activeView: state.activeView,
         filterMode: state.filterMode,
         focus: state.focus,
+        pendingKey: state.pendingKey,
         showCommandPalette: state.showCommandPalette,
         showHelp: state.showHelp,
     });
-    const status = state.statusMessage ? `  ${state.statusMessage}` : '';
+    // Real status messages always win; idle tips only fill the slot when it
+    // would otherwise be empty.
+    const trailing = state.statusMessage || idleTip || '';
+    const status = trailing ? `  ${trailing}` : '';
     const contextualText = `${hints.contextual.join('   ')}${status}`;
     const globalText = hints.global.join(' · ');
     return h(Box, {
@@ -20106,6 +22913,7 @@ async function startCocoUiFromLogArgv(logArgv, options = {}) {
     const rows = options.rows || (await getLogRows(git, logArgv));
     await startInkInteractiveLog(git, rows, {}, {
         appLabel: 'coco ui',
+        idleTips: config.logTui?.idleTips,
         initialView: 'history',
         logArgv,
         theme: config.logTui?.theme,
@@ -20118,6 +22926,7 @@ async function startCocoUi(argv) {
     const rows = await getLogRows(git, logArgv);
     await startInkInteractiveLog(git, rows, {}, {
         appLabel: 'coco ui',
+        idleTips: config.logTui?.idleTips,
         initialView: argv.view || 'history',
         logArgv,
         theme: createUiTheme(config, argv),
@@ -21166,6 +23975,7 @@ y.command(changelog.command, changelog.desc, changelog.builder, changelog.handle
 y.command(recap.command, recap.desc, recap.builder, recap.handler);
 y.command(review.command, review.desc, review.builder, review.handler);
 y.command(init.command, init.desc, init.builder, init.handler);
+y.command(doctor.command, doctor.desc, doctor.builder, doctor.handler);
 y.command(log.command, log.desc, log.builder, log.handler);
 y.command(ui.command, ui.desc, ui.builder, ui.handler);
 y.help().parse(process.argv.slice(2));
@@ -21621,6 +24431,7 @@ var commitValidationHandler = /*#__PURE__*/Object.freeze({
 
 exports.changelog = changelog;
 exports.commit = commit;
+exports.doctor = doctor;
 exports.init = init;
 exports.log = log;
 exports.recap = recap;