borgmcp 2.15.0 → 2.16.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "2.15.0",
+  "version": "2.16.1",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,23 +24,22 @@
   },
   "scripts": {
     "clean": "node scripts/clean.mjs",
-    "build": "npm run clean && tsc -p tsconfig.json && node scripts/set-bin-mode.mjs",
-    "check": "tsc -p tsconfig.json --noEmit",
-    "dev": "tsc -p tsconfig.json --watch",
+    "preflight:node": "node scripts/node-preflight.mjs",
+    "build": "npm run preflight:node && npm run clean && tsc -p tsconfig.json && node scripts/set-bin-mode.mjs",
+    "check": "npm run preflight:node && tsc -p tsconfig.json --noEmit",
+    "dev": "npm run preflight:node && tsc -p tsconfig.json --watch",
     "start": "node dist/index.js",
     "test": "npm run test:unit && npm run test:release",
-    "test:unit": "vitest run --config vitest.config.ts",
-    "test:release": "node --test test/release-lane.test.mjs test/release-identity.test.mjs",
+    "test:unit": "npm run preflight:node && vitest run --config vitest.config.ts",
+    "test:release": "npm run preflight:node && node --test test/release-lane.test.mjs",
     "onboarding:smoke": "node scripts/onboarding-smoke.mjs",
-    "release:prepare": "node scripts/release-identity.mjs prepare",
     "release:exercise": "npm run build && node scripts/release-exercise.mjs",
     "release:check": "npm run verify:public-source && npm run verify:release && npm run verify:lock && npm run check && npm test && npm run build && npm run onboarding:smoke && npm run verify:package",
     "verify:artifact": "node scripts/verify-packed-artifact.mjs",
     "verify:public-source": "node scripts/verify-public-source.mjs",
     "verify:package": "node scripts/verify-local-package.mjs",
     "verify:release": "node scripts/verify-release-readiness.mjs",
-    "verify:lock": "node scripts/verify-lock-registry.mjs",
-    "verify:release-identity": "node scripts/release-identity.mjs verify"
+    "verify:lock": "node scripts/verify-lock-registry.mjs"
   },
   "files": [
     "dist",

package/src/assimilate-cmd.ts

@@ -388,6 +388,8 @@ export interface AssimilateDeps {
   // on healthy hosts; degraded-path surfaces a stderr warning and
   // still launches claude (never blocks).
   probeMcpReady: () => Promise<boolean>;
+  /** Save the resolved CLI for a newly-created sibling worktree. */
+  setCliPreferenceForWorktree: (cli: BorgCli, worktree: string) => Promise<void>;
   resolveCli: (explicit?: BorgCli) => Promise<BorgCli>;
   prepareCodexRemoteLaunch: () => Promise<CodexRemoteLaunch>;
   setCodexWakeTarget: (cubeId: string, droneId: string, target: { threadId: string; socketPath: string }) => Promise<void>;
@@ -708,13 +710,10 @@ export async function runAssimilate(
 ): Promise<number> {
   const mode = args.mode ?? 'assimilate';
   // ----- Input validation (before any subprocess work) -----
-  if (args.role !== undefined) {
-    const v = validateName(args.role);
-    if (!v.ok) {
-      deps.stderr(v.error + '\n');
-      return 1;
-    }
-  }
+  // A role is a lookup key, not a path component. matchRoleByName() below
+  // applies the shared roleSlug() normalization, so displayed names such as
+  // "Builder" and "Code Reviewer" must reach that resolver. Keep the strict
+  // identifier validator for worktree names, which do become path components.
   if (args.flags.worktree !== undefined) {
     const v = validateName(args.flags.worktree);
     if (!v.ok) {
@@ -1867,6 +1866,24 @@ export async function runAssimilate(
     }
   };
 
+  // CLI resolution happens before the server attach because agent_kind is part
+  // of that request. The resolver therefore saved the preference against the
+  // invoking checkout. Once a sibling exists, save the same choice under its
+  // own project key so a later --here launch in that worktree can read it.
+  if (spawnedWorktreePath) {
+    try {
+      await deps.setCliPreferenceForWorktree(cli, spawnedWorktreePath);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      deps.stderr(
+        `Borg could not save the ${cli} preference for sibling worktree ${spawnedWorktreePath}: ${message}. ` +
+          'The worktree was removed; correct the local configuration and retry.\n',
+      );
+      rollbackWorktree();
+      return 1;
+    }
+  }
+
   try {
     deps.mkdirp(scratchRoot);
     deps.provisionLaunchAccess?.(cli, seatWorktree, launchAccessPaths);

package/src/assimilate-deps.ts

@@ -60,6 +60,7 @@ import {
   hasPersistedActiveCube as cubesHasPersistedActive,
   setActiveCube as cubesSetActive,
   inboxPathForDrone,
+  setProjectCliPreference,
   setCodexWakeTarget,
 } from './cubes.js';
 import {
@@ -575,6 +576,7 @@ export function buildDefaultAssimilateDeps(
         }
       }, () => process.stdin.isTTY === true)
     ),
+    setCliPreferenceForWorktree: (cli, worktree) => setProjectCliPreference(cli, worktree),
     prepareCodexRemoteLaunch: () => prepareCodexRemoteLaunch(defaultCodexRemoteDeps()),
     setCodexWakeTarget,
     findLoadedCodexThread,

package/src/bare-launch-menu.ts

@@ -39,6 +39,23 @@ export interface LaunchMenuInputs {
   hasLaunchAllTargets: boolean;
 }
 
+/**
+ * Resolve and configure the CLI that will actually launch.
+ *
+ * This callback deliberately runs after the one-shot menu choice. A bare
+ * launch may resolve one default CLI first and then launch a different
+ * installed CLI for this invocation; only the final CLI may be self-healed.
+ */
+export function configureSelectedLaunchCli(
+  defaultCli: BorgCli,
+  action: LaunchMenuAction | undefined,
+  configure: (cli: BorgCli) => void,
+): BorgCli {
+  const cli = action?.kind === 'launch' ? action.cli : defaultCli;
+  configure(cli);
+  return cli;
+}
+
 const PRETTY: Record<BorgCli, string> = { claude: 'Claude', codex: 'Codex', opencode: 'OpenCode' };
 
 /**

package/src/claude.ts

@@ -24,7 +24,7 @@ import { basename } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
-import { findProjectRoot, getActiveCube, inboxPathForDrone, setCodexWakeTarget, pruneDeadCodexWakeTargets } from './cubes.js';
+import { findProjectRoot, getActiveCube, inboxPathForDrone, setCodexWakeTarget, pruneDeadCodexWakeTargets, type BorgCli } from './cubes.js';
 import { monitorStateRootForWorktree } from './inbox-monitor.js';
 import { formatSeatReattachRefusal, inspectLiveInboxMonitor } from './seat-reattach-guard.js';
 import { handleVersionFlag, getPackageVersion } from './version.js';
@@ -48,10 +48,12 @@ import { runLaunchAll } from './launch-all-cmd.js';
 import { buildDefaultLaunchAllDeps } from './launch-all-deps.js';
 import { discoverDroneCandidates } from './launch-all-discovery.js';
 import {
+  configureSelectedLaunchCli,
   explicitCliLaunchHint,
   runBareLaunchMenu,
   shouldResolveExplicitCliLaunchHintTargets,
   shouldShowLaunchMenu,
+  type LaunchMenuAction,
 } from './bare-launch-menu.js';
 import { setTerminalTitle } from './terminal-title.js';
 import { initConsolePrefix, consolePrefix } from './console-prefix.js';
@@ -81,6 +83,7 @@ import {
   removeSessionStartHook,
 } from './config-utils.js';
 import { ensureCliMcpConfigured } from './ensure-mcp-config.js';
+import { configureResolvedCli } from './resolved-cli-config.js';
 import { installBorgPlugin } from './opencode-plugin.js';
 import { allocateOpenCodePort, connectOpenCodeDrone, createOpenCodeLaunchKickoff, injectInitialKickoff, openCodeLaunchBinding } from './opencode-drone.js';
 import { buildOpenCodeLaunchArgs, defaultApprovalIo, resolveLaunchBorgApprovals } from './cli-tool-approval.js';
@@ -322,7 +325,7 @@ async function main() {
     parsedCli.cli,
     defaultCliChoiceDeps(prompt, () => process.stdin.isTTY === true)
   );
-  ensureDetectedCliConfigured();
+  let launchAction: LaunchMenuAction | undefined;
 
   // Active cube for this directory — needed for the launch menu's option-3
   // availability, the terminal title, and the inbox-Monitor clause below.
@@ -383,9 +386,13 @@ async function main() {
     // option 1 → configured default; option 2 → the other agent, ONE-SHOT
     // (we deliberately do NOT call setProjectCliPreference — the saved
     // preference is changed only via `borg --cli <agent>`).
-    cli = action.cli;
+    launchAction = action;
   }
 
+  // Configure only the CLI that will actually launch. This must follow the
+  // one-shot menu: the resolved default can differ from the menu selection.
+  cli = configureSelectedLaunchCli(cli, launchAction, ensureResolvedCliConfigured);
+
   if (active && !parsedCli.force) {
     const inboxPath = inboxPathForDrone(active.cubeId, active.droneId);
     const stateRoot = monitorStateRootForWorktree(findProjectRoot(process.cwd()));
@@ -616,40 +623,25 @@ async function main() {
   });
 }
 
-function ensureDetectedCliConfigured(): void {
-  const found = detectCliAvailability();
-  if (found.claude) {
-    try {
-      ensureCliMcpConfigured('claude');
-      // gh#673 P2 (WI-1): the orientation hook lives PROJECT-LOCAL in
-      // <root>/.claude/settings.local.json — ensured on every bare
-      // `borg` launch so pre-P2 worktrees self-heal. The legacy GLOBAL
-      // hook is then removed: safe because this ensure precedes every
-      // borg-launched agent spawn (other projects get their local hook
-      // at their own next launch/assimilate), and P1's BORG_SESSION
-      // gate already no-ops the global hook in non-borg sessions.
-      addProjectSessionStartHook(findProjectRoot(process.cwd()));
-      removeSessionStartHook();
-      addUserPromptSubmitHook();
-    } catch (err: any) {
-      console.error(`${consolePrefix()}${chalk.yellow(`warning: Claude Code integration check failed: ${err?.message ?? err}`)}`);
-    }
-  }
-  if (found.codex) {
-    try {
-      ensureCliMcpConfigured('codex');
-      addCodexSessionStartHook();
-      addCodexUserPromptSubmitHook();
-    } catch (err: any) {
-      console.error(`${consolePrefix()}${chalk.yellow(`warning: Codex integration check failed: ${err?.message ?? err}`)}`);
-    }
-  }
-  if (found.opencode) {
-    try {
-      ensureCliMcpConfigured('opencode');
-    } catch (err: any) {
-      console.error(`${consolePrefix()}${chalk.yellow(`warning: OpenCode integration check failed: ${err?.message ?? err}`)}`);
-    }
+function ensureResolvedCliConfigured(cli: BorgCli): void {
+  const label = cli === 'claude' ? 'Claude Code' : cli === 'codex' ? 'Codex' : 'OpenCode';
+  try {
+    configureResolvedCli(cli, {
+      ensureMcp: ensureCliMcpConfigured,
+      addClaudeProjectSessionStartHook: () => {
+        // gh#673 P2 (WI-1): the orientation hook lives PROJECT-LOCAL in
+        // <root>/.claude/settings.local.json — ensured on every bare
+        // `borg` launch so pre-P2 worktrees self-heal. The legacy GLOBAL
+        // hook is then removed after the local hook is in place.
+        addProjectSessionStartHook(findProjectRoot(process.cwd()));
+      },
+      removeClaudeGlobalSessionStartHook: removeSessionStartHook,
+      addClaudeUserPromptSubmitHook: addUserPromptSubmitHook,
+      addCodexSessionStartHook,
+      addCodexUserPromptSubmitHook,
+    });
+  } catch (err: any) {
+    console.error(`${consolePrefix()}${chalk.yellow(`warning: ${label} integration check failed: ${err?.message ?? err}`)}`);
   }
 }
 

package/src/cubes.ts

@@ -611,9 +611,14 @@ export async function readAllProjectIdentities(): Promise<
   );
 }
 
-export async function setProjectCliPreference(cli: BorgCli): Promise<void> {
+/**
+ * Save the CLI preference for the current project, or for an explicitly named
+ * worktree. The explicit path is used when assimilate has just created a
+ * sibling worktree but the process still began in the invoking checkout.
+ */
+export async function setProjectCliPreference(cli: BorgCli, dir?: string): Promise<void> {
   const existing = (await readLaunchFile()) ?? { projects: {} };
-  existing.projects[findProjectRoot()] = { cli };
+  existing.projects[findProjectRoot(dir)] = { cli };
   await writeLaunchFile(existing);
 }
 

package/src/parse-assimilate-args.ts

@@ -115,7 +115,13 @@ export function parseAssimilateArgs(rawArgs: string[]): ParseResult {
         if (enrollmentRequested) {
           return { ok: false, error: ENROLLMENT_POSITIONAL_INPUT_ERROR };
         }
-        return { ok: false, error: `unexpected extra argument: ${arg} (already have role "${role}")` };
+        return {
+          ok: false,
+          error:
+            `unexpected extra argument: ${arg} (already have role "${role}"). ` +
+            'Multi-word role names must be quoted (for example, `borg assimilate "Code Reviewer"`) ' +
+            'or written with hyphens.',
+        };
       }
       if (enrollmentRequested && !validateName(arg).ok) {
         return { ok: false, error: ENROLLMENT_POSITIONAL_INPUT_ERROR };

package/src/regen-format.ts

@@ -243,7 +243,7 @@ export function markArrivalAnnouncedThisProcess(): void {
 export function getDronePlaybook(): string {
   const arrivalInstruction = arrivalAnnouncedThisProcess
     ? ''
-    : '\n**When this MCP session first starts:** post one `ARRIVAL: <your-label> (<your-role>) online on <hostname> at <project-path>` (run `hostname`; use cwd for the path). After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit `/mcp` reconnect may show it again.\n';
+    : '\n**When this MCP session first starts:** post one `ARRIVAL: <your-label> (<your-role>) online on <hostname>` (run `hostname`). After the post succeeds, the client suppresses this instruction until the MCP process restarts; an explicit `/mcp` reconnect may show it again.\n';
   return `## How to operate as a Drone
 
 You're a Drone in a Cube. Coordinate with other drones through the activity log.
@@ -261,6 +261,12 @@ You're a Drone in a Cube. Coordinate with other drones through the activity log.
 
 **How coordination works:** the Cube gives primitives, not workflows. Your role's \`detailed_description\` (above) is your playbook — its conventions + signals come from there, not the system. The log is the coordination channel. Different cubes, different conventions.
 
+**Communication discipline for non-human seats:**
+- **Console:** write nothing except harness-required output. Surface something to the operator only when blocked and needing unblocking; do not narrate plans, progress, method, or results.
+- **Log:** a post must change what another seat does. Otherwise, do not write it. Keep posts short: lifecycle signal + SHA and nothing else; defect + location/evidence; correction to your live claim; or a genuine blocking question.
+- **Do not post:** plans, work-in-progress/progress narration, method or reasoning, restatements/agreement/credit, self-examination, framing phrases, or coordination commentary.
+- **Evidence boundary:** state what a verdict did not exercise and any unavailable control in the same short clause. The human seat is excluded so its dispatches can explain constraints without being misapplied.
+
 **Default: act autonomously, coordinate through the log.** Don't wait for user input. Need input → post the question, continue other work, other drones respond. The human supervisor is reachable through your cube's coordinating / human-seat role (the role your cube designates for direction + integration), or the Queen role when the seat is delegated to a drone — one continuous seat. Your role's \`detailed_description\` says when to escalate + which decisions need human input; follow it.
 
 **Operating loop — each wake, in order:**

package/src/resolved-cli-config.ts

@@ -0,0 +1,40 @@
+import type { BorgCli } from './cubes.js';
+
+export interface ResolvedCliConfigDeps {
+  ensureMcp(cli: BorgCli): void;
+  addClaudeProjectSessionStartHook(): void;
+  removeClaudeGlobalSessionStartHook(): void;
+  addClaudeUserPromptSubmitHook(): void;
+  addCodexSessionStartHook(): void;
+  addCodexUserPromptSubmitHook(): void;
+}
+/**
+ * Apply only the integration writes for the CLI the launcher resolved.
+ * In particular, a Claude installation must not cause Codex or OpenCode
+ * configuration to be repaired as a side effect of a bare `borg` launch.
+ */
+export function configureResolvedCli(
+  cli: BorgCli,
+  deps: ResolvedCliConfigDeps,
+): void {
+  if (cli === 'claude') {
+    deps.ensureMcp('claude');
+    // The project-local SessionStart hook is the launch-time self-heal for
+    // the CLI actually being launched. Remove only the obsolete global hook
+    // after the local hook is in place, then keep the Claude prompt hook in
+    // its existing global location.
+    deps.addClaudeProjectSessionStartHook();
+    deps.removeClaudeGlobalSessionStartHook();
+    deps.addClaudeUserPromptSubmitHook();
+    return;
+  }
+
+  if (cli === 'codex') {
+    deps.ensureMcp('codex');
+    deps.addCodexSessionStartHook();
+    deps.addCodexUserPromptSubmitHook();
+    return;
+  }
+
+  deps.ensureMcp('opencode');
+}

package/src/setup-selection.ts

@@ -0,0 +1,87 @@
+import type { BorgCli } from './cubes.js';
+
+export interface SetupAgentChoice {
+  title: string;
+  value: BorgCli;
+  selected: boolean;
+  disabled?: boolean;
+}
+
+export type SetupAgentSelection =
+  | { kind: 'selected'; agents: BorgCli[] }
+  | { kind: 'empty' }
+  | { kind: 'cancelled' };
+
+export interface EmptySetupOutcome {
+  kind: 'empty';
+  agentConfigurationChanged: false;
+  localServerInitializationStarted: false;
+  recovery: {
+    kind: 'rerun-setup';
+    command: 'borg setup';
+  };
+}
+
+const CLI_TITLES: Record<BorgCli, string> = {
+  claude: 'Claude Code',
+  codex: 'Codex',
+  opencode: 'OpenCode',
+};
+
+/** Build the first-run choices from the CLIs that are actually installed. */
+export function setupAgentChoices(
+  detected: readonly BorgCli[],
+  alreadyConfigured: ReadonlySet<BorgCli> = new Set(),
+): SetupAgentChoice[] {
+  return [...new Set(detected)].map((cli) => ({
+    title: alreadyConfigured.has(cli)
+      ? `${CLI_TITLES[cli]} (already configured)`
+      : CLI_TITLES[cli],
+    value: cli,
+    selected: !alreadyConfigured.has(cli),
+    ...(alreadyConfigured.has(cli) ? { disabled: true } : {}),
+  }));
+}
+
+/** The agent names whose newly selected setup needs a restart notice. */
+export function setupRestartInstruction(selected: readonly BorgCli[]): string {
+  const labels = selected.map((cli) => CLI_TITLES[cli]);
+  return `🔄 Restart ${labels.join(' / ')} (or open a new session) for the changes to take effect.`;
+}
+
+/** Describe the accepted zero-selection result and its recovery path. */
+export function emptySetupOutcome(): EmptySetupOutcome {
+  return {
+    kind: 'empty',
+    agentConfigurationChanged: false,
+    localServerInitializationStarted: false,
+    recovery: {
+      kind: 'rerun-setup',
+      command: 'borg setup',
+    },
+  };
+}
+
+/**
+ * Keep only detected agents and return them in detection order. The selected
+ * set is invocation-local; it is deliberately never persisted.
+ */
+export function normalizeSetupAgentSelection(
+  detected: readonly BorgCli[],
+  selected: readonly unknown[] | undefined,
+): BorgCli[] {
+  if (!Array.isArray(selected)) return [];
+  const selectedSet = new Set(selected);
+  return [...new Set(detected)].filter((cli) => selectedSet.has(cli));
+}
+
+/** Turn the prompt result into the terminal outcome used by the wizard. */
+export function resolveSetupAgentSelection(
+  detected: readonly BorgCli[],
+  selected: readonly unknown[] | undefined,
+  cancelled = false,
+): SetupAgentSelection {
+  if (cancelled) return { kind: 'cancelled' };
+  const agents = normalizeSetupAgentSelection(detected, selected);
+  return agents.length === 0 ? { kind: 'empty' } : { kind: 'selected', agents };
+}

package/src/setup.ts

@@ -39,6 +39,13 @@ import { initDebugFromArgv } from './debug.js';
 import { defaultApprovalIo, setupApprovalWarnings } from './cli-tool-approval.js';
 import { offerFirstRunServerInstall } from './first-run-server.js';
 import { setupNextStepsText } from './cli-help.js';
+import {
+  emptySetupOutcome,
+  resolveSetupAgentSelection,
+  setupAgentChoices,
+  setupRestartInstruction,
+} from './setup-selection.js';
+import type { BorgCli } from './cubes.js';
 
 /**
  * Main setup wizard
@@ -69,18 +76,8 @@ async function main() {
     process.exit(1);
   }
 
-  // Resolve the separately published local server before setup writes agent
-  // configuration. Decline/non-interactive/failure paths therefore leave no
-  // partial setup state behind.
-  console.log(chalk.blue('◼ Local Server'));
-  const serverInstall = await offerFirstRunServerInstall(undefined, undefined, { initializeServer: true });
-  if (serverInstall.kind !== 'present' && serverInstall.kind !== 'installed') {
-    process.exit(serverInstall.kind === 'declined' ? 0 : 1);
-  }
-  console.log('');
-  console.log('◼ Local server initialized');
-
-  // Step 1: Configure every detected agent CLI
+  // Step 1: Choose which detected agent CLIs to configure. The choice is
+  // first-run/invocation-local; it is never persisted as an opt-out.
   console.log(chalk.blue('◼ Agent CLI Integration'));
 
   const yes = parseYesFlag(process.argv);
@@ -88,6 +85,12 @@ async function main() {
   const claudeDetected = claudeCliPath !== null;
   const codexDetected = codexCliPath !== null;
   const opencodeDetected = opencodeCliPath !== null;
+  const detectedClis: BorgCli[] = [
+    ...(claudeDetected ? ['claude' as const] : []),
+    ...(codexDetected ? ['codex' as const] : []),
+    ...(opencodeDetected ? ['opencode' as const] : []),
+  ];
+
   const claudeMcpConfigured = isMcpServerConfigured();
   const codexMcpConfigured = isCodexMcpServerConfigured();
   const opencodeMcpConfigured = isOpenCodeMcpServerConfigured();
@@ -95,14 +98,73 @@ async function main() {
   const claudeUpsHookPending = claudeDetected && !isUserPromptSubmitHookRegistered();
   const codexSessionHookPending = codexDetected && !isCodexSessionStartHookRegistered();
   const codexUpsHookPending = codexDetected && !isCodexUserPromptSubmitHookRegistered();
-  const claudeHookPending = claudeLegacyHookPending || claudeUpsHookPending;
-  const codexHookPending = codexSessionHookPending || codexUpsHookPending;
+  const alreadyConfigured = new Set<BorgCli>([
+    ...(claudeDetected && claudeMcpConfigured && !claudeLegacyHookPending && !claudeUpsHookPending
+      ? ['claude' as const]
+      : []),
+    ...(codexDetected && codexMcpConfigured && !codexSessionHookPending && !codexUpsHookPending
+      ? ['codex' as const]
+      : []),
+    ...(opencodeDetected && opencodeMcpConfigured ? ['opencode' as const] : []),
+  ]);
+
+  const allDetectedMutationPending = setupMutationPending({
+    claude: claudeDetected,
+    codex: codexDetected,
+    opencode: opencodeDetected,
+    claudeMcpConfigured,
+    codexMcpConfigured,
+    opencodeMcpConfigured,
+    claudeHookPending: claudeLegacyHookPending || claudeUpsHookPending,
+    codexHookPending: codexSessionHookPending || codexUpsHookPending,
+  });
+
+  let selectedClis = detectedClis;
+  if (allDetectedMutationPending && !yes && process.stdin.isTTY === true) {
+    let cancelled = false;
+    const answer = await prompts(
+      {
+        type: 'multiselect',
+        name: 'selected',
+        message: 'Which detected agent CLIs should Borg configure?',
+        hint: 'Space toggles selection; Enter accepts the checked agents',
+        choices: setupAgentChoices(detectedClis, alreadyConfigured),
+        instructions: false,
+      },
+      {
+        onCancel: () => {
+          cancelled = true;
+        },
+      },
+    );
+    const selection = resolveSetupAgentSelection(detectedClis, answer.selected, cancelled);
+    if (selection.kind === 'cancelled') {
+      console.log(chalk.yellow('\n◼ Setup cancelled — no changes made.\n'));
+      return;
+    }
+    if (selection.kind === 'empty') {
+      const outcome = emptySetupOutcome();
+      console.log(chalk.yellow(
+        `\n◼ No agent CLIs selected — agent configuration and local-server initialization were skipped. ` +
+        `Run \`${outcome.recovery.command}\` again to choose an agent and continue setup.\n`,
+      ));
+      return;
+    }
+    selectedClis = selection.agents;
+  }
+
+  const selected = new Set(selectedClis);
+  const claudeSelected = selected.has('claude');
+  const codexSelected = selected.has('codex');
+  const opencodeSelected = selected.has('opencode');
+  const claudeHookPending = claudeSelected && (claudeLegacyHookPending || claudeUpsHookPending);
+  const codexHookPending = codexSelected && (codexSessionHookPending || codexUpsHookPending);
 
   if (
     setupMutationPending({
-      claude: claudeDetected,
-      codex: codexDetected,
-      opencode: opencodeDetected,
+      claude: claudeSelected,
+      codex: codexSelected,
+      opencode: opencodeSelected,
       claudeMcpConfigured,
       codexMcpConfigured,
       opencodeMcpConfigured,
@@ -112,7 +174,7 @@ async function main() {
   ) {
     console.log(
       formatConfigMutationDisclosure(
-        configMutationTargets({ claude: claudeDetected, codex: codexDetected, opencode: opencodeDetected })
+        configMutationTargets({ claude: claudeSelected, codex: codexSelected, opencode: opencodeSelected })
       )
     );
     const mutationDecision = await confirmConfigMutation({
@@ -135,7 +197,19 @@ async function main() {
   }
   console.log('');
 
-  if (claudeCliPath) {
+  // Resolve the separately published local server only after the complete
+  // agent selection and the existing single config-mutation confirmation.
+  // Esc/zero-selection/decline therefore leave both agent and server setup
+  // untouched.
+  console.log(chalk.blue('◼ Local Server'));
+  const serverInstall = await offerFirstRunServerInstall(undefined, undefined, { initializeServer: true });
+  if (serverInstall.kind !== 'present' && serverInstall.kind !== 'installed') {
+    process.exit(serverInstall.kind === 'declined' ? 0 : 1);
+  }
+  console.log('');
+  console.log('◼ Local server initialized');
+
+  if (claudeSelected) {
     try {
       ensureCliMcpConfigured('claude');
       if (claudeLegacyHookPending) removeSessionStartHook();
@@ -146,7 +220,7 @@ async function main() {
       process.exit(1);
     }
   }
-  if (codexCliPath) {
+  if (codexSelected) {
     try {
       ensureCliMcpConfigured('codex');
       if (codexSessionHookPending) addCodexSessionStartHook();
@@ -157,7 +231,7 @@ async function main() {
       process.exit(1);
     }
   }
-  if (opencodeCliPath) {
+  if (opencodeSelected) {
     try {
       ensureCliMcpConfigured('opencode');
       console.log(chalk.green('◼ borg configured for OpenCode'));
@@ -172,8 +246,8 @@ async function main() {
     codexArgs: [],
   });
   for (const warning of await setupApprovalWarnings(approvalIo, {
-    codex: codexDetected,
-    opencode: opencodeDetected,
+    codex: codexSelected,
+    opencode: opencodeSelected,
   })) {
     console.log(chalk.yellow(`warning: ${warning}`));
   }
@@ -185,7 +259,7 @@ async function main() {
 
   // Success message
   console.log(chalk.green.bold('\nSetup complete!\n'));
-  console.log(chalk.yellow('🔄 Restart Claude Code / Codex / OpenCode (or open a new session) for the changes to take effect.\n'));
+  console.log(chalk.yellow(`${setupRestartInstruction(selectedClis)}\n`));
   if (!serverInstall.suppressClientNextSteps) {
     console.log(chalk.gray(setupNextStepsText()));
   }