overlord-cli 3.22.0 → 3.24.0

package/README.md

@@ -33,6 +33,9 @@ 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
@@ -53,8 +56,9 @@ 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

package/bin/_cli/index.mjs

@@ -38,7 +38,7 @@ 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

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/protocol.mjs

@@ -189,6 +189,37 @@ function readJsonFile(filePath, label) {
   }
 }
 
+async function readTextFromStdin(label) {
+  const chunks = [];
+  try {
+    for await (const chunk of process.stdin) {
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    }
+  } catch (err) {
+    throw new Error(
+      `${label}: could not read stdin: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function readJsonFileOrStdin(filePath, label) {
+  if (filePath !== '-') {
+    return readJsonFile(filePath, label);
+  }
+
+  try {
+    return JSON.parse(await readTextFromStdin(label));
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith(`${label}: could not read stdin`)) {
+      throw err;
+    }
+    throw new Error(
+      `${label}: could not parse stdin: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // changeRationales helper
 // ---------------------------------------------------------------------------
@@ -200,7 +231,10 @@ function readJsonFile(filePath, label) {
  */
 async function resolveChangeRationales(flags) {
   if (flags['change-rationales-file']) {
-    return readJsonFile(String(flags['change-rationales-file']), '--change-rationales-file');
+    return await readJsonFileOrStdin(
+      String(flags['change-rationales-file']),
+      '--change-rationales-file'
+    );
   }
   if (flags['change-rationales-json']) {
     try {
@@ -624,7 +658,7 @@ async function protocolDeliver(args) {
   if (!sessionKey) throw new Error('--session-key is required (or set SESSION_KEY)');
   if (!ticketId) throw new Error('--ticket-id is required (or set TICKET_ID)');
   const deliverPayload = flags['payload-file']
-    ? readJsonFile(String(flags['payload-file']), '--payload-file')
+    ? await readJsonFileOrStdin(String(flags['payload-file']), '--payload-file')
     : null;
   const summary = deliverPayload?.summary ??
     (flags['summary-file']
@@ -642,7 +676,7 @@ async function protocolDeliver(args) {
     throw new Error('Use either --payload-file or --artifacts-json, not both');
   }
   if (flags['artifacts-file']) {
-    artifacts = readJsonFile(String(flags['artifacts-file']), '--artifacts-file');
+    artifacts = await readJsonFileOrStdin(String(flags['artifacts-file']), '--artifacts-file');
   } else if (flags['artifacts-json']) {
     try {
       artifacts = JSON.parse(String(flags['artifacts-json']));
@@ -1144,14 +1178,15 @@ deliver:
     --session-key <key>
     --ticket-id <id>
     --summary <text> or --summary-file <path>
-    or: --payload-file <path> containing { summary, artifacts, changeRationales }
+    or: --payload-file <path|-> containing { summary, artifacts, changeRationales }
   Optional:
     --artifacts-json <json>
-    --artifacts-file <path>
+    --artifacts-file <path|->
     --change-rationales-json <json>
-    --change-rationales-file <path>
+    --change-rationales-file <path|->
     --skip-file-change-check  Bypass local git vs changeRationales validation
   Notes:
+    Use --payload-file - to read the full delivery JSON from stdin without creating a scratch file.
     Do not combine --payload-file with --artifacts-json/--artifacts-file or change-rationale flags.
     In a git workspace, deliver validates that changed files are represented by changeRationales unless skipped.
 
@@ -1243,6 +1278,7 @@ Examples:
   ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done"
   ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done" --artifacts-file ./artifacts.json
   ovld protocol deliver --session-key <key> --ticket-id <id> --payload-file ./deliver.json
+  ovld protocol deliver --session-key <key> --ticket-id <id> --payload-file -
   ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done" --skip-file-change-check
   ovld protocol deliver --session-key <key> --ticket-id <id> --summary "Done" --timeout 60000
 `);

package/bin/_cli/setup.mjs

@@ -84,11 +84,11 @@ If you receive a prompt with a specified ticket ID, adhere to the following. If
      --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
    \`\`\`
 
-   For larger or quote-sensitive deliveries, prefer a single JSON file:
+   For larger or quote-sensitive deliveries, prefer a single JSON payload on stdin:
    \`\`\`bash
-   ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --payload-file ./deliver.json
+   ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --payload-file -
    \`\`\`
-   Treat \`deliver.json\` as ephemeral scratch data only. Create it outside the repository when practical, never commit it, and remove it after delivery.
+   This avoids creating a scratch delivery file that needs cleanup. If your runtime cannot provide stdin directly, \`--payload-file ./deliver.json\` remains supported; treat that file as ephemeral scratch data, never commit it, and remove it after delivery.
 
 ## Change Rationales
 
@@ -96,7 +96,7 @@ Always include \`changeRationales\` when delivering. Optionally include them on
 
 Before delivering, make sure every meaningful git-tracked file change is represented in \`changeRationales\`; do not send \`file_changes\` as an artifact.
 
-These are structured protocol payloads that Overlord stores as first-class rows in the \`file_changes\` table. Prefer inline JSON or the dedicated command below. For quote-sensitive deliveries, prefer \`--payload-file\` so summary, artifacts, and change rationales stay in one JSON document, but treat that JSON as ephemeral scratch data rather than a repository artifact. Ordinary deliver artifacts should use \`next_steps\`, \`test_results\`, \`migration\`, \`note\`, \`url\`, or \`decision\`.
+These are structured protocol payloads that Overlord stores as first-class rows in the \`file_changes\` table. Prefer inline JSON or the dedicated command below. For larger full delivery payloads, prefer \`--payload-file -\` so summary, artifacts, and change rationales stay in one JSON document without creating a temporary file. Ordinary deliver artifacts should use \`next_steps\`, \`test_results\`, \`migration\`, \`note\`, \`url\`, or \`decision\`.
 
 \`\`\`bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \\\\
@@ -158,11 +158,11 @@ If you receive a prompt with a specified ticket ID, adhere to the following. If
      --artifacts-json '[{"type":"next_steps","label":"Next steps","content":"..."}]' \\\\
      --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
    \`\`\`
-   If you use \`--payload-file\`, \`--artifacts-file\`, or \`--change-rationales-file\` for larger JSON, treat that file as ephemeral scratch data outside the repository and remove it after delivery. Do not leave delivery JSON checked into the worktree.
+   For larger delivery JSON, prefer \`--payload-file -\` and stream the full payload on stdin so no scratch file needs to be created or removed. If you use \`--payload-file\`, \`--artifacts-file\`, or \`--change-rationales-file\` with a real path, treat that file as ephemeral scratch data outside the repository and remove it after delivery. Do not leave delivery JSON checked into the worktree.
 
 ## Change Rationales
 
-Always include \`changeRationales\` when delivering. Before delivering, make sure every meaningful git-tracked file change is represented in \`changeRationales\`; do not send \`file_changes\` as an artifact. Record only meaningful behavioral changes. Overlord stores these as structured rows in the \`file_changes\` table. If you need a JSON file for transport, keep it ephemeral and out of the repository.
+Always include \`changeRationales\` when delivering. Before delivering, make sure every meaningful git-tracked file change is represented in \`changeRationales\`; do not send \`file_changes\` as an artifact. Record only meaningful behavioral changes. Overlord stores these as structured rows in the \`file_changes\` table. For larger delivery payloads, prefer \`--payload-file -\` with stdin. If you need a JSON file for transport, keep it ephemeral and out of the repository.
 
 \`\`\`bash
 ovld protocol record-change-rationales --session-key <sessionKey> --ticket-id $TICKET_ID \\\\
@@ -231,7 +231,7 @@ When done, deliver with artifacts and change rationales:
 \`\`\`bash
 ovld protocol deliver --session-key <sessionKey> --ticket-id $TICKET_ID --summary "Narrative: what you did, next steps." --artifacts-json '[{"type":"next_steps","label":"Next steps","content":"..."}]' --change-rationales-json '[{"label":"Short reviewer title","file_path":"path/to/file.ts","summary":"What changed.","why":"Why it changed.","impact":"Behavioral impact.","hunks":[{"header":"@@ -10,6 +10,14 @@"}]}]'
 \`\`\`
-If you use a JSON file for delivery transport, keep it ephemeral scratch data outside the repository and remove it after the protocol call.
+For larger delivery JSON, prefer \`--payload-file -\` with stdin so no scratch file needs to be created or removed. If you use a JSON file for delivery transport, keep it ephemeral scratch data outside the repository and remove it after the protocol call.
 
 Rules:
 - Always attach first and deliver last.
@@ -950,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
 // ---------------------------------------------------------------------------
@@ -959,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 {
@@ -979,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;
   }
@@ -1003,6 +1493,19 @@ 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "3.22.0",
+  "version": "3.24.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"
   },

package/plugins/overlord/scripts/overlord-mcp.mjs

@@ -7,6 +7,27 @@ const execFileAsync = promisify(execFile);
 const OVLD_BIN = process.env.OVLD_BIN?.trim() || 'ovld';
 const PROTOCOL_VERSION = '2025-06-18';
 
+function execFileWithOptionalInput(file, args, options, input) {
+  if (input === undefined) {
+    return execFileAsync(file, args, options);
+  }
+
+  return new Promise((resolve, reject) => {
+    const child = execFile(file, args, options, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+
+      resolve({ stdout, stderr });
+    });
+
+    child.stdin?.end(input);
+  });
+}
+
 const tools = [
   {
     name: 'discover_project',
@@ -239,7 +260,8 @@ const tools = [
   },
   {
     name: 'deliver_ticket',
-    description: 'Deliver final work back into Overlord with summary, artifacts, and change rationales.',
+    description:
+      'Deliver final work back into Overlord with summary, artifacts, and change rationales. Large payloads are streamed to the CLI through stdin, so this tool does not create delivery scratch files.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -255,11 +277,14 @@ const tools = [
     toCliFlags: args => ({
       'session-key': args.session_key,
       'ticket-id': args.ticket_id,
-      summary: args.summary,
-      'artifacts-json': args.artifacts,
-      'change-rationales-json': args.change_rationales,
+      'payload-file': '-',
       'skip-file-change-check': args.skip_file_change_check
     }),
+    toCliStdin: args => JSON.stringify({
+      summary: args.summary,
+      ...(Array.isArray(args.artifacts) ? { artifacts: args.artifacts } : {}),
+      ...(Array.isArray(args.change_rationales) ? { changeRationales: args.change_rationales } : {})
+    }),
     subcommand: 'deliver'
   },
   {
@@ -490,17 +515,24 @@ function cliArgsFromFlags(flags) {
 }
 
 async function runProtocol(tool, args) {
-  const cliArgs = ['protocol', tool.subcommand, ...cliArgsFromFlags(tool.toCliFlags(args ?? {}))];
+  const toolArgs = args ?? {};
+  const cliArgs = ['protocol', tool.subcommand, ...cliArgsFromFlags(tool.toCliFlags(toolArgs))];
+  const stdin = typeof tool.toCliStdin === 'function' ? tool.toCliStdin(toolArgs) : undefined;
 
   try {
-    const { stdout, stderr } = await execFileAsync(OVLD_BIN, cliArgs, {
-      cwd: process.cwd(),
-      env: {
-        ...process.env,
-        AGENT_IDENTIFIER: process.env.AGENT_IDENTIFIER ?? 'codex-overlord-plugin'
+    const { stdout, stderr } = await execFileWithOptionalInput(
+      OVLD_BIN,
+      cliArgs,
+      {
+        cwd: process.cwd(),
+        env: {
+          ...process.env,
+          AGENT_IDENTIFIER: process.env.AGENT_IDENTIFIER ?? 'codex-overlord-plugin'
+        },
+        maxBuffer: 20 * 1024 * 1024
       },
-      maxBuffer: 20 * 1024 * 1024
-    });
+      stdin
+    );
 
     const trimmed = stdout.trim();
     const data = trimmed ? JSON.parse(trimmed) : {};

package/plugins/overlord/skills/overlord-ticket-workflow/SKILL.md

@@ -15,7 +15,7 @@ Overlord plugin.
    and stop.
 6. Deliver last with `ovld protocol deliver`, including meaningful `changeRationales` for every
    behavioral git-tracked change.
-   If you need `--payload-file`, `--artifacts-file`, or `--change-rationales-file`, treat that JSON as ephemeral scratch data, not as a repository file. Remove it after delivery and never commit it.
+   For larger delivery JSON, prefer `--payload-file -` and stream the full payload on stdin so no scratch file needs to be created or removed. If you need `--payload-file`, `--artifacts-file`, or `--change-rationales-file` with a real path, treat that JSON as ephemeral scratch data, not as a repository file. Remove it after delivery and never commit it.
 
 ## Rules