overlord-cli 3.21.0 → 3.23.0

package/README.md

@@ -13,6 +13,7 @@ npm install -g overlord-cli
 ```
 
 Use Node.js 20 or newer for every CLI install or update.
+Run `ovld update` any time you want to refresh the global npm install to the latest release.
 
 ## Usage
 
@@ -31,6 +32,10 @@ ovld auth login
 ovld attach
 ovld create "Investigate the failing build"
 ovld prompt "Draft a fix for the onboarding flow"
+ovld update
+ovld protocol discover-project
+ovld protocol attach --ticket-id <ticket-id>
+ovld protocol update --session-key <session-key> --ticket-id <ticket-id> --summary "Working on it" --phase execute
 ovld setup codex
 ovld setup cursor
 ovld setup gemini
@@ -51,9 +56,11 @@ ovld doctor
 - `auth` - log in, log out, or check auth status
 - `tickets` - list or create tickets
 - `ticket` - work with a single ticket
-- `protocol` - run ticket lifecycle commands
-- `connect`, `restart`, `run`, `resume`, `context` - launch or resume an agent session
+- `protocol` - run ticket lifecycle commands such as `discover-project`, `attach`, `connect`, `load-context`, `spawn`, `update`, `record-change-rationales`, `ask`, `read-context`, `write-context`, `deliver`, and artifact upload/download helpers
+- `connect`, `restart`, `context` - launch or resume an agent session or print ticket context
+- `run`, `resume` - legacy aliases for `connect` and `restart`
 - `setup` - install the Overlord connector or plugin bundle for a supported agent
+- `update` - install the latest CLI release from npm
 - `doctor` - verify installed agent connectors and check whether a newer CLI version is available
 
 ## License

package/bin/_cli/cli-update.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cliPackage = require('../../package.json');
+
+const CURRENT_CLI_VERSION = typeof cliPackage.version === 'string' ? cliPackage.version : '0.0.0';
+const CLI_PACKAGE_NAME =
+  typeof cliPackage.name === 'string' && cliPackage.name ? cliPackage.name : 'overlord-cli';
+
+const ORANGE = '\x1b[38;5;208m';
+const RESET = '\x1b[0m';
+
+function colorizeOrange(text) {
+  return `${ORANGE}${text}${RESET}`;
+}
+
+export function getCurrentCliVersion() {
+  return CURRENT_CLI_VERSION;
+}
+
+export function getCliPackageName() {
+  return CLI_PACKAGE_NAME;
+}
+
+export async function fetchLatestCliVersion({
+  fetchImpl = fetch,
+  packageName = CLI_PACKAGE_NAME,
+  timeoutMs = 2500
+} = {}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetchImpl(`https://registry.npmjs.org/${packageName}/latest`, {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' }
+    });
+
+    if (!response.ok) return null;
+
+    const payload = await response.json();
+    return typeof payload?.version === 'string' ? payload.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function checkForCliUpdate(options = {}) {
+  const currentVersion = options.currentVersion ?? CURRENT_CLI_VERSION;
+  const latestVersion = await fetchLatestCliVersion(options);
+  if (!latestVersion || latestVersion === currentVersion) return null;
+  return latestVersion;
+}
+
+export function formatCliUpdateNotice(latestVersion, { currentVersion = CURRENT_CLI_VERSION } = {}) {
+  return `New Overlord CLI version available: v${latestVersion} (installed v${currentVersion}). Run \`ovld update\` to update via npm.`;
+}
+
+export function printCliUpdateNotice(
+  latestVersion,
+  { currentVersion = CURRENT_CLI_VERSION, stream = process.stderr } = {}
+) {
+  if (!latestVersion) return false;
+  stream.write(`${colorizeOrange(formatCliUpdateNotice(latestVersion, { currentVersion }))}\n`);
+  return true;
+}
+
+export async function runCliUpdateCommand({
+  currentVersion = CURRENT_CLI_VERSION,
+  fetchLatestVersionFn = fetchLatestCliVersion,
+  logger = console,
+  npmCommand = 'npm',
+  packageName = CLI_PACKAGE_NAME,
+  spawnSyncImpl = spawnSync
+} = {}) {
+  const latestVersion = await fetchLatestVersionFn({ currentVersion, packageName });
+
+  if (latestVersion && latestVersion === currentVersion) {
+    logger.log(`Overlord CLI ${currentVersion} is already the latest version.`);
+    return { alreadyLatest: true, currentVersion, latestVersion };
+  }
+
+  const target = `${packageName}@latest`;
+  if (latestVersion) {
+    logger.log(`Updating Overlord CLI ${currentVersion} -> ${latestVersion} via npm...`);
+  } else {
+    logger.log(`Updating Overlord CLI via npm...`);
+  }
+
+  const result = spawnSyncImpl(npmCommand, ['install', '-g', target], {
+    env: process.env,
+    stdio: 'inherit'
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (typeof result.status === 'number' && result.status !== 0) {
+    throw new Error(`\`${npmCommand} install -g ${target}\` exited with status ${result.status}.`);
+  }
+
+  if (typeof result.signal === 'string') {
+    throw new Error(`\`${npmCommand} install -g ${target}\` was terminated by ${result.signal}.`);
+  }
+
+  if (latestVersion) {
+    logger.log(`Overlord CLI updated to v${latestVersion}.`);
+  } else {
+    logger.log('Overlord CLI update complete. Run `ovld version` to confirm the installed version.');
+  }
+
+  return { alreadyLatest: false, currentVersion, latestVersion, result };
+}

package/bin/_cli/index.mjs

@@ -2,6 +2,7 @@
 
 import { runAttachCommand } from './attach.mjs';
 import { runAuthCommand } from './auth.mjs';
+import { checkForCliUpdate, printCliUpdateNotice, runCliUpdateCommand } from './cli-update.mjs';
 import { runLauncherCommand } from './launcher.mjs';
 import { runProtocolCommand } from './protocol.mjs';
 import { runDoctorCommand, runSetupCommand } from './setup.mjs';
@@ -37,7 +38,8 @@ Usage:
   ${primaryCommand} connect <agent>            Launch an agent on a ticket
   ${primaryCommand} restart <agent>            Resume an agent session
   ${primaryCommand} context                    Print ticket context (requires TICKET_ID)
-  ${primaryCommand} setup <agent|all>          Install Overlord agent connector
+  ${primaryCommand} setup [agent|all]          Install Overlord agent connector (interactive if no args)
+  ${primaryCommand} update                    Install the latest CLI version from npm
   ${primaryCommand} doctor                     Validate installed agent connectors and check for CLI updates
   ${primaryCommand} version                    Show the installed CLI version
   ${primaryCommand} help                       Show this help message
@@ -66,6 +68,15 @@ Run a subcommand with --help for more detail.
 export async function runCli({ primaryCommand }) {
   assertSupportedNodeVersion();
   const [command, ...rest] = process.argv.slice(2);
+  const shouldCheckForUpdate =
+    Boolean(process.stdout.isTTY || process.stderr.isTTY) &&
+    command !== 'doctor' &&
+    command !== 'update';
+  const latestCliVersion = shouldCheckForUpdate ? await checkForCliUpdate() : null;
+
+  if (latestCliVersion && command !== 'doctor' && command !== 'update') {
+    printCliUpdateNotice(latestCliVersion);
+  }
 
   if (!command || command === 'help' || command === '--help' || command === '-h') {
     printHelp(primaryCommand);
@@ -119,8 +130,18 @@ export async function runCli({ primaryCommand }) {
     return;
   }
 
+  if (command === 'update') {
+    if (rest[0] === '--help' || rest[0] === '-h' || rest[0] === 'help') {
+      console.log(`Usage:
+  ${primaryCommand} update   Install the latest CLI version from npm`);
+      return;
+    }
+    await runCliUpdateCommand();
+    return;
+  }
+
   if (command === 'doctor') {
-    await runDoctorCommand();
+    await runDoctorCommand({ latestCliVersion });
     return;
   }
 

package/bin/_cli/postinstall.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install message for Overlord CLI
+ * Shown after `npm install -g overlord-cli` or `yarn global add overlord-cli`
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Only show message if this is a global install (not local dev)
+const isGlobalInstall = process.env.npm_config_global === 'true' ||
+                        process.env.npm_execpath?.includes('yarn') ||
+                        !__dirname.includes('node_modules');
+
+if (!isGlobalInstall) {
+  process.exit(0);
+}
+
+const green = s => `\x1b[32m${s}\x1b[0m`;
+const cyan = s => `\x1b[36m${s}\x1b[0m`;
+const bold = s => `\x1b[1m${s}\x1b[0m`;
+
+console.log(`
+${green('✓')} Overlord CLI installed successfully!
+
+${bold('Next step:')} Configure agent connectors
+
+  ${cyan('ovld setup')}
+
+This will guide you through:
+  • Selecting which agent connectors to install (Claude, Cursor, etc.)
+  • Configuring agent permissions for Overlord protocol access
+
+You can also run ${cyan('ovld setup <agent>')} to install a specific agent connector,
+or ${cyan('ovld doctor')} to check your installation status.
+
+Run ${cyan('ovld help')} to see all available commands.
+`);

package/bin/_cli/setup.mjs

@@ -12,6 +12,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { checkForCliUpdate, getCurrentCliVersion, printCliUpdateNotice } from './cli-update.mjs';
 
 const BUNDLE_VERSION = '1.8.0';
 const MD_MARKER_START = '<!-- overlord:managed:start -->';
@@ -280,11 +281,6 @@ function readJsonFileOrNull(filePath) {
   }
 }
 
-function localCliVersion() {
-  const cliPackage = readJsonFileOrNull(path.resolve(__dirname, '..', '..', 'package.json'));
-  return typeof cliPackage?.version === 'string' ? cliPackage.version : null;
-}
-
 function writeJsonFile(filePath, data) {
   const dir = path.dirname(filePath);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
@@ -483,28 +479,6 @@ function currentContentHashForAgent(agent) {
   );
 }
 
-async function checkForCliUpdate() {
-  const currentVersion = localCliVersion();
-  if (!currentVersion) return null;
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 2500);
-  try {
-    const response = await fetch('https://registry.npmjs.org/overlord-cli/latest', {
-      signal: controller.signal,
-      headers: { Accept: 'application/json' }
-    });
-    if (!response.ok) return null;
-    const payload = await response.json();
-    const latestVersion = typeof payload?.version === 'string' ? payload.version : null;
-    if (!latestVersion) return null;
-    return latestVersion === currentVersion ? null : latestVersion;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
 function codexSourcePluginDir() {
   if (fs.existsSync(PACKAGE_PLUGIN_DIR)) return PACKAGE_PLUGIN_DIR;
   if (fs.existsSync(REPO_PLUGIN_DIR)) return REPO_PLUGIN_DIR;
@@ -976,6 +950,392 @@ function currentNodeMajor() {
   return Number.parseInt(process.versions.node.split('.')[0] ?? '', 10);
 }
 
+// ---------------------------------------------------------------------------
+// Interactive checkbox prompt
+// ---------------------------------------------------------------------------
+
+/**
+ * Run an interactive checkbox list (multiselect with spacebar).
+ *
+ * @param {object}   opts
+ * @param {string}   opts.message    - Prompt message shown above the list
+ * @param {string[]} opts.choices    - List of choice labels
+ * @param {string[]} [opts.defaults] - Initially selected choices
+ * @returns {Promise<string[]>} - Array of selected choice labels
+ */
+function runCheckboxPrompt({ message, choices, defaults = [] }) {
+  return new Promise(resolve => {
+    const hide = '\x1b[?25l';
+    const show = '\x1b[?25h';
+    const saveCursor = '\x1b7';
+    const restoreCursor = '\x1b8';
+    const eraseBelow = '\x1b[J';
+    const cyan = s => `\x1b[36m${s}\x1b[0m`;
+    const bold = s => `\x1b[1m${s}\x1b[0m`;
+    const dim = s => `\x1b[2m${s}\x1b[0m`;
+
+    let cursorIdx = 0;
+    let selected = new Set(defaults);
+    let hasRendered = false;
+
+    function render() {
+      const lines = [];
+      lines.push(bold(message));
+      lines.push(dim('  ↑↓ navigate · Space toggle · Enter confirm · Esc cancel'));
+      lines.push('');
+
+      for (let i = 0; i < choices.length; i++) {
+        const choice = choices[i];
+        const isSelected = selected.has(choice);
+        const isCursor = i === cursorIdx;
+        const checkbox = isSelected ? '[✓]' : '[ ]';
+        const marker = isCursor ? cyan('▶') : ' ';
+        const label = isCursor ? bold(choice) : choice;
+        lines.push(`  ${marker} ${checkbox} ${label}`);
+      }
+
+      if (hasRendered) {
+        process.stdout.write(restoreCursor + eraseBelow);
+      }
+      process.stdout.write(saveCursor + lines.join('\n'));
+      hasRendered = true;
+    }
+
+    function cleanup() {
+      if (hasRendered) {
+        process.stdout.write(restoreCursor + eraseBelow);
+      }
+      process.stdin.setRawMode(false);
+      process.stdin.removeAllListeners('data');
+      process.stdout.write(show);
+    }
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdout.write(hide);
+    render();
+
+    process.stdin.on('data', key => {
+      // Ctrl-C / Ctrl-D → exit
+      if (key === '\x03' || key === '\x04') {
+        cleanup();
+        process.exit(0);
+      }
+
+      // Escape → cancel
+      if (key === '\x1b') {
+        cleanup();
+        resolve([]);
+        return;
+      }
+
+      // Enter → confirm selection
+      if (key === '\r' || key === '\n') {
+        cleanup();
+        resolve(Array.from(selected));
+        return;
+      }
+
+      // Arrow up
+      if (key === '\x1b[A') {
+        cursorIdx = (cursorIdx - 1 + choices.length) % choices.length;
+        render();
+        return;
+      }
+
+      // Arrow down
+      if (key === '\x1b[B') {
+        cursorIdx = (cursorIdx + 1) % choices.length;
+        render();
+        return;
+      }
+
+      // Spacebar → toggle selection
+      if (key === ' ') {
+        const choice = choices[cursorIdx];
+        if (selected.has(choice)) {
+          selected.delete(choice);
+        } else {
+          selected.add(choice);
+        }
+        render();
+        return;
+      }
+    });
+  });
+}
+
+/**
+ * Ask a yes/no question interactively.
+ *
+ * @param {string} question - The question to ask
+ * @param {boolean} defaultYes - Default answer if user just presses Enter
+ * @returns {Promise<boolean>} - true if yes, false if no
+ */
+function askYesNo(question, defaultYes = true) {
+  return new Promise(resolve => {
+    const hide = '\x1b[?25l';
+    const show = '\x1b[?25h';
+    const saveCursor = '\x1b7';
+    const restoreCursor = '\x1b8';
+    const eraseBelow = '\x1b[J';
+    const cyan = s => `\x1b[36m${s}\x1b[0m`;
+    const bold = s => `\x1b[1m${s}\x1b[0m`;
+    const dim = s => `\x1b[2m${s}\x1b[0m`;
+
+    const choices = ['Yes', 'No'];
+    let cursorIdx = defaultYes ? 0 : 1;
+    let hasRendered = false;
+
+    function render() {
+      const lines = [];
+      lines.push(bold(question));
+      lines.push('');
+
+      for (let i = 0; i < choices.length; i++) {
+        const choice = choices[i];
+        const isCursor = i === cursorIdx;
+        const marker = isCursor ? cyan('▶') : ' ';
+        const label = isCursor ? bold(choice) : choice;
+        lines.push(`  ${marker} ${label}`);
+      }
+
+      lines.push('');
+      lines.push(dim('  ↑↓ navigate · Enter confirm · Esc cancel'));
+
+      if (hasRendered) {
+        process.stdout.write(restoreCursor + eraseBelow);
+      }
+      process.stdout.write(saveCursor + lines.join('\n'));
+      hasRendered = true;
+    }
+
+    function cleanup() {
+      if (hasRendered) {
+        process.stdout.write(restoreCursor + eraseBelow);
+      }
+      process.stdin.setRawMode(false);
+      process.stdin.removeAllListeners('data');
+      process.stdout.write(show);
+    }
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdout.write(hide);
+    render();
+
+    process.stdin.on('data', key => {
+      // Ctrl-C / Ctrl-D → exit
+      if (key === '\x03' || key === '\x04') {
+        cleanup();
+        process.exit(0);
+      }
+
+      // Escape → cancel (default to No)
+      if (key === '\x1b') {
+        cleanup();
+        resolve(false);
+        return;
+      }
+
+      // Enter → confirm selection
+      if (key === '\r' || key === '\n') {
+        cleanup();
+        resolve(cursorIdx === 0);
+        return;
+      }
+
+      // Arrow up
+      if (key === '\x1b[A') {
+        cursorIdx = (cursorIdx - 1 + choices.length) % choices.length;
+        render();
+        return;
+      }
+
+      // Arrow down
+      if (key === '\x1b[B') {
+        cursorIdx = (cursorIdx + 1) % choices.length;
+        render();
+        return;
+      }
+
+      // y/Y → yes
+      if (key === 'y' || key === 'Y') {
+        cleanup();
+        resolve(true);
+        return;
+      }
+
+      // n/N → no
+      if (key === 'n' || key === 'N') {
+        cleanup();
+        resolve(false);
+        return;
+      }
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Agent permissions installation
+// ---------------------------------------------------------------------------
+
+function getPlatformUrl() {
+  // Check for OVERLORD_URL env var first, otherwise default to localhost
+  return process.env.OVERLORD_URL || 'http://localhost:3000';
+}
+
+function installAgentPermissions(agents, platformUrl) {
+  console.log(`\nInstalling agent permissions for: ${agents.join(', ')}`);
+  console.log(`Platform URL: ${platformUrl}\n`);
+
+  for (const agent of agents) {
+    if (agent === 'claude') {
+      installClaudePermissions(platformUrl);
+    } else if (agent === 'opencode') {
+      installOpenCodePermissions(platformUrl);
+    } else if (agent === 'codex') {
+      installCodexPermissions(platformUrl);
+    }
+    // cursor and gemini don't have permission configuration
+  }
+}
+
+function installClaudePermissions(platformUrl) {
+  const settingsPath = path.join(process.cwd(), '.claude', 'settings.local.json');
+  console.log(`--- Claude Code ---`);
+  console.log(`Settings file: ${settingsPath}`);
+
+  let settings = { permissions: { allow: [] } };
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    } catch (e) {
+      console.error(`  ERROR: Could not parse ${settingsPath}: ${e.message}`);
+      return false;
+    }
+    if (!settings.permissions) settings.permissions = {};
+    if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+  }
+
+  const PROTOCOL_ENDPOINTS = [
+    'attach', 'update', 'ask', 'read-context', 'write-context', 'deliver',
+    'create-ticket', 'list-tickets', 'record-change-rationales', 'spawn',
+    'discover-project', 'load-context', 'artifact-upload-file', 'artifact-download-url'
+  ];
+
+  const entries = [];
+  for (const endpoint of PROTOCOL_ENDPOINTS) {
+    entries.push(`Bash(curl -s -X POST "${platformUrl}/api/protocol/${endpoint}":*)`);
+  }
+  entries.push(`Bash(curl -s -H 'Authorization::*)`);
+  for (const endpoint of PROTOCOL_ENDPOINTS) {
+    entries.push(`Bash(curl -s -X POST "$OVERLORD_URL/api/protocol/${endpoint}":*)`);
+  }
+  entries.push(`Bash(curl -s -H "Authorization::*)`);
+
+  const existing = new Set(settings.permissions.allow);
+  const toAdd = entries.filter((e) => !existing.has(e));
+
+  if (toAdd.length === 0) {
+    console.log('  All required permissions already present. Nothing to do.\n');
+    return true;
+  }
+
+  console.log(`  Adding ${toAdd.length} permission entries:`);
+  for (const entry of toAdd) {
+    console.log(`    + ${entry}`);
+  }
+
+  // Backup
+  if (fs.existsSync(settingsPath)) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = `${settingsPath}.backup-${ts}`;
+    fs.copyFileSync(settingsPath, backupPath);
+    console.log(`  Backup: ${backupPath}`);
+  }
+
+  settings.permissions.allow = [...settings.permissions.allow, ...toAdd];
+
+  const dir = path.dirname(settingsPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  console.log('  Settings updated.\n');
+  return true;
+}
+
+function installOpenCodePermissions(_platformUrl) {
+  console.log(`--- OpenCode ---`);
+  const configPath = path.join(os.homedir(), '.config', 'opencode', 'opencode.json');
+  console.log(`Config file: ${configPath}`);
+
+  let config = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    } catch (e) {
+      console.error(`  ERROR: Could not parse ${configPath}: ${e.message}`);
+      return false;
+    }
+  }
+
+  const existingPermission =
+    config.permission && typeof config.permission === 'object' ? config.permission : {};
+  const existingBash =
+    existingPermission.bash && typeof existingPermission.bash === 'object'
+      ? existingPermission.bash
+      : {};
+
+  const next = {
+    ...config,
+    $schema: 'https://opencode.ai/config.json',
+    permission: {
+      ...existingPermission,
+      bash: {
+        '*': 'ask',
+        ...existingBash,
+        'ovld protocol *': 'allow',
+        'curl -sS -X POST *': 'allow',
+        'curl -s -X POST *': 'allow'
+      }
+    }
+  };
+
+  if (fs.existsSync(configPath)) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = `${configPath}.backup-${ts}`;
+    fs.copyFileSync(configPath, backupPath);
+    console.log(`  Backup: ${backupPath}`);
+  }
+
+  const dir = path.dirname(configPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(next, null, 2) + '\n');
+  console.log('  Config updated.\n');
+  return true;
+}
+
+function installCodexPermissions(platformUrl) {
+  console.log(`--- Codex ---`);
+  console.log('  Codex does not support file-based permission configuration.');
+  console.log('  To warm up permissions, run the following commands once inside a Codex session:');
+  console.log('  (Codex will prompt for approval; approve each one to persist the prefix.)\n');
+
+  const PROTOCOL_ENDPOINTS = [
+    'attach', 'update', 'ask', 'read-context', 'write-context', 'deliver',
+    'create-ticket', 'list-tickets'
+  ];
+
+  for (const endpoint of PROTOCOL_ENDPOINTS) {
+    console.log(`  curl -s -X POST "${platformUrl}/api/protocol/${endpoint}" -H "Content-Type: application/json" -H "Authorization: Bearer \\$AGENT_TOKEN" -d '{}'`);
+  }
+  console.log(`  curl -s -H "Authorization: Bearer \\$AGENT_TOKEN" "${platformUrl}/api/protocol/context/test"`);
+  console.log();
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -985,18 +1345,103 @@ export async function runSetupCommand(args) {
 
   if (agent === '--help' || agent === '-h' || agent === 'help') {
     console.log(`Usage:
+  ovld setup           Interactive setup (select agents and configure permissions)
   ovld setup claude    Install Overlord bundle for Claude Code
   ovld setup codex     Install Overlord Codex plugin bundle
   ovld setup cursor    Install Overlord rules, slash commands, and permissions for Cursor
   ovld setup gemini    Install Overlord slash commands and policy rules for Gemini CLI
   ovld setup opencode  Install Overlord connector for OpenCode
   ovld setup all       Install for all supported agents
-  ovld doctor          Validate installed connectors`);
+  ovld doctor          Validate installed connectors and check for CLI updates`);
+    return;
+  }
+
+  // Interactive mode when called without arguments
+  if (!agent) {
+    console.log('Welcome to Overlord agent setup!\n');
+
+    // Step 1: Select agents to install
+    const agentLabels = supportedAgents.map(a => {
+      const descriptions = {
+        claude: 'Claude Code',
+        codex: 'Codex',
+        cursor: 'Cursor',
+        gemini: 'Gemini CLI',
+        opencode: 'OpenCode'
+      };
+      return `${a.padEnd(10)} - ${descriptions[a] || a}`;
+    });
+
+    const selectedLabels = await runCheckboxPrompt({
+      message: 'Select agent connectors to install (Space to toggle, Enter to confirm):',
+      choices: agentLabels,
+      defaults: []
+    });
+
+    if (selectedLabels.length === 0) {
+      console.log('\nNo agents selected. Setup cancelled.');
+      return;
+    }
+
+    // Extract agent names from selected labels
+    const selectedAgents = selectedLabels.map(label => label.split('-')[0].trim());
+
+    // Step 2: Install selected agents
+    console.log(`\nInstalling Overlord agent bundles for: ${selectedAgents.join(', ')}...\n`);
+
+    const installedAgents = [];
+    for (const a of selectedAgents) {
+      console.log(`[${a}]`);
+      try {
+        if (a === 'claude') installClaude();
+        else if (a === 'codex') installCodex();
+        else if (a === 'cursor') installCursor();
+        else if (a === 'gemini') installGemini();
+        else installOpenCode();
+        installedAgents.push(a);
+      } catch (err) {
+        console.error(`  ✗ Failed: ${err.message}`);
+      }
+      console.log();
+    }
+
+    if (installedAgents.length === 0) {
+      console.log('No agents were successfully installed.');
+      return;
+    }
+
+    // Step 3: Offer to configure agent permissions
+    const agentsThatNeedPermissions = installedAgents.filter(a =>
+      ['claude', 'codex', 'opencode'].includes(a)
+    );
+
+    if (agentsThatNeedPermissions.length > 0) {
+      console.log('Agent connectors installed successfully!\n');
+
+      const shouldInstallPermissions = await askYesNo(
+        'Would you like to configure agent permissions for Overlord protocol access?',
+        true
+      );
+
+      if (shouldInstallPermissions) {
+        const platformUrl = getPlatformUrl();
+        installAgentPermissions(agentsThatNeedPermissions, platformUrl);
+        console.log('✓ Agent permissions configured.\n');
+      } else {
+        console.log('\nSkipped agent permissions configuration.');
+        console.log('You can run the permission installer later with:');
+        console.log('  node scripts/install-agent-permissions.mjs\n');
+      }
+    }
+
+    console.log('Setup complete! Run `ovld doctor` to verify your installation.');
     return;
   }
 
   if (agent === 'all') {
     console.log('Installing Overlord agent bundle for all supported agents...\n');
+    const installedAgents = [];
+
     for (const a of supportedAgents) {
       console.log(`[${a}]`);
       try {
@@ -1005,11 +1450,30 @@ export async function runSetupCommand(args) {
         else if (a === 'cursor') installCursor();
         else if (a === 'gemini') installGemini();
         else installOpenCode();
+        installedAgents.push(a);
       } catch (err) {
         console.error(`  ✗ Failed: ${err.message}`);
       }
       console.log();
     }
+
+    // Offer permissions setup for 'all' command too
+    const agentsThatNeedPermissions = installedAgents.filter(a =>
+      ['claude', 'codex', 'opencode'].includes(a)
+    );
+
+    if (agentsThatNeedPermissions.length > 0) {
+      const shouldInstallPermissions = await askYesNo(
+        '\nWould you like to configure agent permissions for Overlord protocol access?',
+        true
+      );
+
+      if (shouldInstallPermissions) {
+        const platformUrl = getPlatformUrl();
+        installAgentPermissions(agentsThatNeedPermissions, platformUrl);
+      }
+    }
+
     console.log('Done.');
     return;
   }
@@ -1029,13 +1493,26 @@ export async function runSetupCommand(args) {
     else if (agent === 'gemini') installGemini();
     else installOpenCode();
     console.log('\nDone.');
+
+    // Offer permissions setup for single agent install too
+    if (['claude', 'codex', 'opencode'].includes(agent)) {
+      const shouldInstallPermissions = await askYesNo(
+        '\nWould you like to configure agent permissions for Overlord protocol access?',
+        true
+      );
+
+      if (shouldInstallPermissions) {
+        const platformUrl = getPlatformUrl();
+        installAgentPermissions([agent], platformUrl);
+      }
+    }
   } catch (err) {
     console.error(`\nFailed: ${err.message}`);
     process.exit(1);
   }
 }
 
-export async function runDoctorCommand() {
+export async function runDoctorCommand({ latestCliVersion = null } = {}) {
   console.log('Overlord agent bundle status:\n');
   let allOk = true;
   const nodeMajor = currentNodeMajor();
@@ -1051,18 +1528,15 @@ export async function runDoctorCommand() {
   for (const agent of supportedAgents) {
     if (!doctorAgent(agent)) allOk = false;
   }
-  const latestCliVersion = await checkForCliUpdate();
+  const updateVersion = latestCliVersion ?? (await checkForCliUpdate());
   console.log();
   if (allOk) {
     console.log('All bundles are up to date.');
   } else {
     console.log('Run `ovld setup <agent>` or `ovld setup all` to install/repair.');
   }
-  if (latestCliVersion) {
+  if (updateVersion) {
     console.log();
-    console.log(`CLI update available: ${latestCliVersion}`);
-    console.log(
-      `Update with Node.js ${REQUIRED_NODE_MAJOR}+ and reinstall the installed CLI wrapper if needed.`
-    );
+    printCliUpdateNotice(updateVersion, { currentVersion: getCurrentCliVersion(), stream: process.stdout });
   }
 }

package/bin/_cli/version.mjs

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-import { createRequire } from 'node:module';
-
-const require = createRequire(import.meta.url);
-const { version } = require('../../package.json');
+import { getCurrentCliVersion } from './cli-update.mjs';
 
 export function runVersionCommand() {
-  console.log(`Overlord CLI ${version}`);
+  console.log(`Overlord CLI ${getCurrentCliVersion()}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "3.21.0",
+  "version": "3.23.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {
@@ -14,6 +14,9 @@
     "bin/",
     "plugins/"
   ],
+  "scripts": {
+    "postinstall": "node bin/_cli/postinstall.mjs || true"
+  },
   "engines": {
     "node": ">=20"
   },