fpasoterm 1.6.0

package/bin/fpasoterm

@@ -0,0 +1,2882 @@
+#!/usr/bin/env node
+
+const { spawn, spawnSync } = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const readline = require('node:readline/promises');
+const toml = require('smol-toml');
+
+const root = path.resolve(__dirname, '..');
+const {
+  configPath,
+  defaultConfigExample,
+  deleteWindowState,
+  discoverPluginFiles,
+  loadConfig,
+  mergeConfig,
+  missingConfigKeys,
+  pluginMetadata,
+  readPluginMetadata,
+  readUserConfig,
+  resolvePluginSelector,
+  selectProfileConfig,
+  platformDefaultConfig,
+  profileNames,
+  validateUserConfig,
+  writableConfigDefaults,
+  pruneUnsupportedConfig,
+  writeUserConfig,
+} = require(path.join(root, 'src', 'config'));
+const packageJson = require(path.join(root, 'package.json'));
+const launcherStartedAt = Number(process.env.FPASOTERM_LAUNCH_STARTED_AT) || Date.now();
+const launcherLogPath = process.env.FPASOTERM_LAUNCHER_LOG || path.join(
+  process.platform === 'win32'
+    ? (process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'))
+    : (process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache')),
+  'fpasoterm',
+  'launcher.log',
+);
+
+const helpText = `Usage: fpasoterm [options]
+
+Options:
+  -h, --help                    Show this help.
+  -v, --version                 Show the version and source commit.
+      --update-check             Compare the installed version with npm latest, then exit.
+      --completion <shell>      Print a completion script: bash, zsh, fish, or powershell.
+      --completion-install <shell>
+                                Install persistent command completion for a shell.
+      --completion-uninstall <shell>
+                                Remove fpasoterm's persistent command completion.
+  -l, --list                    List running fpasoterm windows, then exit.
+  -q, --close <pid|title|all>   Close windows by PID, exact title, or all.
+      --broadcast <text>        Send text plus Enter to running local terminal windows.
+      --broadcast-target <pid|title>
+                                Limit Broadcast targets (comma-separated/repeatable).
+      --broadcast-sync          Also send Broadcast through the trusted sync channel.
+  -d, --dev                     Force a local debug-binary rebuild and launch.
+  -F, --foreground              Keep the launcher attached to the current console.
+  -C, --console-diagnostics     Print diagnostics to stderr as well as the log file.
+  -c, --config <path>           Use a specific config.toml for this launch.
+  -p, --profile <name>          Apply a named [profiles.<name>] overlay for this launch.
+      --profile-list            List available named profiles, then exit.
+      --show-config             Print resolved settings and plugin load status, then exit.
+      --config-check             Validate config.toml and report warnings, then exit.
+      --config-path              Print the active config.toml path, then exit.
+      --config-example           Print the active config.toml.example contents, then exit.
+      --diagnostics              Print a Markdown diagnostics report, then exit.
+      --doctor                   Check updates, npm audit, and config health, then exit.
+      --open-log-dir             Open the configured terminal log directory, then exit.
+      --copy-diagnostics         Copy the Markdown diagnostics report to the clipboard, then exit.
+      --plugin-list             List local User/plugins files and enabled plugins, then exit.
+      --plugin-path             Print the active User/plugins directory, then exit.
+      --plugin-info <file>      Show a .js/.ts plugin's state, version, source, and load status.
+      --plugin-uninstall <file> Remove comma-separated local User/plugins files, then exit.
+      --plugin-search [query]   Search official public plugin ports, then exit.
+      --plugin-install <port>   Install one port from GitHub, or --plugin-ports-dir when supplied.
+      --plugin-ports-dir <path> Use this local fpasoterm-plugins checkout with --plugin-install.
+      --plugin-install-file <path>
+                                Copy one trusted local .js/.ts plugin into User/plugins.
+      --force                   Replace an existing file during a plugin install.
+      --enable                  Enable a plugin installed by one --plugin-install command.
+      --update-config           Add missing default settings and back up config.toml, then exit.
+      --prune-config            Remove unsupported settings and back up config.toml, then exit.
+      --setup-sync              Ask questions and configure a local sync folder, then exit.
+      --sync-status             Report sync-folder health, command state, and channels, then exit.
+      --sync-clean              Remove expired sync commands and abandoned temporary files, then exit.
+      --sync-diagnostics        Print a Markdown sync diagnostic report, then exit.
+      --self-update             Update an npm-installed fpasoterm package, then refresh desktop files on Linux.
+      --self-update-checkout    Update a clean git checkout with git pull, npm install, and desktop refresh.
+      --update-desktop          Reinstall the local command, desktop entry, and launcher icons, then exit.
+  -s, --shell <command>         Override the configured shell for this launch.
+  -o, --cwd <path>              Start the terminal in this directory. Relative paths are allowed.
+  -e, --command <command>       Send a command to the shell after launch.
+  -t, --title <text>            Override the titlebar title for this launch.
+  -b, --titlebar-color <color>  Override the custom titlebar color for this launch.
+  -r, --reset-window-state      Delete saved window size, then exit.
+  -R, --reset-config            Rename config.toml, restore defaults and default size, then exit.
+      --enable-plugin <names>   Enable plugin files by name (comma-separated/repeatable), then exit.
+      --disable-plugin <names>  Disable plugin files by name (comma-separated/repeatable), then exit.
+      --plugin-enable-all       Enable every discovered User/plugins .js/.ts file, then exit.
+      --plugin-disable-all      Disable every plugin without deleting plugin files, then exit.
+      --plugin-enable <names>   Alias for --enable-plugin.
+      --plugin-disable <names>  Alias for --disable-plugin.
+                                Local selectors may omit plugins/ and .js/.ts when unambiguous.
+  -W, --width <px>              Override the configured window width for this launch.
+  -H, --height <px>             Override the configured window height for this launch.
+  -z, --size <width>x<height>   Override both window dimensions for this launch.
+  -k, --debug-keys              Enable key/composition diagnostics.
+      --disable-dmabuf          Set WEBKIT_DISABLE_DMABUF_RENDERER=1 for Linux WebKitGTK diagnostics.
+
+Normal launches build and run the local Tauri binary when needed, then detach
+from the console so the shell prompt is available again.
+Use --foreground when you want the command to wait for the app process.
+
+Completion usage:
+  fpasoterm --completion-install bash
+  fpasoterm --completion-uninstall bash
+  Supported shell values: bash, zsh, fish, powershell
+
+Profile usage:
+  1. Find config: fpasoterm --config-path
+  2. Add to config.toml:
+       [profiles.large-font.terminal]
+       fontSize = 18
+  3. Launch: fpasoterm --profile large-font
+  List names: fpasoterm --profile-list
+  Sample file: --config examples/config/profiles.toml --profile large-font
+  Docs: docs/config.en.md#profiles and docs/config.ja.md#profile
+`;
+
+// Appends diagnostics for launcher/icon starts where stdout and stderr are hidden.
+function appendLauncherLog(message) {
+  try {
+    fs.mkdirSync(path.dirname(launcherLogPath), { recursive: true });
+    fs.appendFileSync(launcherLogPath, `${message}\n`);
+  } catch {
+    // Launcher diagnostics must never prevent the app from starting.
+  }
+}
+
+// Records elapsed launcher time without keeping the invoking shell attached.
+function appendLaunchPhase(phase) {
+  appendLauncherLog(`launcher phase=${phase} elapsed_ms=${Date.now() - launcherStartedAt}`);
+}
+
+// Converts CLI options into environment variables consumed by the main process.
+function parseArgs(argv) {
+  validateArgs(argv);
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    return { help: true };
+  }
+  if (argv.includes('--version') || argv.includes('-v')) {
+    return { help: false, version: true };
+  }
+  if (argv.includes('--update-check')) {
+    return { help: false, version: false, updateCheck: true };
+  }
+  const pluginSearchIndex = argv.indexOf('--plugin-search');
+  if (pluginSearchIndex >= 0) {
+    const query = argv[pluginSearchIndex + 1];
+    return { help: false, version: false, pluginSearch: query && !query.startsWith('-') ? query : '' };
+  }
+
+  const env = {};
+  const runtimeArgs = [];
+  const enablePlugins = [];
+  const disablePlugins = [];
+  let enableAllPlugins = false;
+  let disableAllPlugins = false;
+  let foreground = false;
+  let dev = false;
+  let completionShell = '';
+  let completionInstallShell = '';
+  let completionUninstallShell = '';
+  let showConfig = false;
+  let configCheck = false;
+  let profileList = false;
+  let configPathOnly = false;
+  let configExample = false;
+  let diagnostics = false;
+  let doctor = false;
+  let openLogDir = false;
+  let copyDiagnostics = false;
+  let pluginList = false;
+  let pluginPath = false;
+  let pluginInfo = '';
+  const pluginUninstall = [];
+  let pluginInstall = '';
+  let pluginPortsDir = '';
+  let pluginInstallFile = '';
+  let pluginInstallForce = false;
+  let pluginInstallEnable = false;
+  let listInstances = false;
+  let closeTarget = '';
+  let setupSync = false;
+  let syncStatus = false;
+  let syncClean = false;
+  let syncDiagnostics = false;
+  let broadcastText = '';
+  const broadcastTargets = [];
+  let broadcastSync = false;
+  let resetWindowState = false;
+  let resetConfig = false;
+  let updateConfig = false;
+  let pruneConfig = false;
+  let selfUpdate = false;
+  let selfUpdateCheckout = false;
+  let updateDesktop = false;
+  let startCommand = '';
+  let updateCheck = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--foreground' || arg === '-F') {
+      foreground = true;
+      continue;
+    }
+
+    if (arg === '--dev' || arg === '-d') {
+      dev = true;
+      continue;
+    }
+
+    if (arg === '--completion') {
+      completionShell = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--completion-install') {
+      completionInstallShell = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--completion-uninstall') {
+      completionUninstallShell = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--show-config') {
+      showConfig = true;
+      continue;
+    }
+
+    if (arg === '--config-check') {
+      configCheck = true;
+      continue;
+    }
+
+    if (arg === '--profile-list') {
+      profileList = true;
+      continue;
+    }
+
+    if (arg === '--config-path') {
+      configPathOnly = true;
+      continue;
+    }
+
+    if (arg === '--config-example') {
+      configExample = true;
+      continue;
+    }
+
+    if (arg === '--diagnostics') {
+      diagnostics = true;
+      continue;
+    }
+
+    if (arg === '--doctor') {
+      doctor = true;
+      continue;
+    }
+
+    if (arg === '--open-log-dir') {
+      openLogDir = true;
+      continue;
+    }
+
+    if (arg === '--copy-diagnostics') {
+      copyDiagnostics = true;
+      continue;
+    }
+
+    if (arg === '--plugin-list') {
+      pluginList = true;
+      continue;
+    }
+
+    if (arg === '--plugin-path') {
+      pluginPath = true;
+      continue;
+    }
+
+    if (arg === '--plugin-info') {
+      pluginInfo = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--plugin-uninstall') {
+      pluginUninstall.push(...parsePluginSelectors(requireValue(argv, index, arg), arg));
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--plugin-install') {
+      pluginInstall = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--plugin-ports-dir') {
+      pluginPortsDir = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--plugin-install-file') {
+      pluginInstallFile = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--force') {
+      pluginInstallForce = true;
+      continue;
+    }
+
+    if (arg === '--enable') {
+      pluginInstallEnable = true;
+      continue;
+    }
+
+    if (arg === '--list' || arg === '-l') {
+      listInstances = true;
+      continue;
+    }
+
+    if (arg === '--close' || arg === '-q') {
+      closeTarget = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--setup-sync') {
+      setupSync = true;
+      continue;
+    }
+
+    if (arg === '--sync-status') {
+      syncStatus = true;
+      continue;
+    }
+
+    if (arg === '--sync-clean') {
+      syncClean = true;
+      continue;
+    }
+
+    if (arg === '--sync-diagnostics') {
+      syncDiagnostics = true;
+      continue;
+    }
+
+    if (arg === '--broadcast') {
+      broadcastText = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--broadcast-target') {
+      broadcastTargets.push(...parseBroadcastSelectors(requireValue(argv, index, arg), arg));
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--broadcast-sync') {
+      broadcastSync = true;
+      continue;
+    }
+
+    if (arg === '--self-update') {
+      selfUpdate = true;
+      continue;
+    }
+
+    if (arg === '--update-check') {
+      updateCheck = true;
+      continue;
+    }
+
+    if (arg === '--self-update-checkout') {
+      selfUpdateCheckout = true;
+      continue;
+    }
+
+    if (arg === '--update-desktop') {
+      updateDesktop = true;
+      continue;
+    }
+
+    if (arg === '--reset-window-state' || arg === '-r') {
+      resetWindowState = true;
+      continue;
+    }
+
+    if (arg === '--reset-config' || arg === '-R') {
+      resetConfig = true;
+      continue;
+    }
+
+    if (arg === '--update-config') {
+      updateConfig = true;
+      continue;
+    }
+
+    if (arg === '--prune-config') {
+      pruneConfig = true;
+      continue;
+    }
+
+    if (arg === '--command' || arg === '-e') {
+      startCommand = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--shell' || arg === '-s') {
+      env.FPASOTERM_SHELL = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--cwd' || arg === '-o') {
+      const directory = path.resolve(requireValue(argv, index, arg));
+      let metadata;
+      try {
+        metadata = fs.statSync(directory);
+      } catch (error) {
+        throw new Error(`${arg} directory is unavailable: ${error.message}`);
+      }
+      if (!metadata.isDirectory()) {
+        throw new Error(`${arg} must name an existing directory`);
+      }
+      env.FPASOTERM_START_CWD = directory;
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--title' || arg === '-t') {
+      env.FPASOTERM_WINDOW_TITLE = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--titlebar-color' || arg === '-b') {
+      env.FPASOTERM_TITLEBAR_COLOR = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--enable-plugin' || arg === '--plugin-enable') {
+      enablePlugins.push(...parsePluginSelectors(requireValue(argv, index, arg), arg));
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--disable-plugin' || arg === '--plugin-disable') {
+      disablePlugins.push(...parsePluginSelectors(requireValue(argv, index, arg), arg));
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--plugin-enable-all') {
+      enableAllPlugins = true;
+      continue;
+    }
+
+    if (arg === '--plugin-disable-all') {
+      disableAllPlugins = true;
+      continue;
+    }
+
+    if (arg === '--console-diagnostics' || arg === '-C') {
+      env.FPASOTERM_CONSOLE_DIAGNOSTICS = '1';
+      continue;
+    }
+
+    if (arg === '--debug-keys' || arg === '-k') {
+      env.FPASOTERM_DEBUG_KEYS = '1';
+      continue;
+    }
+
+    if (arg === '--disable-dmabuf') {
+      env.FPASOTERM_DISABLE_DMABUF = '1';
+      env.WEBKIT_DISABLE_DMABUF_RENDERER = '1';
+      continue;
+    }
+
+    if (arg === '--config' || arg === '-c') {
+      env.FPASOTERM_CONFIG_PATH = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--profile' || arg === '-p') {
+      env.FPASOTERM_PROFILE = requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--width' || arg === '-W') {
+      env.FPASOTERM_WINDOW_WIDTH = requirePositiveInteger(requireValue(argv, index, arg), arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--height' || arg === '-H') {
+      env.FPASOTERM_WINDOW_HEIGHT = requirePositiveInteger(requireValue(argv, index, arg), arg);
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--size' || arg === '-z') {
+      const value = requireValue(argv, index, arg);
+      const match = value.match(/^(\d+)x(\d+)$/i);
+      if (!match) {
+        throw new Error(`${arg} must be formatted as <width>x<height>`);
+      }
+      env.FPASOTERM_WINDOW_WIDTH = requirePositiveInteger(match[1], '--width');
+      env.FPASOTERM_WINDOW_HEIGHT = requirePositiveInteger(match[2], '--height');
+      index += 1;
+      continue;
+    }
+
+    throw new Error(arg.startsWith('-')
+      ? `unknown option: ${arg}`
+      : `unexpected argument: ${arg}`);
+  }
+
+  if (enableAllPlugins && disableAllPlugins) {
+    throw new Error('--plugin-enable-all and --plugin-disable-all cannot be used together');
+  }
+  if ((broadcastTargets.length > 0 || broadcastSync) && !broadcastText) {
+    throw new Error('--broadcast-target and --broadcast-sync require --broadcast <text>');
+  }
+  const pluginInstallCount = [pluginInstall, pluginInstallFile].filter(Boolean).length;
+  if (pluginInstallCount > 1) {
+    throw new Error('use only one of --plugin-install or --plugin-install-file');
+  }
+  if ((pluginInstallForce || pluginInstallEnable) && pluginInstallCount === 0) {
+    throw new Error('--force and --enable require a --plugin-install command');
+  }
+  if (pluginPortsDir && !pluginInstall) {
+    throw new Error('--plugin-ports-dir requires --plugin-install <category/name>');
+  }
+  if (pluginUninstall.length > 0 && (
+    enablePlugins.length > 0 || disablePlugins.length > 0 || enableAllPlugins || disableAllPlugins || pluginInstallCount > 0
+  )) {
+    throw new Error('--plugin-uninstall cannot be combined with other plugin mutation options');
+  }
+
+  return {
+    help: false,
+    version: false,
+    foreground,
+    dev,
+    completionShell,
+    completionInstallShell,
+    completionUninstallShell,
+    showConfig,
+    configCheck,
+    profileList,
+    configPathOnly,
+    configExample,
+    diagnostics,
+    doctor,
+    openLogDir,
+    copyDiagnostics,
+    pluginList,
+    pluginPath,
+    pluginInfo,
+    pluginUninstall,
+    pluginInstall,
+    pluginPortsDir,
+    pluginInstallFile,
+    pluginInstallForce,
+    pluginInstallEnable,
+    listInstances,
+    closeTarget,
+    setupSync,
+    syncStatus,
+    syncClean,
+    syncDiagnostics,
+    broadcastText,
+    broadcastTargets,
+    broadcastSync,
+    resetWindowState,
+    resetConfig,
+    updateConfig,
+    pruneConfig,
+    selfUpdate,
+    updateCheck,
+    selfUpdateCheckout,
+    updateDesktop,
+    env: {
+      ...env,
+      ...(startCommand ? { FPASOTERM_START_COMMAND: startCommand } : {}),
+    },
+    startCommand,
+    enablePlugins,
+    disablePlugins,
+    enableAllPlugins,
+    disableAllPlugins,
+    runtimeArgs,
+  };
+}
+
+// Rejects unknown options before help/version handling can bypass validation.
+function validateArgs(argv) {
+  const flags = new Set([
+    '--help', '-h', '--version', '-v', '--list', '-l', '--dev', '-d', '--foreground', '-F',
+    '--console-diagnostics', '-C', '--show-config', '--config-check', '--config-path', '--config-example',
+    '--diagnostics', '--doctor', '--open-log-dir', '--copy-diagnostics', '--profile-list', '--plugin-list', '--plugin-path', '--plugin-search', '--setup-sync', '--sync-status', '--sync-clean', '--sync-diagnostics', '--self-update',
+    '--self-update-checkout', '--update-desktop', '--update-check', '--reset-window-state', '-r', '--reset-config', '-R',
+    '--update-config',
+    '--prune-config', '--plugin-enable-all', '--plugin-disable-all', '--force', '--enable',
+    '--debug-keys', '-k', '--disable-dmabuf', '--broadcast-sync',
+  ]);
+  const valueOptions = new Set([
+    '--config', '-c', '--profile', '-p', '--shell', '-s', '--cwd', '-o', '--command', '-e', '--title', '-t',
+    '--titlebar-color', '-b', '--close', '-q', '--enable-plugin', '--disable-plugin', '--plugin-enable', '--plugin-disable', '--plugin-info', '--plugin-uninstall', '--width', '-W',
+    '--height', '-H', '--size', '-z', '--broadcast', '--broadcast-target', '--completion',
+    '--completion-install', '--completion-uninstall', '--plugin-install', '--plugin-ports-dir', '--plugin-install-file',
+  ]);
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--plugin-search') {
+      if (argv[index + 1] && !argv[index + 1].startsWith('-')) index += 1;
+      continue;
+    }
+    if (flags.has(arg)) {
+      continue;
+    }
+    if (valueOptions.has(arg)) {
+      requireValue(argv, index, arg);
+      index += 1;
+      continue;
+    }
+    throw new Error(arg.startsWith('-')
+      ? `unknown option: ${arg}`
+      : `unexpected argument: ${arg}`);
+  }
+}
+
+// Prints the package version and the checkout commit without starting the desktop process.
+function printVersion() {
+  console.log(versionText());
+}
+
+// Returns one stable build identifier for CLI output and diagnostics reports.
+function versionText() {
+  if (fs.existsSync(path.join(root, '.jj'))) {
+    const jjResult = spawnSync('jj', ['-R', root, 'log', '-r', '@', '--no-graph', '-T', 'commit_id.short(12)'], {
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    if (jjResult.status === 0 && jjResult.stdout.trim()) {
+      return `fpasoterm ${packageJson.version} (commit ${jjResult.stdout.trim()})`;
+    }
+  }
+  const gitResult = spawnSync('git', ['-C', root, 'rev-parse', '--short=12', 'HEAD'], {
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  const commit = gitResult.status === 0 ? gitResult.stdout.trim() : 'unknown';
+  return `fpasoterm ${packageJson.version} (commit ${commit})`;
+}
+
+// Compares stable npm package versions without making normal help/version calls network-bound.
+function comparePackageVersions(left, right) {
+  const parse = (value) => String(value).split('.').map((part) => Number.parseInt(part, 10));
+  const leftParts = parse(left);
+  const rightParts = parse(right);
+  if (leftParts.length !== 3 || rightParts.length !== 3 || [...leftParts, ...rightParts].some(Number.isNaN)) {
+    throw new Error(`cannot compare package versions: ${left} and ${right}`);
+  }
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) {
+      return leftParts[index] - rightParts[index];
+    }
+  }
+  return 0;
+}
+
+// Queries npm only for an explicit update check so ordinary CLI commands stay fast offline.
+async function checkForUpdate() {
+  const response = await fetch('https://registry.npmjs.org/fpasoterm/latest', {
+    headers: { accept: 'application/json', 'user-agent': `fpasoterm/${packageJson.version}` },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!response.ok) {
+    throw new Error(`npm registry returned HTTP ${response.status}`);
+  }
+  const metadata = await response.json();
+  const latest = String(metadata?.version || '');
+  if (!/^\d+\.\d+\.\d+$/.test(latest)) {
+    throw new Error('npm registry did not return a stable latest version');
+  }
+  const comparison = comparePackageVersions(packageJson.version, latest);
+  console.log(`installed: ${versionText()}`);
+  console.log(`latest npm release: ${latest}`);
+  if (comparison < 0) {
+    console.log('status: update available');
+    console.log('update: fpasoterm --self-update');
+  } else if (comparison === 0) {
+    console.log('status: up to date');
+  } else {
+    console.log('status: local build is newer than npm latest');
+  }
+}
+
+// Runs npm audit without modifying dependencies and summarizes JSON output for doctor reports.
+function npmAuditSummary() {
+  try {
+    const npm = npmInvocation(['audit', '--omit=dev', '--json']);
+    const result = spawnSync(npm.command, npm.args, {
+      cwd: root,
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    if (result.error) return { status: 'unavailable', detail: result.error.message };
+    const report = JSON.parse(result.stdout || '{}');
+    const vulnerabilities = report.metadata?.vulnerabilities || {};
+    const total = Number(vulnerabilities.total || 0);
+    return {
+      status: total === 0 && result.status === 0 ? 'ok' : 'warnings',
+      detail: `total=${total} low=${vulnerabilities.low || 0} moderate=${vulnerabilities.moderate || 0} high=${vulnerabilities.high || 0} critical=${vulnerabilities.critical || 0}`,
+    };
+  } catch (error) {
+    return { status: 'unavailable', detail: String(error.message || error) };
+  }
+}
+
+// Prints a read-only maintenance report; updates remain an explicit --self-update action.
+async function runDoctor(options) {
+  applyEnv(options.env);
+  const config = validateUserConfig(configPath());
+  console.log('## fpasoterm doctor');
+  console.log('');
+  console.log(`- version: ${versionText()}`);
+  console.log(`- config: ${config.configPath}`);
+  console.log(`- config status: ${config.error ? 'error' : 'ok'}`);
+  for (const warning of config.warnings) console.log(`- config warning: ${warning}`);
+  if (config.error) console.log(`- config error: ${config.error}`);
+
+  try {
+    const response = await fetch('https://registry.npmjs.org/fpasoterm/latest', {
+      headers: { accept: 'application/json', 'user-agent': `fpasoterm/${packageJson.version}` },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) throw new Error(`npm registry returned HTTP ${response.status}`);
+    const latest = String((await response.json())?.version || '');
+    const comparison = comparePackageVersions(packageJson.version, latest);
+    console.log(`- npm latest: ${latest}`);
+    console.log(`- update: ${comparison < 0 ? 'available; run fpasoterm --self-update' : comparison === 0 ? 'up to date' : 'local build is newer'}`);
+  } catch (error) {
+    console.log(`- update: unavailable (${error.message || error})`);
+  }
+
+  const audit = npmAuditSummary();
+  console.log(`- npm audit: ${audit.status} (${audit.detail})`);
+  console.log('');
+  console.log('Doctor is read-only. Review findings, then run --self-update or fix config.toml explicitly.');
+}
+
+// Searches public port metadata only; source is neither downloaded nor executed.
+async function searchPublicPlugins(query) {
+  const response = await fetch('https://raw.githubusercontent.com/oyoguhito/fpasoterm-plugins/main/INDEX', {
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!response.ok) throw new Error(`public plugin index returned HTTP ${response.status}`);
+  const needle = String(query || '').trim().toLocaleLowerCase();
+  const ports = (await response.text()).split(/\r?\n/).filter(Boolean).map((line) => line.split('|'))
+    .filter((fields) => fields.length === 8)
+    .filter((fields) => fields.slice(0, 5).join(' ').toLocaleLowerCase().includes(needle));
+  process.stdout.write(`Public plugins${needle ? ` matching "${query}"` : ''}:\nsource: remote official INDEX (oyoguhito/fpasoterm-plugins)\n`);
+  if (ports.length === 0) return process.stdout.write('  (none)\n');
+  for (const [id, name, version, author, description, , minimum] of ports) {
+    process.stdout.write(`  ${id} (${name} ${version}, ${author}, requires >= ${minimum})\n    ${description}\n    install: fpasoterm --plugin-install ${id} --enable\n`);
+  }
+}
+
+// Validates a public catalog ID before it is used to construct a fixed-repository URL.
+function validatePublicPluginPortId(value) {
+  const id = String(value || '').trim();
+  const parts = id.split('/');
+  if (parts.length < 2 || parts.some((part) => !/^[A-Za-z0-9_-]+$/.test(part))) {
+    throw new Error(`invalid public plugin port '${value}'; use a category/name identifier`);
+  }
+  return parts.join('/');
+}
+
+// Downloads bounded UTF-8 metadata or source only from the official public ports repository.
+async function fetchPublicPluginText(relativePath, maximumBytes) {
+  const response = await fetch(`https://raw.githubusercontent.com/oyoguhito/fpasoterm-plugins/main/${relativePath}`, {
+    headers: { accept: 'text/plain', 'user-agent': `fpasoterm/${packageJson.version}` },
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!response.ok) throw new Error(`public plugin download returned HTTP ${response.status}`);
+  const contentLength = Number(response.headers.get('content-length') || 0);
+  if (contentLength > maximumBytes) throw new Error(`public plugin download exceeds ${maximumBytes} bytes`);
+  const text = await response.text();
+  if (Buffer.byteLength(text, 'utf8') > maximumBytes) {
+    throw new Error(`public plugin download exceeds ${maximumBytes} bytes`);
+  }
+  return text;
+}
+
+// Parses and validates the narrow port manifest contract shared by remote and local sources.
+function parsePluginPortManifest(id, manifestText, label) {
+  const manifest = toml.parse(manifestText)?.port;
+  const required = (key) => {
+    const value = typeof manifest?.[key] === 'string' ? manifest[key].trim() : '';
+    if (!value) throw new Error(`${label} port manifest is missing port.${key}`);
+    return value;
+  };
+  if (required('id') !== id) throw new Error(`${label} port manifest id mismatch: requested ${id}`);
+  const version = required('version');
+  const minimumVersion = required('minFpasotermVersion');
+  const sourceName = required('source');
+  const installPath = required('installPath').replaceAll('\\', '/');
+  if (!/^\d+\.\d+\.\d+$/.test(version) || !/^\d+\.\d+\.\d+$/.test(minimumVersion)) {
+    throw new Error(`${label} port manifest has an invalid version`);
+  }
+  if (comparePackageVersions(packageJson.version, minimumVersion) < 0) {
+    throw new Error(`${id} requires fpasoterm >= ${minimumVersion}; found ${packageJson.version}`);
+  }
+  if (!/^[^/\\]+\.(?:js|ts)$/.test(sourceName)
+    || !/^(?:[A-Za-z0-9_-]+\/)+[A-Za-z0-9_-]+\.(?:js|ts)$/.test(installPath)) {
+    throw new Error(`${label} port manifest has an unsafe source or install path`);
+  }
+  return { version, sourceName, installPath };
+}
+
+// Writes one reviewed source into User/plugins without following an existing symlink.
+function installPluginSource(options, source, installPath, origin, version) {
+  if (!source.includes(`@fpasoterm-plugin version: ${version}`)
+    || !source.includes('window.fpasotermPluginApi')) {
+    throw new Error(`${origin} does not contain a valid fpasoterm plugin header`);
+  }
+
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const pluginsDirectory = path.join(path.dirname(targetPath), 'plugins');
+  fs.mkdirSync(pluginsDirectory, { recursive: true });
+  const destination = path.resolve(pluginsDirectory, installPath);
+  if (!destination.startsWith(`${path.resolve(pluginsDirectory)}${path.sep}`)) {
+    throw new Error('public port destination escapes User/plugins');
+  }
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  if (fs.existsSync(destination)) {
+    const metadata = fs.lstatSync(destination);
+    if (metadata.isSymbolicLink()) throw new Error(`refusing to replace symlinked plugin ${destination}`);
+    if (!metadata.isFile()) throw new Error(`cannot replace non-file plugin ${destination}`);
+    if (!options.pluginInstallForce) {
+      throw new Error(`${destination} already exists; review it and rerun with --force to replace it`);
+    }
+  }
+  const temporary = `${destination}.fpasoterm-download-${process.pid}.tmp`;
+  fs.writeFileSync(temporary, source, 'utf8');
+  try {
+    fs.renameSync(temporary, destination);
+  } catch (error) {
+    if (fs.existsSync(destination) && options.pluginInstallForce) {
+      fs.unlinkSync(destination);
+      fs.renameSync(temporary, destination);
+    } else {
+      throw error;
+    }
+  }
+
+  const plugin = `plugins/${installPath}`;
+  console.log(`installed ${origin} -> ${plugin}`);
+  if (options.pluginInstallEnable) {
+    const userConfig = readUserConfig(targetPath);
+    const plugins = userConfig.plugins && typeof userConfig.plugins === 'object' ? userConfig.plugins : {};
+    const enabled = new Set(Array.isArray(plugins.enabled) ? plugins.enabled : []);
+    enabled.add(plugin);
+    writeUserConfig({ ...userConfig, plugins: { ...plugins, enabled: [...enabled].sort() } }, targetPath);
+    console.log(`enabled installed plugin in ${targetPath}`);
+  } else {
+    console.log(`review the source, then enable it with: fpasoterm --plugin-enable ${installPath.replace(/\.(?:js|ts)$/, '')}`);
+  }
+  console.log('Restart fpasoterm to load the installed plugin selection.');
+}
+
+// Installs one reviewed public port without starting Cargo or the native desktop runtime.
+async function installPublicPlugin(options) {
+  const id = validatePublicPluginPortId(options.pluginInstall);
+  const manifestText = await fetchPublicPluginText(`ports/${id}/port.toml`, 64 * 1024);
+  const { version, sourceName, installPath } = parsePluginPortManifest(id, manifestText, 'public');
+  const source = await fetchPublicPluginText(`ports/${id}/${sourceName}`, 1024 * 1024);
+  installPluginSource(options, source, installPath, `public port ${id}`, version);
+}
+
+// Resolves a local ports checkout from an explicit path, environment, or sibling repository.
+function localPluginPortsDirectory(options) {
+  const directory = path.resolve(options.pluginPortsDir || '');
+  if (!options.pluginPortsDir || !fs.existsSync(path.join(directory, 'ports'))) {
+    throw new Error('local fpasoterm-plugins checkout not found; pass --plugin-ports-dir <path>');
+  }
+  return directory;
+}
+
+// Reads a bounded regular local file so an arbitrary path cannot be followed through a symlink.
+function readLocalPluginText(filePath, maximumBytes, label) {
+  const metadata = fs.lstatSync(filePath, { throwIfNoEntry: false });
+  if (!metadata || !metadata.isFile() || metadata.isSymbolicLink()) {
+    throw new Error(`${label} must be a regular file`);
+  }
+  if (metadata.size > maximumBytes) throw new Error(`${label} exceeds ${maximumBytes} bytes`);
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+// Installs a port from a checked-out fpasoterm-plugins tree for local development and review.
+function installLocalPluginPort(options) {
+  const id = validatePublicPluginPortId(options.pluginInstall);
+  const portsDirectory = localPluginPortsDirectory(options);
+  const portDirectory = path.join(portsDirectory, 'ports', ...id.split('/'));
+  const manifestText = readLocalPluginText(path.join(portDirectory, 'port.toml'), 64 * 1024, 'local port manifest');
+  const { version, sourceName, installPath } = parsePluginPortManifest(id, manifestText, 'local');
+  const source = readLocalPluginText(path.join(portDirectory, sourceName), 1024 * 1024, 'local plugin source');
+  installPluginSource(options, source, installPath, `local port ${id}`, version);
+}
+
+// Copies one explicit, trusted local renderer plugin without needing a ports checkout.
+function installLocalPluginFile(options) {
+  const filePath = path.resolve(options.pluginInstallFile);
+  if (!/\.(?:js|ts)$/i.test(filePath)) throw new Error('--plugin-install-file requires a .js or .ts file');
+  const source = readLocalPluginText(filePath, 1024 * 1024, 'local plugin source');
+  const version = pluginMetadata(source).version;
+  if (!version || version === '(not declared)') {
+    throw new Error('local plugin source must declare // @fpasoterm-plugin version: <version>');
+  }
+  installPluginSource(options, source, path.basename(filePath), `local plugin ${path.basename(filePath)}`, version);
+}
+
+// Prints a shell-specific completion script without resolving or launching the app runtime.
+function printCompletion(shell) {
+  const fileNames = {
+    bash: 'fpasoterm.bash',
+    zsh: '_fpasoterm',
+    fish: 'fpasoterm.fish',
+    powershell: 'fpasoterm.ps1',
+  };
+  const normalized = String(shell || '').toLowerCase();
+  const fileName = fileNames[normalized];
+  if (!fileName) {
+    throw new Error(`unsupported completion shell: ${shell} (expected bash, zsh, fish, or powershell)`);
+  }
+  process.stdout.write(fs.readFileSync(path.join(root, 'completions', fileName), 'utf8'));
+}
+
+// Normalizes and validates shell names shared by completion output and file management.
+function completionFileName(shell) {
+  const fileNames = {
+    bash: 'fpasoterm.bash',
+    zsh: '_fpasoterm',
+    fish: 'fpasoterm.fish',
+    powershell: 'fpasoterm.ps1',
+  };
+  const normalized = String(shell || '').toLowerCase();
+  if (!fileNames[normalized]) {
+    throw new Error(`unsupported completion shell: ${shell} (expected bash, zsh, fish, or powershell)`);
+  }
+  return { shell: normalized, fileName: fileNames[normalized] };
+}
+
+// Resolves a user-owned location so install and uninstall never alter system completion files.
+function completionInstallPath(shell) {
+  const normalized = completionFileName(shell).shell;
+  if (normalized === 'bash') {
+    return path.join(process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'), 'bash-completion', 'completions', 'fpasoterm');
+  }
+  if (normalized === 'zsh') {
+    return path.join(os.homedir(), '.zfunc', '_fpasoterm');
+  }
+  if (normalized === 'fish') {
+    return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'fish', 'completions', 'fpasoterm.fish');
+  }
+  if (process.platform !== 'win32') {
+    throw new Error('powershell completion installation is supported on Windows only');
+  }
+  return path.join(path.dirname(configPath()), 'completions', 'fpasoterm.ps1');
+}
+
+// Decodes the UTF-16LE profile path represented as ASCII-safe Base64 by PowerShell.
+function decodePowerShellProfilePath(encodedPath) {
+  const bytes = Buffer.from(encodedPath, 'base64');
+  if (bytes.length === 0 || bytes.length % 2 !== 0) {
+    return '';
+  }
+  return bytes.toString('utf16le').replace(/^\uFEFF/, '');
+}
+
+// Asks every available Windows PowerShell host for its profile path rather than assuming Documents is not redirected.
+function powershellProfilePaths() {
+  const profiles = new Map();
+  for (const command of ['pwsh.exe', 'powershell.exe']) {
+    const result = spawnSync(command, ['-NoProfile', '-Command', '[Convert]::ToBase64String([System.Text.Encoding]::Unicode.GetBytes($PROFILE.CurrentUserCurrentHost))'], {
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    if (result.status === 0 && result.stdout.trim()) {
+      const profilePath = decodePowerShellProfilePath(result.stdout.trim());
+      if (profilePath) {
+        profiles.set(profilePath.toLowerCase(), profilePath);
+      }
+    }
+  }
+  if (profiles.size > 0) {
+    return [...profiles.values()];
+  }
+  throw new Error('PowerShell was not found; install it or use --completion powershell manually');
+}
+
+const powershellCompletionStart = '# >>> fpasoterm completion >>>';
+const powershellCompletionEnd = '# <<< fpasoterm completion <<<';
+
+// Escapes marker text before using it to identify fpasoterm's profile block.
+function escapeRegularExpression(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Removes only the managed block, preserving every other user PowerShell profile setting.
+function updatePowershellProfile(profilePath, scriptPath) {
+  const existing = fs.existsSync(profilePath) ? fs.readFileSync(profilePath, 'utf8') : '';
+  const block = new RegExp(`\\r?\\n?${escapeRegularExpression(powershellCompletionStart)}[\\s\\S]*?${escapeRegularExpression(powershellCompletionEnd)}\\r?\\n?`, 'g');
+  const hadManagedBlock = existing.includes(powershellCompletionStart);
+  const withoutExistingBlock = existing.replace(block, '').replace(/\n{3,}/g, '\n\n').trimEnd();
+  if (scriptPath === null) {
+    if (hadManagedBlock && !withoutExistingBlock) {
+      fs.unlinkSync(profilePath);
+    } else if (hadManagedBlock) {
+      fs.writeFileSync(profilePath, withoutExistingBlock ? `${withoutExistingBlock}\n` : '', 'utf8');
+    }
+    return;
+  }
+  fs.mkdirSync(path.dirname(profilePath), { recursive: true });
+  const escapedPath = scriptPath.replace(/'/g, "''");
+  const managedBlock = `${powershellCompletionStart}\n. '${escapedPath}'\n${powershellCompletionEnd}\n`;
+  fs.writeFileSync(profilePath, `${withoutExistingBlock}${withoutExistingBlock ? '\n\n' : ''}${managedBlock}`, 'utf8');
+}
+
+// Installs a completion file for later shell sessions without launching the app runtime.
+function installCompletion(shell) {
+  const { shell: normalized, fileName } = completionFileName(shell);
+  const targetPath = completionInstallPath(normalized);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.copyFileSync(path.join(root, 'completions', fileName), targetPath);
+  if (normalized === 'powershell') {
+    const profilePaths = powershellProfilePaths();
+    for (const profilePath of profilePaths) {
+      updatePowershellProfile(profilePath, targetPath);
+    }
+    console.log(`updated PowerShell profile${profilePaths.length === 1 ? '' : 's'}: ${profilePaths.join(', ')}`);
+    console.log('restart PowerShell, or run: . $PROFILE');
+    console.log('if scripts are blocked: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned');
+  }
+  console.log(`installed ${normalized} completion: ${targetPath}`);
+}
+
+// Deletes just fpasoterm's installed completion and its managed PowerShell profile block.
+function uninstallCompletion(shell) {
+  const { shell: normalized } = completionFileName(shell);
+  const targetPath = completionInstallPath(normalized);
+  if (normalized === 'powershell') {
+    for (const profilePath of powershellProfilePaths()) {
+      updatePowershellProfile(profilePath, null);
+    }
+  }
+  if (fs.existsSync(targetPath)) {
+    fs.unlinkSync(targetPath);
+    console.log(`removed ${normalized} completion: ${targetPath}`);
+  } else {
+    console.log(`${normalized} completion is not installed: ${targetPath}`);
+  }
+}
+
+// Returns the runtime marker directory shared with the native application.
+function instanceMarkerDirectory() {
+  const cacheHome = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(cacheHome, 'fpasoterm', 'instances');
+}
+
+// Returns the local command directory shared with the native Broadcast watcher.
+function localBroadcastCommandDirectory() {
+  const cacheHome = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(cacheHome, 'fpasoterm', 'broadcast', 'commands');
+}
+
+// Checks whether a marker PID still belongs to a running process.
+function instanceProcessIsLive(pid) {
+  if (process.platform === 'linux') {
+    return fs.existsSync(`/proc/${pid}`);
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+// Best-effort cleanup must not prevent a read-only instance listing.
+function removeStaleInstanceMarker(markerPath) {
+  try {
+    fs.rmSync(markerPath, { force: true });
+  } catch {
+    // Read-only cache mounts can still be inspected even when cleanup is denied.
+  }
+}
+
+// Reads live native per-process markers and removes stale entries when possible.
+function runningInstances() {
+  const directory = instanceMarkerDirectory();
+  const instances = [];
+  if (fs.existsSync(directory)) {
+    for (const name of fs.readdirSync(directory).filter((entry) => entry.endsWith('.pid')).sort()) {
+      const markerPath = path.join(directory, name);
+      try {
+        const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+        const pid = Number(marker.pid || path.basename(name, '.pid'));
+        if (!Number.isInteger(pid) || pid <= 0 || !instanceProcessIsLive(pid)) {
+          removeStaleInstanceMarker(markerPath);
+          continue;
+        }
+        instances.push({
+          id: String(marker.instanceId || ''),
+          pid,
+          title: String(marker.title || marker.baseTitle || 'fpasoterm'),
+          createdAt: Number(marker.createdAt || 0),
+        });
+      } catch {
+        removeStaleInstanceMarker(markerPath);
+      }
+    }
+  }
+
+  instances.sort((left, right) => left.createdAt - right.createdAt || left.pid - right.pid);
+  return instances;
+}
+
+// Lists running windows from the native per-process markers without launching the GUI.
+function printRunningInstances() {
+  const instances = runningInstances();
+  if (instances.length === 0) {
+    console.log('No running fpasoterm windows.');
+    return;
+  }
+  for (const instance of instances) {
+    const started = instance.createdAt > 0 ? new Date(instance.createdAt).toISOString() : 'unknown';
+    console.log(`session=${instance.pid} pid=${instance.pid} title=${JSON.stringify(instance.title)} started=${started}`);
+  }
+}
+
+// Publishes one complete command file so running terminal watchers never read partial JSON.
+function writeBroadcastItem(directory, item) {
+  fs.mkdirSync(directory, { recursive: true });
+  const baseName = `command-${item.id}`;
+  const temporaryPath = path.join(directory, `${baseName}.tmp`);
+  const commandPath = path.join(directory, `${baseName}.json`);
+  fs.writeFileSync(temporaryPath, JSON.stringify(item));
+  fs.renameSync(temporaryPath, commandPath);
+}
+
+// Sends a command to selected live local windows and optionally the configured sync channel.
+function broadcastTerminalInput(options) {
+  const allInstances = runningInstances().filter((instance) => instance.id);
+  if (allInstances.length === 0) {
+    throw new Error('no running fpasoterm windows were found');
+  }
+
+  const selected = new Map();
+  if (options.broadcastTargets.length === 0) {
+    allInstances.forEach((instance) => selected.set(instance.id, instance));
+  } else {
+    for (const selector of options.broadcastTargets) {
+      const numericPid = /^\d+$/.test(selector) ? Number(selector) : undefined;
+      const matches = allInstances.filter((instance) => (
+        numericPid === undefined ? instance.title === selector : instance.pid === numericPid
+      ));
+      if (matches.length === 0) {
+        throw new Error(`no running window matches Broadcast target ${JSON.stringify(selector)}`);
+      }
+      matches.forEach((instance) => selected.set(instance.id, instance));
+    }
+  }
+
+  if (options.broadcastSync && selected.size !== allInstances.length) {
+    throw new Error('--broadcast-sync requires every running local window to be selected');
+  }
+
+  const text = `${options.broadcastText.replace(/\r\n?/g, '\n').replace(/\n/g, '\r').replace(/\r+$/, '')}\r`;
+  const status = syncStatusReport(options);
+  const bytes = Buffer.byteLength(text, 'utf8');
+  if (bytes > status.maxBytes) {
+    throw new Error(`broadcast payload is too large: ${bytes} bytes > ${status.maxBytes} bytes`);
+  }
+  if (options.broadcastSync && !status.commandsEnabled) {
+    throw new Error('sync commands are disabled or commandSecret is missing; run fpasoterm --setup-sync');
+  }
+  if (options.broadcastSync && !status.enabled) {
+    throw new Error(status.message);
+  }
+
+  const createdAt = Date.now();
+  const item = {
+    schemaVersion: 1,
+    id: `cli-${process.pid}-${createdAt}`,
+    sourceId: `cli-${process.pid}`,
+    createdAt,
+    expiresAt: createdAt + status.commandTtlMs,
+    text,
+    targetInstanceIds: [...selected.keys()],
+  };
+  if (options.broadcastSync) {
+    item.signature = signSyncBroadcastItem(item, status.commandSecret);
+  }
+  writeBroadcastItem(localBroadcastCommandDirectory(), item);
+  if (options.broadcastSync) {
+    writeBroadcastItem(status.commandsPath, item);
+  }
+  console.log(`broadcast: sent id=${item.id} local_targets=${selected.size} synced=${options.broadcastSync}`);
+}
+
+// Keeps the HMAC payload stable across Node CLI and the Rust desktop runtime.
+function syncBroadcastSignaturePayload(item) {
+  return JSON.stringify({
+    schemaVersion: item.schemaVersion,
+    id: item.id,
+    sourceId: item.sourceId,
+    createdAt: item.createdAt,
+    expiresAt: item.expiresAt,
+    text: item.text,
+    targetInstanceIds: item.targetInstanceIds,
+  });
+}
+
+// Signs only commands intentionally sent to a trusted sync folder.
+function signSyncBroadcastItem(item, commandSecret) {
+  return crypto.createHmac('sha256', commandSecret)
+    .update(syncBroadcastSignaturePayload(item), 'utf8')
+    .digest('hex');
+}
+
+// Atomically broadcasts a graceful close request by PID, exact title, or all.
+function closeRunningInstance(target) {
+  const normalizedTarget = String(target || '').trim();
+  const closeAll = normalizedTarget.toLowerCase() === 'all';
+  const numericPid = /^\d+$/.test(normalizedTarget) ? Number(normalizedTarget) : null;
+  const matches = runningInstances().filter((instance) => (
+    closeAll || (numericPid === null ? instance.title === normalizedTarget : instance.pid === numericPid)
+  ));
+  if (matches.length === 0) {
+    throw new Error(`no running window matches: ${normalizedTarget}`);
+  }
+
+  const cacheDirectory = path.dirname(instanceMarkerDirectory());
+  fs.mkdirSync(cacheDirectory, { recursive: true });
+  const requestPath = path.join(cacheDirectory, 'close.json');
+  const temporaryPath = path.join(cacheDirectory, `close-${process.pid}.json.tmp`);
+  fs.writeFileSync(temporaryPath, JSON.stringify({
+    createdAt: Date.now(),
+    pids: matches.map((instance) => instance.pid),
+  }));
+  removeStaleInstanceMarker(requestPath);
+  fs.renameSync(temporaryPath, requestPath);
+  for (const instance of matches) {
+    console.log(`requested close session=${instance.pid} pid=${instance.pid} title=${JSON.stringify(instance.title)}`);
+  }
+}
+
+// Resolves npm through its JavaScript entry point when available. This avoids
+// invoking npm.cmd through a shell on Windows, which Node deprecates (DEP0190).
+function npmInvocation(args) {
+  const bundledNpmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+  const npmCli = [process.env.npm_execpath, bundledNpmCli].find((candidate) => candidate && fs.existsSync(candidate));
+  if (npmCli) {
+    return { command: process.execPath, args: [npmCli, ...args] };
+  }
+  return { command: process.platform === 'win32' ? 'npm.cmd' : 'npm', args };
+}
+
+// Runs an update command and fails fast with a clear message.
+function runChecked(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd || root,
+    env: process.env,
+    stdio: 'inherit',
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed with exit code ${result.status}`);
+  }
+}
+
+// Returns true when this command is running from a source checkout.
+function isSourceCheckout() {
+  return fs.existsSync(path.join(root, '.git')) || fs.existsSync(path.join(root, '.jj'));
+}
+
+// Returns true for jj workspaces, which need explicit user-controlled updates.
+function isJjCheckout() {
+  return fs.existsSync(path.join(root, '.jj'));
+}
+
+// Checks whether a git checkout is clean before automated pull/update work.
+function ensureCleanGitCheckout() {
+  const result = spawnSync('git', ['status', '--porcelain'], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error('git status failed; refusing to self-update this checkout');
+  }
+  if (result.stdout.trim()) {
+    throw new Error('checkout has local changes; commit, stash, or update manually before --self-update-checkout');
+  }
+}
+
+// Reinstalls desktop integration from the currently running package root.
+function updateDesktopIntegration() {
+  runChecked(process.execPath, [path.join(root, 'scripts', 'install-linux-desktop.js')]);
+}
+
+// Updates an npm-installed package. Source checkouts are intentionally not pulled.
+function selfUpdate() {
+  if (isSourceCheckout()) {
+    console.log('source checkout detected; not running npm global self-update from this tree');
+    console.log('Use --self-update-checkout for a clean git checkout, or update manually and run:');
+    console.log('  fpasoterm --update-desktop');
+    return;
+  }
+
+  const npm = npmInvocation(['install', '-g', 'fpasoterm@latest']);
+  runChecked(npm.command, npm.args);
+  if (process.platform === 'linux' && fs.existsSync(path.join(root, 'scripts', 'install-linux-desktop.js'))) {
+    updateDesktopIntegration();
+  }
+  console.log('fpasoterm updated. Restart fpasoterm to use the updated app.');
+}
+
+// Updates a clean non-jj git checkout and refreshes its desktop integration.
+function selfUpdateCheckout() {
+  if (!fs.existsSync(path.join(root, '.git'))) {
+    throw new Error('--self-update-checkout requires a git checkout');
+  }
+  if (isJjCheckout()) {
+    console.log('jj checkout detected; automatic checkout updates are intentionally disabled.');
+    console.log('Update with your jj workflow, then run:');
+    console.log('  npm install');
+    console.log('  fpasoterm --update-desktop');
+    return;
+  }
+
+  ensureCleanGitCheckout();
+  runChecked('git', ['pull', '--ff-only']);
+  const npm = npmInvocation(['install']);
+  runChecked(npm.command, npm.args);
+  updateDesktopIntegration();
+  console.log('checkout updated. Restart fpasoterm to use the updated app.');
+}
+
+// Reads the value after a flag and reports a CLI-friendly error when missing.
+function requireValue(argv, index, flag) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith('--')) {
+    if (['--completion', '--completion-install', '--completion-uninstall'].includes(flag)) {
+      throw new Error(`${flag} requires a shell: bash, zsh, fish, or powershell (example: fpasoterm ${flag} bash)`);
+    }
+    throw new Error(`${flag} requires a value`);
+  }
+  return value;
+}
+
+// Normalizes dimension arguments before they are passed to the app process.
+function requirePositiveInteger(value, flag) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${flag} must be a positive integer`);
+  }
+  return String(parsed);
+}
+
+// Splits a comma-separated plugin argument while preserving repeated options.
+function parsePluginSelectors(value, flag) {
+  const selectors = value.split(',').map((entry) => entry.trim()).filter(Boolean);
+  if (selectors.length === 0) {
+    throw new Error(`${flag} requires at least one plugin name`);
+  }
+  return selectors;
+}
+
+// Splits explicit Broadcast target selectors without accepting empty entries.
+function parseBroadcastSelectors(value, flag) {
+  const selectors = value.split(',').map((entry) => entry.trim()).filter(Boolean);
+  if (selectors.length === 0) {
+    throw new Error(`${flag} requires at least one PID or exact title`);
+  }
+  return selectors;
+}
+
+// Applies environment overrides while running config-only CLI commands.
+function applyEnv(env) {
+  for (const [key, value] of Object.entries(env)) {
+    process.env[key] = value;
+  }
+}
+
+// Updates plugins.enabled in config.toml without launching the application.
+function updatePluginConfig(options) {
+  if (
+    options.enablePlugins.length === 0 &&
+    options.disablePlugins.length === 0 &&
+    !options.enableAllPlugins &&
+    !options.disableAllPlugins
+  ) {
+    return false;
+  }
+
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const userConfig = readUserConfig(targetPath);
+  const plugins = userConfig.plugins && typeof userConfig.plugins === 'object' ? userConfig.plugins : {};
+  const enabled = new Set(Array.isArray(plugins.enabled) ? plugins.enabled : []);
+  const available = discoverPluginFiles(targetPath);
+
+  if (options.enableAllPlugins) {
+    for (const plugin of available) {
+      enabled.add(plugin);
+    }
+  }
+
+  if (options.disableAllPlugins) {
+    enabled.clear();
+  }
+
+  for (const selector of options.enablePlugins) {
+    enabled.add(resolvePluginSelector(selector, available, 'enable'));
+  }
+
+  for (const selector of options.disablePlugins) {
+    const plugin = resolvePluginSelector(selector, [...enabled], 'disable');
+    enabled.delete(plugin);
+  }
+
+  writeUserConfig({
+    ...userConfig,
+    plugins: {
+      ...plugins,
+      enabled: [...enabled].sort(),
+    },
+  }, targetPath);
+
+  console.log(`updated ${targetPath}`);
+  const runtimeConfig = loadConfig();
+  printPluginList(targetPath, [...enabled].sort(), runtimeConfig.pluginUrls);
+  console.log('Restart fpasoterm to load the updated plugin selection.');
+  return true;
+}
+
+// Removes selected local plugin sources, their generated cache entries, and enabled-list references.
+function uninstallLocalPlugins(options) {
+  if (options.pluginUninstall.length === 0) {
+    return false;
+  }
+
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const configDir = path.dirname(targetPath);
+  const pluginsDir = path.resolve(configDir, 'plugins');
+  const pluginRoot = `${pluginsDir}${path.sep}`;
+  const available = discoverPluginFiles(targetPath);
+  const selected = [...new Set(options.pluginUninstall.map((selector) => (
+    resolvePluginSelector(selector, available, 'uninstall')
+  )))];
+  const sources = selected.map((plugin) => {
+    const sourcePath = path.resolve(configDir, plugin);
+    if (!sourcePath.startsWith(pluginRoot)) {
+      throw new Error(`refusing to uninstall plugin outside User/plugins: ${plugin}`);
+    }
+    const metadata = fs.lstatSync(sourcePath);
+    if (metadata.isSymbolicLink()) {
+      throw new Error(`refusing to uninstall symlinked plugin: ${plugin}`);
+    }
+    if (!metadata.isFile()) {
+      throw new Error(`cannot uninstall plugin '${plugin}': source is not a regular file`);
+    }
+    const relativeName = path.relative(pluginsDir, sourcePath);
+    return {
+      plugin,
+      sourcePath,
+      cachePath: path.join(configDir, 'cache', 'plugins', relativeName).replace(/\.ts$/, '.js'),
+    };
+  });
+
+  for (const { sourcePath, cachePath } of sources) {
+    fs.unlinkSync(sourcePath);
+    if (fs.existsSync(cachePath)) {
+      const cacheMetadata = fs.lstatSync(cachePath);
+      if (!cacheMetadata.isSymbolicLink() && cacheMetadata.isFile()) {
+        fs.unlinkSync(cachePath);
+      }
+    }
+  }
+
+  const userConfig = readUserConfig(targetPath);
+  const plugins = userConfig.plugins && typeof userConfig.plugins === 'object' ? userConfig.plugins : {};
+  const removed = new Set(selected);
+  const enabled = (Array.isArray(plugins.enabled) ? plugins.enabled : [])
+    .filter((plugin) => !removed.has(plugin));
+  writeUserConfig({
+    ...userConfig,
+    plugins: {
+      ...plugins,
+      enabled,
+    },
+  }, targetPath);
+
+  for (const { plugin } of sources) {
+    console.log(`uninstalled local plugin ${plugin}`);
+  }
+  console.log(`updated ${targetPath}`);
+  console.log('Restart fpasoterm to unload the removed plugin from open windows.');
+  return true;
+}
+
+// Prints the resolved config and which configured plugins can be loaded.
+function showConfig(options) {
+  applyEnv(options.env);
+  const runtimeConfig = loadConfig();
+  applyWindowRuntimeOverrides(runtimeConfig.config.window, options.env);
+  applyTerminalRuntimeOverrides(runtimeConfig.config.terminal, options.env);
+  const enabled = Array.isArray(runtimeConfig.config.plugins?.enabled) ? runtimeConfig.config.plugins.enabled : [];
+
+  console.log(`Config path: ${runtimeConfig.configPath}`);
+  console.log(`Config directory: ${runtimeConfig.configDir}`);
+  console.log(`Active profile: ${runtimeConfig.activeProfile || '(none)'}`);
+  console.log('');
+  console.log('Resolved config:');
+  const displayConfig = {
+    ...runtimeConfig.config,
+    sync: {
+      ...runtimeConfig.config.sync,
+      commandSecret: '[redacted]',
+    },
+  };
+  process.stdout.write(toml.stringify(displayConfig));
+  console.log('');
+  printPluginList(runtimeConfig.configPath, enabled, runtimeConfig.pluginUrls);
+}
+
+// Prints validation results without rewriting or resolving the user's config.
+function checkConfig(options) {
+  applyEnv(options.env);
+  const result = validateUserConfig(configPath());
+  console.log(`config: ${result.configPath}`);
+  if (result.error) {
+    console.log('status: error');
+    console.log('');
+    console.log('errors:');
+    console.log(`- ${result.error}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log('status: ok');
+  if (result.warnings.length > 0) {
+    console.log('');
+    console.log('warnings:');
+    for (const warning of result.warnings) {
+      console.log(`- ${warning}`);
+    }
+  }
+}
+
+// Prints the selected config path without creating files or opening a window.
+function showConfigPath(options) {
+  applyEnv(options.env);
+  console.log(configPath());
+}
+
+// Prints the generated example so it can be redirected to a chosen TOML file.
+function showConfigExample(options) {
+  applyEnv(options.env);
+  process.stdout.write(defaultConfigExample());
+}
+
+// Lists profile names without resolving plugins or opening a terminal window.
+function showProfileList(options) {
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const names = profileNames(readUserConfig(targetPath));
+  console.log('Available profiles:');
+  if (names.length === 0) {
+    console.log('  (none found)');
+    return;
+  }
+  const active = process.env.FPASOTERM_PROFILE || '';
+  for (const name of names) {
+    console.log(`  ${name}${name === active ? ' [selected]' : ''}`);
+  }
+}
+
+// Resolves the local log directory using the same empty-directory default as the runtime.
+function configuredLogDirectory(targetPath, userConfig) {
+  const configured = typeof userConfig.logging?.directory === 'string'
+    ? expandHome(userConfig.logging.directory)
+    : '';
+  return configured || path.join(path.dirname(targetPath), 'logs');
+}
+
+// Formats static launcher information as a GitHub Issue-friendly Markdown report.
+function diagnosticsMarkdown(options) {
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const checked = validateUserConfig(targetPath);
+  const userConfig = checked.error ? {} : readUserConfig(targetPath);
+  const resolved = mergeConfig(platformDefaultConfig(), userConfig);
+  const enabledPlugins = Array.isArray(userConfig.plugins?.enabled) ? userConfig.plugins.enabled : [];
+  const logDirectory = configuredLogDirectory(targetPath, userConfig);
+  const windowState = (() => {
+    const statePath = path.join(path.dirname(targetPath), 'window-state.json');
+    try {
+      return fs.existsSync(statePath) ? JSON.parse(fs.readFileSync(statePath, 'utf8')).window : undefined;
+    } catch {
+      return undefined;
+    }
+  })();
+  const size = windowState?.width && windowState?.height
+    ? `${windowState.width}x${windowState.height} (saved)`
+    : `${resolved.window.width}x${resolved.window.height} (configured)`;
+
+  return [
+    '## fpasoterm diagnostics',
+    '',
+    `- version: ${versionText()}`,
+    `- platform: ${process.platform} ${process.arch}`,
+    '- webview: Tauri WebView (reported by launcher)',
+    `- config path: ${targetPath}`,
+    `- config status: ${checked.error ? 'error' : 'ok'}`,
+    `- profile: ${process.env.FPASOTERM_PROFILE || '(none)'}`,
+    `- plugins: ${enabledPlugins.length > 0 ? enabledPlugins.join(', ') : '(none enabled)'}`,
+    `- terminal size: ${size}`,
+    `- terminal font size: ${resolved.terminal.fontSize}`,
+    `- logging: ${resolved.logging?.enabled === false ? 'disabled' : 'enabled'} (${logDirectory})`,
+    `- sync: ${resolved.sync?.enabled ? `enabled (${resolved.sync.provider || 'folder'}:${resolved.sync.channel || 'default'})` : 'disabled'}`,
+    `- debug log: ${path.join(path.dirname(targetPath), 'logs', 'fpasoterm-debug.log')}`,
+    ...(checked.error ? ['', '### configuration errors', `- ${checked.error}`] : []),
+    ...(checked.warnings.length > 0 ? ['', '### configuration warnings', ...checked.warnings.map((warning) => `- ${warning}`)] : []),
+    '',
+  ].join('\n');
+}
+
+// Opens the local log folder with the operating system's file manager.
+function openLogDirectory(options) {
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const checked = validateUserConfig(targetPath);
+  if (checked.error) {
+    throw new Error(checked.error);
+  }
+  const directory = configuredLogDirectory(targetPath, readUserConfig(targetPath));
+  fs.mkdirSync(directory, { recursive: true });
+  const command = process.platform === 'win32' ? 'explorer.exe' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+  const child = spawn(command, [directory], { detached: true, stdio: 'ignore', windowsHide: true });
+  child.unref();
+  console.log(directory);
+}
+
+// Writes the diagnostics report through platform clipboard tools without opening a window.
+function copyDiagnostics(options) {
+  const report = diagnosticsMarkdown(options);
+  const commands = process.platform === 'win32'
+    ? [['powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', 'Set-Clipboard -Value ([Console]::In.ReadToEnd())']]]
+    : process.platform === 'darwin'
+      ? [['pbcopy', []]]
+      : [['wl-copy', ['--type', 'text/plain;charset=utf-8']], ['xclip', ['-selection', 'clipboard', '-target', 'UTF8_STRING']], ['xsel', ['--clipboard', '--input']]];
+  const errors = [];
+  for (const [command, args] of commands) {
+    const result = spawnSync(command, args, { input: report, encoding: 'utf8', windowsHide: true });
+    if (!result.error && result.status === 0) {
+      console.log('copied diagnostics to clipboard');
+      return;
+    }
+    errors.push(result.error?.message || `${command} exited with ${result.status}`);
+  }
+  throw new Error(`could not copy diagnostics: ${errors.join('; ')}`);
+}
+
+// Clears remembered window bounds without touching config.toml.
+function resetWindowState(options) {
+  applyEnv(options.env);
+  const runtimeConfig = loadConfig();
+  deleteWindowState(runtimeConfig.windowStatePath);
+  console.log(`deleted ${runtimeConfig.windowStatePath}`);
+}
+
+// Renames the selected config.toml, restores defaults, and clears saved bounds.
+function resetConfig(options) {
+  applyEnv(options.env);
+  const targetPath = configPath();
+  let backupPath = '';
+  if (fs.existsSync(targetPath)) {
+    backupPath = `${targetPath}.backup-${Date.now()}`;
+    fs.renameSync(targetPath, backupPath);
+  }
+  writeUserConfig(writableConfigDefaults(), targetPath);
+  const statePath = path.join(path.dirname(targetPath), 'window-state.json');
+  deleteWindowState(statePath);
+  console.log(`reset config ${targetPath}`);
+  if (backupPath) {
+    console.log(`renamed previous config ${backupPath}`);
+  }
+  console.log(`deleted saved window state ${statePath}`);
+}
+
+// Adds newly introduced defaults while retaining every existing user value.
+function updateConfig(options) {
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const userConfig = readUserConfig(targetPath);
+  const defaults = writableConfigDefaults();
+  const missing = missingConfigKeys(defaults, userConfig);
+  if (missing.length === 0) {
+    console.log(`config already includes all defaults: ${targetPath}`);
+    return;
+  }
+
+  let backupPath = '';
+  if (fs.existsSync(targetPath)) {
+    backupPath = `${targetPath}.backup-${Date.now()}`;
+    fs.copyFileSync(targetPath, backupPath);
+  }
+  writeUserConfig(mergeConfig(defaults, userConfig), targetPath);
+  console.log(`updated ${targetPath}`);
+  console.log(`added ${missing.length} default setting(s)`);
+  if (backupPath) {
+    console.log(`backed up previous config ${backupPath}`);
+  }
+}
+
+// Removes obsolete configuration keys while retaining every supported value.
+function pruneConfigFile(options) {
+  applyEnv(options.env);
+  const targetPath = configPath();
+  if (!fs.existsSync(targetPath)) {
+    console.log(`config does not exist: ${targetPath}`);
+    return;
+  }
+
+  const userConfig = readUserConfig(targetPath);
+  const result = pruneUnsupportedConfig(writableConfigDefaults(), userConfig);
+  if (result.removed.length === 0) {
+    console.log(`config has no unsupported settings: ${targetPath}`);
+    return;
+  }
+
+  const backupPath = `${targetPath}.backup-${Date.now()}`;
+  fs.copyFileSync(targetPath, backupPath);
+  writeUserConfig(result.config, targetPath);
+  console.log(`pruned ${targetPath}`);
+  console.log(`removed ${result.removed.length} unsupported setting(s): ${result.removed.join(', ')}`);
+  console.log(`backed up previous config ${backupPath}`);
+}
+
+// Prints plugin entries with load and declared-version information.
+function printPluginList(targetPath, enabled, pluginUrls = []) {
+  const configDir = path.dirname(targetPath);
+  const loadedByName = new Map(pluginUrls.map((plugin) => [plugin.name, plugin]));
+
+  console.log('');
+  console.log('Plugins:');
+  if (enabled.length === 0) {
+    console.log('  (none enabled)');
+    return;
+  }
+
+  for (const plugin of enabled) {
+    const pluginPath = path.resolve(configDir, plugin);
+    const relativeName = path.relative(configDir, pluginPath);
+    const loaded = loadedByName.get(relativeName);
+    const exists = fs.existsSync(pluginPath);
+    const status = loaded ? 'loadable' : exists ? 'not loadable' : 'missing';
+    const version = exists ? readPluginMetadata(pluginPath).version : '(not declared)';
+    console.log(`  - ${plugin} [${status}; version ${version}]${loaded ? ` -> ${loaded.url}` : ''}`);
+  }
+}
+
+// Lists every plugin file below User/plugins and the explicit enabled selection.
+function showPluginList(options) {
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const userConfig = readUserConfig(targetPath);
+  const enabled = Array.isArray(userConfig.plugins?.enabled) ? userConfig.plugins.enabled : [];
+  const available = discoverPluginFiles(targetPath);
+
+  console.log('Local plugins (User/plugins):');
+  if (available.length === 0) {
+    console.log('  (none found)');
+  } else {
+    for (const plugin of available) {
+      const metadata = readPluginMetadata(path.resolve(path.dirname(targetPath), plugin));
+      console.log(`  ${plugin} [version ${metadata.version}]`);
+    }
+  }
+
+  console.log('');
+  console.log('Enabled plugins:');
+  if (enabled.length === 0) {
+    console.log('  (none enabled)');
+  } else {
+    for (const plugin of enabled) {
+      console.log(`  ${plugin}`);
+    }
+  }
+}
+
+// Prints the active configuration's plugin directory without creating it.
+function showPluginPath(options) {
+  applyEnv(options.env);
+  console.log(path.join(path.dirname(configPath()), 'plugins'));
+}
+
+// Prints one local plugin's resolved source and load details without opening a window.
+function showPluginInfo(options) {
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const available = discoverPluginFiles(targetPath);
+  const plugin = resolvePluginSelector(options.pluginInfo, available, 'inspect');
+  const sourcePath = path.resolve(path.dirname(targetPath), plugin);
+  const userConfig = readUserConfig(targetPath);
+  const enabled = Array.isArray(userConfig.plugins?.enabled) && userConfig.plugins.enabled.includes(plugin);
+  const runtimeConfig = loadConfig();
+  const resolved = runtimeConfig.pluginUrls.find((entry) => entry.name === plugin);
+  const source = fs.readFileSync(sourcePath, 'utf8');
+  const metadata = readPluginMetadata(sourcePath);
+
+  console.log(`Plugin: ${plugin}`);
+  console.log(`State: ${enabled ? 'enabled' : 'disabled'}`);
+  console.log(`Type: ${path.extname(sourcePath) === '.ts' ? 'TypeScript' : 'JavaScript'}`);
+  console.log(`Version: ${metadata.version}`);
+  console.log(`Source: ${sourcePath}`);
+  console.log(`Description: ${metadata.description}`);
+  console.log(`Load status: ${resolved ? 'loadable' : 'not loadable'}`);
+  if (resolved) {
+    console.log(`Renderer URL: ${resolved.url}`);
+  }
+}
+
+// Expands common environment variable forms used in configuration paths.
+function expandPathVariables(inputPath) {
+  return String(inputPath || '')
+    .replace(/%([^%]+)%/g, (match, name) => process.env[name] || match)
+    .replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (match, name) => process.env[name] || match);
+}
+
+// Expands a leading ~/ and environment variables so prompts can accept portable paths.
+function expandHome(inputPath) {
+  const normalized = expandPathVariables(inputPath).trim();
+  if (normalized === '~') {
+    return os.homedir();
+  }
+  if (normalized.startsWith('~/') || normalized.startsWith('~\\')) {
+    return path.join(os.homedir(), normalized.slice(2));
+  }
+  return normalized;
+}
+
+// Returns platform-specific Google Drive folder candidates for setup prompts.
+function googleDriveCandidates() {
+  const home = os.homedir();
+  const candidates = [
+    path.join(home, 'Google Drive'),
+    path.join(home, 'GoogleDrive'),
+    path.join(home, 'MyDrive'),
+  ];
+
+  if (process.platform === 'linux') {
+    candidates.unshift('/mnt/chromeos/GoogleDrive/MyDrive');
+    candidates.unshift('/mnt/shared/GoogleDrive/MyDrive');
+    candidates.unshift('/mnt/chromeos/shared/GoogleDrive/MyDrive');
+  } else if (process.platform === 'darwin') {
+    const cloudStorage = path.join(home, 'Library', 'CloudStorage');
+    if (fs.existsSync(cloudStorage)) {
+      for (const entry of fs.readdirSync(cloudStorage)) {
+        if (entry.startsWith('GoogleDrive-')) {
+          candidates.unshift(path.join(cloudStorage, entry, 'My Drive'));
+          candidates.unshift(path.join(cloudStorage, entry));
+        }
+      }
+    }
+    candidates.push('/Volumes/GoogleDrive/My Drive');
+  } else if (process.platform === 'win32') {
+    for (const letter of 'DEFGHIJKLMNOPQRSTUVWXYZ') {
+      candidates.unshift(`${letter}:\\Google Drive`);
+      candidates.unshift(`${letter}:\\マイドライブ`);
+      candidates.unshift(`${letter}:\\My Drive`);
+    }
+    candidates.unshift('G:\\My Drive');
+    candidates.push(path.join(home, 'My Drive'));
+    candidates.push(path.join(home, 'Google Drive'));
+  }
+
+  return [...new Set(candidates)];
+}
+
+// Returns true when the current user should be able to create files in a directory.
+function canWriteDirectory(directory) {
+  try {
+    fs.accessSync(directory, fs.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Adds writable immediate subdirectories because ChromeOS often shares selected
+// Drive folders, not the whole MyDrive root, into Linux.
+function writableDriveCandidates() {
+  const expanded = [];
+  for (const candidate of googleDriveCandidates()) {
+    if (!fs.existsSync(candidate)) {
+      continue;
+    }
+    expanded.push(candidate);
+    try {
+      for (const entry of fs.readdirSync(candidate, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          expanded.push(path.join(candidate, entry.name));
+        }
+      }
+    } catch {
+      // Some provider roots are visible but not listable until fully mounted.
+    }
+  }
+  return [...new Set(expanded)].filter(canWriteDirectory);
+}
+
+// Picks the most likely writable sync root and appends the fpasoterm subdirectory.
+function defaultSyncPath() {
+  const existing = writableDriveCandidates()[0] || googleDriveCandidates().find((candidate) => fs.existsSync(candidate));
+  return path.join(existing || path.join(os.homedir(), 'Google Drive'), 'fpasoterm-sync');
+}
+
+// Returns concrete sync folder suggestions by appending fpasoterm-sync to roots.
+function syncPathCandidates() {
+  const roots = writableDriveCandidates();
+  const visibleRoots = googleDriveCandidates().filter((candidate) => fs.existsSync(candidate));
+  return [...new Set([...(roots.length > 0 ? roots : visibleRoots), ...visibleRoots])]
+    .map((candidate) => path.join(candidate, 'fpasoterm-sync'));
+}
+
+// Asks one setup question, returning the default when the user presses Enter.
+async function askQuestion(rl, question, defaultValue) {
+  const suffix = defaultValue === undefined || defaultValue === '' ? '' : ` [${defaultValue}]`;
+  const answer = (await rl.question(`${question}${suffix}: `)).trim();
+  return answer || defaultValue;
+}
+
+// Lets users choose a detected sync folder candidate by number or type a path.
+async function askSyncPath(rl, defaultValue) {
+  const candidates = syncPathCandidates();
+  if (candidates.length > 0) {
+    console.log('Detected sync folder candidates:');
+    candidates.forEach((candidate, index) => {
+      console.log(`  ${index + 1}. ${candidate}`);
+    });
+    console.log('');
+    const answer = await askQuestion(rl, 'Select sync folder candidate number or type a path', '1');
+    if (/^\d+$/.test(answer)) {
+      const index = Number(answer) - 1;
+      if (!candidates[index]) {
+        throw new Error(`unknown sync folder candidate number: ${answer}`);
+      }
+      return candidates[index];
+    }
+    return answer;
+  }
+
+  const answer = await askQuestion(rl, 'Local sync folder path or candidate number', defaultValue);
+  return answer;
+}
+
+// Parses yes/no setup answers with a default.
+function isYes(value, defaultValue = true) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!normalized) {
+    return defaultValue;
+  }
+  return ['y', 'yes', 'true', '1', 'はい'].includes(normalized);
+}
+
+// Prints Google Drive mounting guidance before asking for the local sync path.
+function printSyncSetupHelp() {
+  console.log('fpasoterm sync uses a local folder that Google Drive or another tool already syncs.');
+  console.log('It does not use Google Drive API, OAuth, API keys, or a Google Cloud project.');
+  console.log('');
+  console.log('Google Drive folder setup:');
+  console.log('- ChromeOS/Baguette: open the Files app, create folders such as Google Drive/My Drive/shared or Google Drive/My Drive/temp, right-click each folder, and choose "Share with Linux".');
+  console.log('- Then select a detected candidate such as /mnt/chromeos/shared/GoogleDrive/MyDrive/shared/fpasoterm-sync or /mnt/chromeos/shared/GoogleDrive/MyDrive/temp/fpasoterm-sync.');
+  console.log('- Some ChromeOS Linux environments expose the same shared folders as /mnt/shared/GoogleDrive/MyDrive/<folder>/fpasoterm-sync or /mnt/chromeos/GoogleDrive/MyDrive/<folder>/fpasoterm-sync.');
+  console.log('- If Linux cannot create a folder under MyDrive directly, use a subfolder that is individually shared with Linux.');
+  console.log('- macOS: install Google Drive for desktop, sign in, then use the local Google Drive folder under ~/Library/CloudStorage/GoogleDrive-*/.');
+  console.log('- Windows: install Google Drive for desktop, sign in, then use the drive/folder shown by Google Drive, often G:\\My Drive. In a source checkout, run setup as: node .\\bin\\fpasoterm --setup-sync');
+  console.log('- Linux desktop: use your chosen sync client, rclone mount, Syncthing, Dropbox, or another local synced folder.');
+  console.log('');
+  console.log('Sync channel:');
+  console.log('- A channel is a folder name used to separate sync data inside the same sync path.');
+  console.log('- Use the same channel on every machine that should share clipboard text and diagnostics.');
+  console.log('- Press Enter to keep "default" when you do not need separate work/test/personal channels.');
+  console.log('');
+}
+
+// Interactively creates or updates [sync] and [logging] in config.toml.
+async function setupSync(options) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('--setup-sync must be run from an interactive terminal');
+  }
+
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const userConfig = readUserConfig(targetPath);
+  const currentSync = userConfig.sync && typeof userConfig.sync === 'object' ? userConfig.sync : {};
+  const currentLogging = userConfig.logging && typeof userConfig.logging === 'object' ? userConfig.logging : {};
+  const defaultPath = currentSync.path || defaultSyncPath();
+  const defaultChannel = currentSync.channel || 'default';
+  const generatedCommandSecret = typeof currentSync.commandSecret === 'string' && currentSync.commandSecret.length >= 32
+    ? currentSync.commandSecret
+    : crypto.randomBytes(32).toString('hex');
+  const localDefaultLogDirectory = path.join(path.dirname(targetPath), 'logs');
+  const syncDefaultLogDirectory = currentLogging.directory || path.join(defaultPath, 'logs');
+
+  printSyncSetupHelp();
+  console.log(`Config file: ${targetPath}`);
+  console.log('');
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const syncPath = await askSyncPath(rl, defaultPath);
+    console.log('Use the same sync channel on devices that should share data. Press Enter for default.');
+    const channel = await askQuestion(rl, 'Sync channel name', defaultChannel);
+    console.log('Remote Broadcast commands require a shared secret. Copy the same value to every trusted device.');
+    const commandSecret = await askQuestion(rl, 'Sync command secret', generatedCommandSecret);
+    if (commandSecret.length < 32) {
+      throw new Error('sync command secret must contain at least 32 characters');
+    }
+    const createFolder = isYes(await askQuestion(rl, 'Create the folder if it does not exist? (Y/n)', 'Y'), true);
+    console.log(`Terminal output logs stay local by default under ${localDefaultLogDirectory}.`);
+    console.log('Answer y only when you want readable terminal output logs stored in the selected sync folder.');
+    const enableLogs = isYes(await askQuestion(rl, 'Store terminal output logs in the sync folder? (y/N)', 'N'), false);
+    const logDirectory = enableLogs
+      ? await askQuestion(rl, 'Terminal log directory', syncDefaultLogDirectory)
+      : currentLogging.directory || '';
+
+    const resolvedSyncPath = expandHome(syncPath);
+    if (!fs.existsSync(resolvedSyncPath)) {
+      if (!createFolder) {
+        throw new Error(`sync folder does not exist: ${resolvedSyncPath}`);
+      }
+      fs.mkdirSync(resolvedSyncPath, { recursive: true });
+    }
+    fs.mkdirSync(path.join(resolvedSyncPath, channel || 'default'), { recursive: true });
+    if (enableLogs) {
+      fs.mkdirSync(expandHome(logDirectory), { recursive: true });
+    }
+
+    writeUserConfig({
+      ...userConfig,
+      sync: {
+        ...currentSync,
+        enabled: true,
+        provider: 'folder',
+        path: syncPath,
+        channel: channel || 'default',
+        clipboard: currentSync.clipboard ?? true,
+        diagnostics: currentSync.diagnostics ?? true,
+        pasteRequiresConfirm: currentSync.pasteRequiresConfirm ?? true,
+        maxBytes: currentSync.maxBytes ?? 1048576,
+        commands: true,
+        commandSecret,
+        commandTtlSeconds: currentSync.commandTtlSeconds ?? 60,
+      },
+      logging: {
+        ...currentLogging,
+        enabled: currentLogging.enabled ?? true,
+        directory: logDirectory,
+        autoStart: currentLogging.autoStart ?? false,
+        maxBytes: currentLogging.maxBytes ?? 10485760,
+      },
+    }, targetPath);
+
+    console.log('');
+    console.log(`updated ${targetPath}`);
+    console.log(`sync path: ${syncPath}`);
+    console.log(`sync channel: ${channel || 'default'}`);
+    console.log('sync command authentication: HMAC-SHA-256 enabled');
+    console.log(`terminal logs: ${enableLogs ? logDirectory : 'local default unless configured later'}`);
+  } finally {
+    rl.close();
+  }
+}
+
+// Normalizes a configured sync channel to the directory name used by the backend.
+function normalizedSyncChannel(value) {
+  const normalized = String(value || 'default')
+    .trim()
+    .replace(/[^A-Za-z0-9_.-]/g, '_')
+    .replace(/^[._]+|[._]+$/g, '')
+    .slice(0, 80);
+  return normalized || 'default';
+}
+
+// Reads a file modification time in milliseconds without treating a failure as
+// an error for an informational health check.
+function modificationTimeMs(filePath) {
+  try {
+    return fs.statSync(filePath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+// Inspects one channel directory. This is intentionally read-only so status
+// does not create a folder or alter a network-synced drive.
+function inspectSyncChannel(channelPath, name, now, ttlMs) {
+  const result = {
+    name,
+    diagnosticsExists: fs.existsSync(path.join(channelPath, 'diagnostics.json')),
+    activeCommands: 0,
+    staleCommands: 0,
+    invalidCommands: 0,
+    temporaryFiles: 0,
+  };
+  const commandsPath = path.join(channelPath, 'commands');
+  let entries;
+  try {
+    entries = fs.readdirSync(commandsPath, { withFileTypes: true });
+  } catch {
+    return result;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.startsWith('command-')) {
+      continue;
+    }
+    const itemPath = path.join(commandsPath, entry.name);
+    if (entry.name.endsWith('.json')) {
+      try {
+        const item = JSON.parse(fs.readFileSync(itemPath, 'utf8'));
+        if (Number(item.expiresAt) > now) {
+          result.activeCommands += 1;
+        } else {
+          result.staleCommands += 1;
+        }
+      } catch {
+        result.invalidCommands += 1;
+      }
+    } else if (entry.name.endsWith('.tmp') && modificationTimeMs(itemPath) + ttlMs <= now) {
+      result.temporaryFiles += 1;
+    }
+  }
+  return result;
+}
+
+// Collects all direct-child channels, keeping ordinary files and log folders out.
+function inspectSyncChannels(rootPath, now, ttlMs) {
+  let entries;
+  try {
+    entries = fs.readdirSync(rootPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => inspectSyncChannel(path.join(rootPath, entry.name), entry.name, now, ttlMs))
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+// Resolves and inspects the configured sync folder without starting the desktop app.
+function syncStatusReport(options) {
+  applyEnv(options.env);
+  const targetPath = configPath();
+  const selected = selectProfileConfig(readUserConfig(targetPath));
+  const sync = mergeConfig(
+    mergeConfig(platformDefaultConfig(), selected.baseConfig),
+    selected.profileConfig,
+  ).sync || {};
+  const provider = String(sync.provider || 'folder');
+  const configuredPath = String(sync.path || '').trim();
+  const channel = normalizedSyncChannel(sync.channel);
+  const enabled = sync.enabled === true && provider === 'folder' && Boolean(configuredPath);
+  const rootPath = configuredPath ? expandHome(configuredPath) : '';
+  const diagnosticsPath = rootPath ? path.join(rootPath, channel, 'diagnostics.json') : '';
+  const commandsPath = rootPath ? path.join(rootPath, channel, 'commands') : '';
+  const now = Date.now();
+  const ttlMs = Math.min(Math.max(Number(sync.commandTtlSeconds) || 60, 1), 600) * 1000;
+  const commandSecret = typeof sync.commandSecret === 'string' ? sync.commandSecret : '';
+  const commandsEnabled = sync.commands === true && commandSecret.length >= 32;
+  const maxBytes = Number(sync.maxBytes) > 0 ? Number(sync.maxBytes) : 1048576;
+  const rootExists = Boolean(rootPath) && fs.existsSync(rootPath);
+  let rootReadable = false;
+  let rootWritable = false;
+  if (rootExists) {
+    try {
+      fs.readdirSync(rootPath);
+      rootReadable = true;
+    } catch {}
+    rootWritable = canWriteDirectory(rootPath);
+  }
+  const channels = rootExists ? inspectSyncChannels(rootPath, now, ttlMs) : [];
+  const current = channels.find((item) => item.name === channel);
+  const diagnosticsExists = Boolean(diagnosticsPath) && fs.existsSync(diagnosticsPath);
+  const diagnosticsBytes = diagnosticsExists ? fs.statSync(diagnosticsPath).size : 0;
+  const diagnosticsUpdatedAt = diagnosticsExists ? modificationTimeMs(diagnosticsPath) : 0;
+  const staleCommands = current?.staleCommands || 0;
+  const invalidCommands = current?.invalidCommands || 0;
+  const temporaryFiles = current?.temporaryFiles || 0;
+  let health = 'ok';
+  let message = 'sync folder is healthy';
+  if (!enabled) {
+    health = 'disabled';
+    message = !sync.enabled ? 'sync folder is disabled; set sync.enabled = true' : provider !== 'folder'
+      ? `unsupported sync provider: ${provider}`
+      : 'sync path is empty; set sync.path to a synced local folder';
+  } else if (!rootExists) {
+    health = 'missing';
+    message = 'sync root does not exist';
+  } else if (!rootReadable) {
+    health = 'unreadable';
+    message = 'sync root cannot be read';
+  } else if (!rootWritable) {
+    health = 'read-only';
+    message = 'sync root cannot be written';
+  } else if (staleCommands + invalidCommands + temporaryFiles > 0) {
+    health = 'cleanup recommended';
+    message = 'expired or abandoned command files were found';
+  }
+  return {
+    enabled,
+    commandsEnabled,
+    commandSecret,
+    maxBytes,
+    provider,
+    path: rootPath,
+    channel,
+    diagnosticsPath,
+    commandsPath,
+    health,
+    rootExists,
+    rootReadable,
+    rootWritable,
+    diagnosticsExists,
+    diagnosticsBytes,
+    diagnosticsUpdatedAt,
+    activeCommands: current?.activeCommands || 0,
+    staleCommands,
+    invalidCommands,
+    temporaryFiles,
+    channels,
+    commandTtlMs: ttlMs,
+    message,
+  };
+}
+
+// Makes the health check readable in a terminal and ready to paste into an issue.
+function syncStatusMarkdown(options) {
+  const status = syncStatusReport(options);
+  const lines = [
+    '## fpasoterm sync status',
+    '',
+    `- status: ${status.enabled ? 'enabled' : 'disabled'}`,
+    `- health: ${status.health}`,
+    `- provider: ${status.provider}`,
+    `- path: ${status.path || '(not configured)'}`,
+    `- channel: ${status.channel || '(not configured)'}`,
+    `- root exists: ${status.rootExists}`,
+    `- root readable: ${status.rootReadable}`,
+    `- root writable: ${status.rootWritable}`,
+    `- diagnostics: ${status.diagnosticsExists} (${status.diagnosticsBytes} bytes)`,
+    `- command directory: ${status.commandsPath || '(not available)'}`,
+    `- commands: active=${status.activeCommands} stale=${status.staleCommands} invalid=${status.invalidCommands} temporary=${status.temporaryFiles}`,
+    `- message: ${status.message}`,
+    '',
+    '### Channels',
+  ];
+  if (status.channels.length === 0) {
+    lines.push('- (none found)');
+  } else {
+    status.channels.forEach((item) => lines.push(
+      `- ${item.name}: diagnostics=${item.diagnosticsExists} active=${item.activeCommands} stale=${item.staleCommands} invalid=${item.invalidCommands} temporary=${item.temporaryFiles}`,
+    ));
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+// Deletes only expired commands and stale temporary/malformed requests from all
+// channels. Valid pending commands and diagnostics files remain untouched.
+function cleanSyncFolder(options) {
+  const status = syncStatusReport(options);
+  if (!status.enabled) {
+    throw new Error(status.message);
+  }
+  if (!status.rootExists) {
+    console.log('sync clean: sync root does not exist; nothing to clean');
+    return;
+  }
+  const now = Date.now();
+  const ttlMs = status.commandTtlMs;
+  const removed = { expired: 0, invalid: 0, temporary: 0 };
+  for (const channel of status.channels) {
+    const directory = path.join(status.path, channel.name, 'commands');
+    let entries;
+    try {
+      entries = fs.readdirSync(directory, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.startsWith('command-')) {
+        continue;
+      }
+      const itemPath = path.join(directory, entry.name);
+      let kind = '';
+      if (entry.name.endsWith('.json')) {
+        try {
+          const item = JSON.parse(fs.readFileSync(itemPath, 'utf8'));
+          if (Number(item.expiresAt) <= now) {
+            kind = 'expired';
+          }
+        } catch {
+          if (modificationTimeMs(itemPath) + ttlMs <= now) {
+            kind = 'invalid';
+          }
+        }
+      } else if (entry.name.endsWith('.tmp') && modificationTimeMs(itemPath) + ttlMs <= now) {
+        kind = 'temporary';
+      }
+      if (kind) {
+        fs.rmSync(itemPath, { force: true });
+        removed[kind] += 1;
+      }
+    }
+  }
+  console.log(`sync clean: removed expired=${removed.expired} invalid=${removed.invalid} temporary=${removed.temporary}`);
+  console.log(`path: ${status.path}`);
+  console.log(`channel: ${status.channel}`);
+}
+
+// Finds a built Tauri application binary when one is available locally.
+function findTauriBinary() {
+  if (process.env.FPASOTERM_TAURI_BIN) {
+    return process.env.FPASOTERM_TAURI_BIN;
+  }
+
+  const executable = process.platform === 'win32' ? 'fpasoterm.exe' : 'fpasoterm';
+  for (const profile of ['release', 'debug']) {
+    const candidate = path.join(root, 'src-tauri', 'target', profile, executable);
+    if (fs.existsSync(candidate) && isBuiltBinaryCurrent(candidate)) {
+      return candidate;
+    }
+  }
+  return undefined;
+}
+
+// Stores proof that the binary was created by normal cargo build, not tauri dev.
+function buildStampPath() {
+  return path.join(root, 'src-tauri', 'target', 'debug', '.fpasoterm-normal-build.json');
+}
+
+// Reads the normal-build stamp used to avoid an unnecessary cargo build.
+function readBuildStamp() {
+  try {
+    return JSON.parse(fs.readFileSync(buildStampPath(), 'utf8'));
+  } catch {
+    return undefined;
+  }
+}
+
+// Writes the binary/source mtimes after a successful normal cargo build.
+function writeBuildStamp(binary) {
+  const stamp = {
+    binary,
+    binaryMtime: fs.statSync(binary).mtimeMs,
+    sourceMtime: latestRuntimeSourceMtime(),
+  };
+  fs.writeFileSync(buildStampPath(), JSON.stringify(stamp, null, 2));
+}
+
+// Returns a binary only when the normal-build stamp still matches current files.
+function findStampedTauriBinary() {
+  const binary = findTauriBinary();
+  const stamp = readBuildStamp();
+  if (!binary || !stamp || stamp.binary !== binary) {
+    return undefined;
+  }
+  if (stamp.sourceMtime !== latestRuntimeSourceMtime()) {
+    return undefined;
+  }
+  if (stamp.binaryMtime !== fs.statSync(binary).mtimeMs) {
+    return undefined;
+  }
+  return binary;
+}
+
+// Describes the work the detached launcher will perform before a window exists.
+function startupPreparationStatus(options) {
+  if (options.dev) {
+    return 'building local runtime with cargo';
+  }
+  if (findStampedTauriBinary()) {
+    return 'using cached local runtime';
+  }
+  if (findTauriBinary()) {
+    return 'using local runtime';
+  }
+  return 'building local runtime with cargo (first launch can take several minutes)';
+}
+
+// Detects the only startup path that needs visible work before a window exists.
+function requiresLocalRuntimeBuild(options) {
+  return options.dev || (!findStampedTauriBinary() && !findTauriBinary());
+}
+
+// Builds the debug binary used by normal source-checkout launches.
+function buildTauriBinary(options) {
+  if (options.dev) {
+    appendLauncherLog('launcher build=forced debug binary');
+    return buildLocalTauriBinary(options);
+  }
+  const stampedBinary = findStampedTauriBinary();
+  if (stampedBinary) {
+    appendLauncherLog(`launcher build=skip stamped binary=${stampedBinary}`);
+    return Promise.resolve(stampedBinary);
+  }
+
+  const currentBinary = findTauriBinary();
+  if (currentBinary) {
+    writeBuildStamp(currentBinary);
+    appendLauncherLog(`launcher build=skip current binary=${currentBinary}`);
+    return Promise.resolve(currentBinary);
+  }
+
+  appendLauncherLog('launcher build=cargo build');
+  return buildLocalTauriBinary(options);
+}
+
+// Builds the static-asset debug binary without starting a localhost dev server.
+function buildLocalTauriBinary(options) {
+  appendLaunchPhase('cargo-build-start');
+  let logFd;
+  let stdio = options.foreground ? 'inherit' : 'ignore';
+  if (!options.foreground) {
+    try {
+      logFd = fs.openSync(launcherLogPath, 'a');
+      // A detached first launch cannot write to the invoking terminal. Keep the
+      // compiler diagnostics in launcher.log so a missing toolchain or native
+      // dependency can be diagnosed without rerunning in the foreground.
+      stdio = ['ignore', logFd, logFd];
+    } catch (error) {
+      appendLauncherLog(`launcher cargo log fd error=${error.message}`);
+    }
+  }
+  // Tauri embeds frontendDist in the native binary, but Cargo does not always
+  // notice a renderer-only edit. Clean only this crate before building so an
+  // updated launcher never opens stale renderer assets.
+  appendLaunchPhase('cargo-clean-start');
+  const cleanResult = spawnSync('cargo', [
+    'clean',
+    '--manifest-path', path.join(root, 'src-tauri', 'Cargo.toml'),
+    '-p', 'fpasoterm',
+  ], {
+    cwd: root,
+    env: process.env,
+    stdio,
+    windowsHide: !options.foreground,
+  });
+  if (cleanResult.error) {
+    if (logFd !== undefined) {
+      fs.closeSync(logFd);
+    }
+    return Promise.reject(new Error(`failed to start cargo clean: ${cleanResult.error.message}`));
+  }
+  if (cleanResult.status !== 0) {
+    if (logFd !== undefined) {
+      fs.closeSync(logFd);
+    }
+    return Promise.reject(new Error(`cargo clean failed with exit code ${cleanResult.status}`));
+  }
+  appendLaunchPhase('cargo-clean-complete');
+
+  const result = spawn('cargo', ['build', '--manifest-path', path.join(root, 'src-tauri', 'Cargo.toml')], {
+    cwd: root,
+    env: process.env,
+    stdio,
+    windowsHide: !options.foreground,
+  });
+
+  return new Promise((resolve, reject) => {
+    result.on('error', (error) => {
+      if (logFd !== undefined) {
+        fs.closeSync(logFd);
+      }
+      reject(new Error(`failed to start cargo build: ${error.message}`));
+    });
+    result.on('exit', (code, signal) => {
+      if (logFd !== undefined) {
+        fs.closeSync(logFd);
+      }
+      if (signal) {
+        appendLauncherLog(`launcher cargo build exit signal=${signal}`);
+        reject(new Error(`cargo build exited with signal ${signal}`));
+        return;
+      }
+      if (code !== 0) {
+        appendLauncherLog(`launcher cargo build exit code=${code}`);
+        reject(new Error(`cargo build failed with exit code ${code}`));
+        return;
+      }
+      appendLaunchPhase('cargo-build-complete');
+      const binary = findTauriBinary();
+      if (!binary) {
+        reject(new Error('cargo build finished but no current fpasoterm binary was found'));
+        return;
+      }
+      writeBuildStamp(binary);
+      resolve(binary);
+    });
+  });
+}
+
+// Avoids launching stale local target binaries after source checkout edits.
+function isBuiltBinaryCurrent(candidate) {
+  const binaryMtime = fs.statSync(candidate).mtimeMs;
+  return binaryMtime >= latestRuntimeSourceMtime();
+}
+
+// Tracks source files that require rebuilding the Tauri binary when changed.
+function latestRuntimeSourceMtime() {
+  return [
+    'src-tauri/src/main.rs',
+    'src-tauri/Cargo.toml',
+    'src-tauri/Cargo.lock',
+    'src-tauri/build.rs',
+    'src-tauri/default-config.toml',
+    'src-tauri/tauri.conf.json',
+    'src-tauri/capabilities',
+    'src/renderer',
+    'completions',
+    'extra/logo/fpasoterm.png',
+    'package.json',
+  ]
+    .map((relativePath) => path.join(root, relativePath))
+    .reduce((latest, sourcePath) => Math.max(latest, latestPathMtime(sourcePath)), 0);
+}
+
+// Returns the newest mtime in a file or a small source directory recursively.
+function latestPathMtime(sourcePath) {
+  try {
+    const stat = fs.statSync(sourcePath);
+    if (!stat.isDirectory()) {
+      return stat.mtimeMs;
+    }
+    return fs.readdirSync(sourcePath, { withFileTypes: true })
+      .reduce((latest, entry) => Math.max(latest, latestPathMtime(path.join(sourcePath, entry.name))), stat.mtimeMs);
+  } catch {
+    return 0;
+  }
+}
+
+// Resolves config before launching so the Rust runtime can stay focused on
+// windowing and PTY work.
+function runtimeEnv(options) {
+  applyEnv(options.env);
+  const runtimeConfig = loadConfig();
+  applyWindowRuntimeOverrides(runtimeConfig.config.window, options.env);
+  applyTerminalRuntimeOverrides(runtimeConfig.config.terminal, options.env);
+  runtimeConfig.diagnostics = {
+    debugKeys: options.env.FPASOTERM_DEBUG_KEYS === '1' || process.env.FPASOTERM_DEBUG_KEYS === '1',
+    consoleDiagnostics:
+      options.env.FPASOTERM_CONSOLE_DIAGNOSTICS === '1' || process.env.FPASOTERM_CONSOLE_DIAGNOSTICS === '1',
+    opaqueTerminal:
+      options.env.FPASOTERM_DEBUG_OPAQUE_TERMINAL === '1' ||
+      process.env.FPASOTERM_DEBUG_OPAQUE_TERMINAL === '1',
+  };
+  return {
+    ...process.env,
+    ...options.env,
+    FPASOTERM_RUNTIME_CONFIG_JSON: JSON.stringify(runtimeConfig),
+    // Native processes replace this marker with their own PID. A command
+    // launched from a terminal shell must reload config.toml instead.
+    FPASOTERM_RUNTIME_CONFIG_SOURCE: 'launcher',
+    FPASOTERM_RUNTIME_CONFIG_OWNER_PID: '',
+  };
+}
+
+// Applies one-shot CLI terminal overrides after config resolution.
+function applyTerminalRuntimeOverrides(terminalConfig, env) {
+  if (env.FPASOTERM_SHELL) {
+    terminalConfig.shell = env.FPASOTERM_SHELL;
+  }
+}
+
+// Applies one-shot CLI window overrides after config and saved state resolution.
+function applyWindowRuntimeOverrides(windowConfig, env) {
+  if (env.FPASOTERM_WINDOW_TITLE) {
+    windowConfig.title = env.FPASOTERM_WINDOW_TITLE;
+    windowConfig.titleLocked = true;
+  }
+  if (env.FPASOTERM_TITLEBAR_COLOR) {
+    windowConfig.titlebarColor = env.FPASOTERM_TITLEBAR_COLOR;
+  }
+  if (env.FPASOTERM_WINDOW_WIDTH) {
+    windowConfig.width = Number(env.FPASOTERM_WINDOW_WIDTH);
+  }
+  if (env.FPASOTERM_WINDOW_HEIGHT) {
+    windowConfig.height = Number(env.FPASOTERM_WINDOW_HEIGHT);
+  }
+}
+
+// Starts the desktop runtime. By default the child is detached so the shell prompt returns.
+async function launch(options) {
+  validateLaunchProfile(options);
+  let preparedBinary;
+  // Re-exec before a possible cargo build so normal launches return the caller
+  // prompt consistently on macOS, Linux, and Windows.
+  if (!options.foreground && process.env.FPASOTERM_LAUNCHER_DETACHED !== '1') {
+    const preparation = startupPreparationStatus(options);
+    if (requiresLocalRuntimeBuild(options)) {
+      // First-run compilation can take minutes. Keep this process attached so
+      // the caller sees what is loading and the actual compiler error, then
+      // detach only after a native runtime is ready to open its window.
+      process.stdout.write(`fpasoterm: ${preparation}.\n`);
+      process.stdout.write('fpasoterm: phase 1/3 - preparing the local Rust runtime.\n');
+      process.stdout.write('fpasoterm: phase 2/3 - cargo build started; compiler progress follows.\n');
+      appendLaunchPhase('visible-cargo-build-start');
+      preparedBinary = await buildTauriBinary({ ...options, foreground: true });
+      appendLaunchPhase('visible-cargo-build-complete');
+      process.stdout.write('fpasoterm: phase 2/3 - cargo build completed.\n');
+      process.stdout.write('fpasoterm: phase 3/3 - opening the native window in the background.\n');
+    } else {
+      const child = spawn(process.execPath, [__filename, ...process.argv.slice(2)], {
+        detached: true,
+        env: {
+          ...process.env,
+          FPASOTERM_LAUNCHER_DETACHED: '1',
+          FPASOTERM_LAUNCH_STARTED_AT: String(launcherStartedAt),
+        },
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      child.on('error', (error) => appendLauncherLog(`launcher detach error=${error.message}`));
+      child.unref();
+      if (process.stdout.isTTY) {
+        process.stdout.write(`fpasoterm: ${preparation}; starting in background (pid ${child.pid ?? 'unknown'}).\n`);
+      }
+      appendLaunchPhase(`detached pid=${child.pid ?? 'unknown'}`);
+      return;
+    }
+  }
+
+  appendLaunchPhase('resolving-runtime');
+  const tauriBinary = preparedBinary || await buildTauriBinary(options);
+  appendLaunchPhase('runtime-ready');
+  const command = tauriBinary;
+  const args = options.runtimeArgs;
+  const env = runtimeEnv(options);
+  appendLauncherLog(`launcher command=${command}`);
+  appendLauncherLog(`launcher args=${JSON.stringify(args)}`);
+  appendLauncherLog(`launcher mode=${options.dev ? 'debug-binary' : 'binary'}`);
+  appendLauncherLog(`launcher cwd=${root}`);
+
+  let logFd;
+  let stdio = options.foreground ? 'inherit' : 'ignore';
+  if (!options.foreground) {
+    try {
+      logFd = fs.openSync(launcherLogPath, 'a');
+      stdio = ['ignore', logFd, logFd];
+    } catch (error) {
+      appendLauncherLog(`launcher log fd error=${error.message}`);
+    }
+  }
+
+  const child = spawn(command, args, {
+    detached: !options.foreground,
+    env,
+    stdio,
+    windowsHide: !options.foreground,
+  });
+
+  appendLauncherLog(`launcher child pid=${child.pid ?? 'unknown'}`);
+  appendLaunchPhase('desktop-spawned');
+  child.on('error', (error) => {
+    appendLauncherLog(`launcher child error=${error.message}`);
+    if (logFd !== undefined) {
+      fs.closeSync(logFd);
+    }
+  });
+
+  if (!options.foreground) {
+    if (preparedBinary && process.stdout.isTTY) {
+      process.stdout.write(`fpasoterm: startup complete; window process pid ${child.pid ?? 'unknown'}.\n`);
+    }
+    child.on('exit', (code, signal) => {
+      appendLauncherLog(`launcher child exit code=${code ?? ''} signal=${signal ?? ''}`);
+      if (logFd !== undefined) {
+        fs.closeSync(logFd);
+      }
+    });
+    child.unref();
+    return;
+  }
+
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGUSR2']) {
+    process.on(signal, () => {
+      if (!child.killed) {
+        child.kill(signal);
+      }
+    });
+  }
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      console.error(`${command} exited with signal ${signal}`);
+      process.exit(1);
+    }
+    process.exit(code ?? 0);
+  });
+}
+
+// Validates a requested profile before a normal launch detaches from the shell.
+// This keeps a typo or missing profile visible to the invoking user instead of
+// only recording the failure in launcher.log.
+function validateLaunchProfile(options) {
+  const profile = options.env.FPASOTERM_PROFILE;
+  if (!profile) {
+    return;
+  }
+  applyEnv(options.env);
+  selectProfileConfig(readUserConfig(configPath()), profile);
+}
+
+let parsedArguments = false;
+try {
+  const options = parseArgs(process.argv.slice(2));
+  parsedArguments = true;
+  if (options.help) {
+    process.stdout.write(helpText);
+  } else if (options.version) {
+    printVersion();
+  } else if (options.updateCheck) {
+    Promise.resolve(checkForUpdate()).catch((updateError) => {
+      console.error(`fpasoterm: could not check for updates: ${updateError.message}`);
+      process.exitCode = 1;
+    });
+  } else if (options.doctor) {
+    Promise.resolve(runDoctor(options)).catch((doctorError) => {
+      console.error(`fpasoterm: doctor failed: ${doctorError.message}`);
+      process.exitCode = 1;
+    });
+  } else if (Object.hasOwn(options, 'pluginSearch')) {
+    Promise.resolve(searchPublicPlugins(options.pluginSearch)).catch((searchError) => {
+      console.error(`fpasoterm: could not search public plugins: ${searchError.message}`);
+      process.exitCode = 1;
+    });
+  } else if (options.completionShell) {
+    printCompletion(options.completionShell);
+  } else if (options.completionInstallShell) {
+    installCompletion(options.completionInstallShell);
+  } else if (options.completionUninstallShell) {
+    uninstallCompletion(options.completionUninstallShell);
+  } else if (options.listInstances) {
+    printRunningInstances();
+  } else if (options.closeTarget) {
+    closeRunningInstance(options.closeTarget);
+  } else if (options.pluginInstall && options.pluginPortsDir) {
+    try {
+      installLocalPluginPort(options);
+    } catch (installError) {
+      console.error(`fpasoterm: could not install local plugin port: ${installError.message}`);
+      process.exitCode = 1;
+    }
+  } else if (options.pluginInstall) {
+    Promise.resolve(installPublicPlugin(options)).catch((installError) => {
+      console.error(`fpasoterm: could not install public plugin: ${installError.message}`);
+      process.exitCode = 1;
+    });
+  } else if (options.pluginInstallFile) {
+    try {
+      installLocalPluginFile(options);
+    } catch (installError) {
+      console.error(`fpasoterm: could not install local plugin file: ${installError.message}`);
+      process.exitCode = 1;
+    }
+  } else if (uninstallLocalPlugins(options)) {
+    // The selected local plugin sources and config entries have been removed.
+  } else if (updatePluginConfig(options)) {
+    // The config command has completed without starting the desktop process.
+  } else if (options.resetWindowState) {
+    resetWindowState(options);
+  } else if (options.resetConfig) {
+    resetConfig(options);
+  } else if (options.updateConfig) {
+    updateConfig(options);
+  } else if (options.pruneConfig) {
+    pruneConfigFile(options);
+  } else if (options.syncStatus || options.syncDiagnostics) {
+    process.stdout.write(syncStatusMarkdown(options));
+  } else if (options.syncClean) {
+    cleanSyncFolder(options);
+  } else if (options.broadcastText) {
+    broadcastTerminalInput(options);
+  } else if (options.setupSync) {
+    Promise.resolve(setupSync(options)).catch((setupError) => {
+      console.error(`fpasoterm: ${setupError.message}`);
+      process.exitCode = 1;
+    });
+  } else if (options.showConfig) {
+    showConfig(options);
+  } else if (options.configCheck) {
+    checkConfig(options);
+  } else if (options.profileList) {
+    showProfileList(options);
+  } else if (options.configPathOnly) {
+    showConfigPath(options);
+  } else if (options.configExample) {
+    showConfigExample(options);
+  } else if (options.diagnostics) {
+    process.stdout.write(diagnosticsMarkdown(options));
+  } else if (options.openLogDir) {
+    openLogDirectory(options);
+  } else if (options.copyDiagnostics) {
+    copyDiagnostics(options);
+  } else if (options.pluginList) {
+    showPluginList(options);
+  } else if (options.pluginPath) {
+    showPluginPath(options);
+  } else if (options.pluginInfo) {
+    showPluginInfo(options);
+  } else if (options.updateDesktop) {
+    updateDesktopIntegration();
+  } else if (options.selfUpdateCheckout) {
+    selfUpdateCheckout();
+  } else if (options.selfUpdate) {
+    selfUpdate();
+  } else {
+    Promise.resolve(launch(options)).catch((launchError) => {
+      console.error(`fpasoterm: ${launchError.message}`);
+      appendLauncherLog(`launcher error=${launchError.message}`);
+      process.exitCode = 1;
+    });
+  }
+} catch (error) {
+  console.error(`fpasoterm: ${error.message}`);
+  // Invalid CLI input must remain concise enough for scripts and shell history.
+  // Explicit --help is the only operation that prints the full option list.
+  process.exitCode = parsedArguments ? 1 : 2;
+}