borgmcp 2.5.0 → 2.6.1

package/src/assimilate-cmd.ts

@@ -189,6 +189,9 @@ export interface AssimilateDeps {
   prompt: (message: string) => Promise<string>;
   promptSecret: (message: string) => Promise<string>;
   isTTY: () => boolean;
+  ensureLocalServerInstalled: (connectCommand: string) => Promise<
+    'present' | 'installed' | 'declined' | 'non-interactive' | 'failed'
+  >;
   /** Selected-harness approval inspection/consent (client#20). */
   resolveCliApprovals?: (cli: BorgCli, cwd: string) => Promise<LaunchApprovalDecision>;
 
@@ -360,6 +363,7 @@ function affirmative(answer: string): boolean {
 async function selectAssimilationAuthority(
   flags: AssimilateFlags,
   deps: AssimilateDeps,
+  mode: 'assimilate' | 'cube-init',
 ): Promise<AssimilationAuthority | null> {
   if (flags.server !== undefined) {
     try {
@@ -374,7 +378,10 @@ async function selectAssimilationAuthority(
   // NOT infer an authority — fail closed with actionable guidance.
   if (!deps.isTTY() || flags.yes) {
     if (deps.defaultAuthority) return deps.defaultAuthority;
-    deps.stderr('No local server selected. Use `borg assimilate --host <host> --here` to select a local server.\n');
+    const command = mode === 'cube-init'
+      ? '`borg server cube init --host <host>`'
+      : '`borg assimilate --host <host> --here`';
+    deps.stderr(`No local server selected. Use ${command} to select a local server.\n`);
     return null;
   }
 
@@ -403,8 +410,13 @@ async function selectAssimilationAuthority(
   }
 }
 
-function localAssimilateCommand(apiUrl: string, enroll = false): string {
-  return `\`borg assimilate --host ${apiUrl}${enroll ? ' --enroll' : ''}\``;
+function localAssimilateCommand(
+  apiUrl: string,
+  enroll = false,
+  mode: 'assimilate' | 'cube-init' = 'assimilate',
+): string {
+  const command = mode === 'cube-init' ? 'borg server cube init' : 'borg assimilate';
+  return `\`${command} --host ${apiUrl}${enroll ? ' --enroll' : ''}\``;
 }
 
 function localAssimilateRoleCommand(apiUrl: string): string {
@@ -420,36 +432,44 @@ function reportServerFailure(
   apiUrl: string,
   error: unknown,
   enroll = false,
+  mode: 'assimilate' | 'cube-init' = 'assimilate',
 ): number {
   const message = error instanceof Error ? error.message : String(error);
-  const retryCommand = localAssimilateCommand(apiUrl, enroll);
+  const retryCommand = localAssimilateCommand(apiUrl, enroll, mode);
   if (error instanceof BorgServerError && error.code === 'CREATE_CUBE_DENIED') {
     deps.stderr(
       `This enrolled client cannot create a cube on ${apiUrl}. ` +
         'Ask the server operator to grant access to a cube, then rerun ' +
-        `${localAssimilateCommand(apiUrl)}.\n`,
+        `${localAssimilateCommand(apiUrl, false, mode)}.\n`,
     );
     return 1;
   }
   if (error instanceof BorgServerError && error.code === 'NOT_ENROLLED') {
     deps.stderr(
-      `No saved enrollment for ${apiUrl}. Run ` +
-        `${localAssimilateCommand(apiUrl, true)} from the operator’s terminal.\n`,
+      `Borg could not find a saved enrollment for ${apiUrl}. ` +
+        `This can mean that this client has not enrolled with the server, or that its enrollment ` +
+        `is saved for a different endpoint. Confirm that the host, port, and IPv4 or IPv6 ` +
+        `loopback form in ${apiUrl} match the endpoint used during enrollment. ` +
+        `If this client has never enrolled with that server, run ` +
+        `${localAssimilateCommand(apiUrl, true, mode)} from the operator’s terminal.\n`,
     );
     return 1;
   }
   if (error instanceof BorgServerError && error.code === 'CREDENTIAL_REJECTED') {
     deps.stderr(
       `The saved enrollment for ${apiUrl} was rejected. Re-run ` +
-        `${localAssimilateCommand(apiUrl, true)} from the operator’s terminal.\n`,
+        `${localAssimilateCommand(apiUrl, true, mode)} from the operator’s terminal.\n`,
     );
     return 1;
   }
   if (error instanceof LegacySessionCredentialCollisionError) {
+    const recovery = mode === 'cube-init'
+      ? localAssimilateCommand(error.origin, true, mode)
+      : `borg assimilate --host ${error.origin} --enroll`;
     deps.stderr(
       `Local session credential collision detected.\n` +
         `No local credentials were changed.\n` +
-        `Next: run borg assimilate --host ${error.origin} --enroll.\n`,
+        `Next: run ${recovery}.\n`,
     );
     return 1;
   }
@@ -460,10 +480,10 @@ function reportServerFailure(
   // this worktree — no server/trust-anchor/cube/other-worktree reset, no restart
   // or version-alignment advice (#1082).
   if (error instanceof BorgServerError && error.code === 'SESSION_REVOKED') {
-    return diagnoseSessionTermination(deps, apiUrl, 'revoked');
+    return diagnoseSessionTermination(deps, apiUrl, 'revoked', mode);
   }
   if (error instanceof BorgServerError && error.code === 'SESSION_REJECTED') {
-    return diagnoseSessionTermination(deps, apiUrl, 'superseded');
+    return diagnoseSessionTermination(deps, apiUrl, 'superseded', mode);
   }
   if (error instanceof BorgServerError && error.code === 'INVITATION_REJECTED') {
     deps.stderr(
@@ -471,14 +491,14 @@ function reportServerFailure(
         'Ask the server operator for a replacement invitation — the server can stay running: ' +
         'for an unclaimed owner client run `borg-mcp-server owner-invite`; for an ordinary ' +
         'client run `borg-mcp-server client-invite`. Then rerun ' +
-        `${localAssimilateCommand(apiUrl, true)}.\n`,
+        `${localAssimilateCommand(apiUrl, true, mode)}.\n`,
     );
     return 1;
   }
   if (/HTTP 40[13]|auth(?:entication|orization)|credential.*(?:invalid|rejected)/i.test(message)) {
     deps.stderr(
       `The saved enrollment for ${apiUrl} was rejected. Re-run ` +
-        `${localAssimilateCommand(apiUrl, true)} from the operator’s terminal.\n`,
+        `${localAssimilateCommand(apiUrl, true, mode)} from the operator’s terminal.\n`,
     );
     return 1;
   }
@@ -545,13 +565,17 @@ function diagnoseSessionTermination(
   deps: AssimilateDeps,
   apiUrl: string,
   outcome: 'revoked' | 'superseded',
+  mode: 'assimilate' | 'cube-init' = 'assimilate',
 ): number {
   const message = outcome === 'revoked'
     ? 'Local session was revoked.'
     : 'Local session was superseded by a newer enrollment.';
+  const recovery = mode === 'cube-init'
+    ? localAssimilateCommand(apiUrl, true, mode)
+    : `borg assimilate --host ${apiUrl} --enroll`;
   deps.stderr(
     `${message}\n` +
-      `Next: run borg reset-local-seat, then borg assimilate --host ${apiUrl} --enroll.\n`,
+      `Next: run borg reset-local-seat, then ${recovery}.\n`,
   );
   return 1;
 }
@@ -586,7 +610,8 @@ export async function runAssimilate(
     repositoryContext = await deps.resolveRepositoryContext(deps.cwd());
   } catch (error) {
     if (error instanceof Error && error.message === 'BARE_REPOSITORY') {
-      deps.stderr('borg assimilate requires a non-bare repository worktree. Clone or check out the repository, then retry.\n');
+      const command = mode === 'cube-init' ? 'borg server cube init' : 'borg assimilate';
+      deps.stderr(`${command} requires a non-bare repository worktree. Clone or check out the repository, then retry.\n`);
       return 1;
     }
     repositoryContext = null;
@@ -600,6 +625,19 @@ export async function runAssimilate(
     return 1;
   }
 
+  if (args.flags.server === undefined && deps.defaultAuthority === undefined) {
+    const connectCommand = mode === 'cube-init'
+      ? 'borg server cube init --host <host>'
+      : 'borg assimilate --host <host>';
+    const serverInstall = await deps.ensureLocalServerInstalled(connectCommand);
+    if (serverInstall !== 'present') {
+      // A newly installed server still needs its explicit setup/start journey.
+      // Decline, non-interactive, and failure paths have already printed exact
+      // recovery commands. None may continue into private-state mutation.
+      return serverInstall === 'installed' ? 0 : 1;
+    }
+  }
+
   try {
     await deps.preparePrivateRoot();
   } catch {
@@ -618,16 +656,16 @@ export async function runAssimilate(
     hasPersistedIdentity = existing !== null || await deps.hasPersistedActiveCube();
   } catch (error) {
     if (error instanceof LegacySessionCredentialCollisionError) {
-      return reportServerFailure(deps, error.origin, error);
+      return reportServerFailure(deps, error.origin, error, false, mode);
     }
     localSeatReadError = error;
   }
 
   // ----- Step 1: Select and authenticate the local server -----
-  const authority = await selectAssimilationAuthority(args.flags, deps);
+  const authority = await selectAssimilationAuthority(args.flags, deps, mode);
   if (!authority) return 1;
   if (localSeatReadError !== undefined) {
-    return reportServerFailure(deps, authority.apiUrl, localSeatReadError);
+    return reportServerFailure(deps, authority.apiUrl, localSeatReadError, false, mode);
   }
 
   const projectRoot = repositoryContext.root;
@@ -644,7 +682,7 @@ export async function runAssimilate(
         if (!deps.isTTY()) {
           deps.stderr(
             'Local enrollment requires an interactive operator terminal. ' +
-              `Re-run ${localAssimilateCommand(authority.apiUrl, true)} from the operator’s terminal.\n`,
+              `Re-run ${localAssimilateCommand(authority.apiUrl, true, mode)} from the operator’s terminal.\n`,
           );
           return 1;
         }
@@ -663,7 +701,7 @@ export async function runAssimilate(
           if (!invitation) {
             deps.stderr(
               `No enrollment invitation was entered for ${authority.apiUrl}. ` +
-                `Ask the server operator for one, then rerun ${localAssimilateCommand(authority.apiUrl, true)}.\n`,
+                `Ask the server operator for one, then rerun ${localAssimilateCommand(authority.apiUrl, true, mode)}.\n`,
             );
             return 1;
           }
@@ -697,7 +735,7 @@ export async function runAssimilate(
         serverCapabilities: serverAuth.serverCapabilities ?? [],
       };
     } catch (error) {
-      return reportServerFailure(deps, authority.apiUrl, error, args.flags.enroll === true);
+      return reportServerFailure(deps, authority.apiUrl, error, args.flags.enroll === true, mode);
     }
   }
 
@@ -728,6 +766,8 @@ export async function runAssimilate(
       isTTY: deps.isTTY,
       prompt: deps.prompt,
       write: deps.stderr,
+      ...(mode === 'cube-init' ? { writeResult: deps.stdout } : {}),
+      useColor: () => deps.isTTY() && !process.env.NO_COLOR && !process.env.CI,
       getIdentity: deps.getRepositoryIdentity,
       getAssociation: (repository) => deps.getRepositoryAssociation(auth.serverTrustIdentity, repository),
       saveAssociation: (repository, association) =>
@@ -815,12 +855,12 @@ export async function runAssimilate(
     if (error instanceof BorgServerError && error.code === 'CREATE_CUBE_DENIED') {
       deps.stderr(
         `This enrolled client cannot create a cube on ${auth.apiUrl}. ` +
-        `Ask the server operator to grant access to a cube, then rerun ${localAssimilateCommand(auth.apiUrl)}.\n`,
+        `Ask the server operator to grant access to a cube, then rerun ${localAssimilateCommand(auth.apiUrl, false, mode)}.\n`,
       );
       return 1;
     }
     if (error instanceof BorgServerError) {
-      return reportServerFailure(deps, auth.apiUrl, error);
+      return reportServerFailure(deps, auth.apiUrl, error, false, mode);
     }
     deps.stderr(
       'Repository cube initialization failed.\n' +
@@ -1800,7 +1840,7 @@ export async function runAssimilate(
     // OpenCode assimilate launch: start TUI with the kickoff passed via
     // --prompt (auto-submits it as the first message). BORG_SESSION is
     // pinned in opencode.json. A unique port is assigned so the MCP child
-    // can connect via the HTTP API for context-streaming (injectOpenCodeEntry).
+    // can connect to OpenCode's local HTTP API for durable entry injection.
     dronePort = computeOpenCodePort(result.drone_id);
     installBorgPlugin();
     const cwd = agentCwd;
@@ -1824,9 +1864,8 @@ export async function runAssimilate(
       launchedAtSeconds: Math.floor(Date.now() / 1000),
     });
   }
-  // gh#opencode: inject the kickoff prompt into the TUI's first session via
-  // the SDK. OpenCode doesn't accept a prompt as a CLI arg, so we do it
-  // programmatically once the HTTP server is ready. Best-effort.
+  // gh#opencode: bind to the kickoff-bearing session through OpenCode's local
+  // HTTP API after the TUI auto-submits --prompt. Best-effort.
   if (cli === 'opencode' && openCodeKickoff) {
     const launchKickoff = openCodeKickoff;
     const serverUrl = `http://127.0.0.1:${dronePort}`;

package/src/assimilate-deps.ts

@@ -18,6 +18,10 @@ import { readinessProbeEnv } from './readiness-probe.js';
 import { resolveMcpBinaryPath } from './self-path.js';
 import { buildRuntimeMetadataReport } from './runtime-metadata.js';
 import { inspectLiveInboxMonitor } from './seat-reattach-guard.js';
+import {
+  buildDefaultFirstRunServerInstallDeps,
+  offerFirstRunServerInstall,
+} from './first-run-server.js';
 
 import type { AssimilateDeps } from './assimilate-cmd.js';
 import {
@@ -149,6 +153,11 @@ export function buildDefaultAssimilateDeps(
       return typeof result.invitation === 'string' ? result.invitation : '';
     },
     isTTY: () => process.stdin.isTTY === true,
+    ensureLocalServerInstalled: async (connectCommand) =>
+      (await offerFirstRunServerInstall(
+        buildDefaultFirstRunServerInstallDeps(),
+        connectCommand,
+      )).kind,
     resolveCliApprovals: (cli, cwd) => resolveLaunchBorgApprovals(
       cli,
       defaultApprovalIo(

package/src/claude.ts

@@ -82,7 +82,7 @@ import { ensureCliMcpConfigured } from './ensure-mcp-config.js';
 import { installBorgPlugin } from './opencode-plugin.js';
 import { connectOpenCodeDrone, computeOpenCodePort, createOpenCodeLaunchKickoff, injectInitialKickoff } from './opencode-drone.js';
 import { buildOpenCodeLaunchArgs, defaultApprovalIo, resolveLaunchBorgApprovals } from './cli-tool-approval.js';
-import { runEarlyServerFacade } from './server-facade.js';
+import { isClientOwnedCubeInitArgv, runEarlyServerFacade } from './server-facade.js';
 import { runEarlyUpdate } from './update-cmd.js';
 
 export type AssimilateDepsBuilder = typeof buildDefaultAssimilateDeps;
@@ -106,6 +106,13 @@ async function main() {
   const updateExitCode = await runEarlyUpdate(process.argv);
   if (updateExitCode !== null) process.exit(updateExitCode);
 
+  // Cube initialization is client-owned, so enable debug before its early
+  // facade dispatch. Server lifecycle commands keep their argv verbatim:
+  // their separate executable owns and parses `--debug`.
+  if (isClientOwnedCubeInitArgv(process.argv)) {
+    initDebugFromArgv(process.argv);
+  }
+
   const serverExitCode = await runEarlyServerFacade(process.argv);
   if (serverExitCode !== null) process.exit(serverExitCode);
 
@@ -462,7 +469,7 @@ async function main() {
     // OpenCode launch: start TUI with the kickoff passed via --prompt
     // (auto-submits it as the first message). BORG_SESSION is pinned in
     // opencode.json. A unique port is assigned so the MCP child can connect
-    // via the HTTP API for context-streaming (injectOpenCodeEntry).
+    // to OpenCode's local HTTP API for durable entry injection.
     const dronePort = active
       ? computeOpenCodePort(active.droneId)
       : 14096;
@@ -500,7 +507,7 @@ async function main() {
   }
 
   // gh#857 WI-2: wake-target recording is codex-only (app-server bridge).
-  // OpenCode has no remote-wake mechanisms yet; claude uses the inbox Monitor.
+  // OpenCode uses HTTP entry injection; Claude uses the inbox Monitor.
   if (cli === 'codex' && active && codexSocketPath) {
     void recordCodexWakeTarget({
       deps: { setCodexWakeTarget, findLoadedCodexThread },

package/src/cli-help.ts

@@ -31,7 +31,7 @@ export function topLevelHelpText(version: string): string {
     `  borg assimilate [role]   Join or create a cube\n` +
     `  borg assimilate --host <host>   Join or create on an explicit server\n` +
     `  borg assimilate --worktree <name>   Spawn a worktree drone (in ~/.borg/worktrees/<repo>/<name>)\n` +
-    `  borg server cube init   Initialize this repository's cube without creating a drone\n` +
+    `  borg server cube init    Initialize this repository's cube without creating a drone\n` +
     `  borg reset-local-seat    Clear ONLY this worktree's saved local seat (offline; after a rejection)\n` +
     `  borg sync [--prune]      Sync this worktree's branch to origin/main\n` +
     `  borg cleanup [--prune]   Report (or --prune) worktrees orphaned by evicted drones\n` +
@@ -82,9 +82,9 @@ export function serverHelpText(): string {
 }
 
 /** Client-owned help for repository cube initialization without a drone. */
-export function cubeInitHelpText(): string {
+export function cubeInitHelpText(version: string): string {
   return (
-    `borg server cube init — initialize this Git repository's cube without creating a drone\n\n` +
+    `borg server cube init (borgmcp ${version}) — initialize this Git repository's cube without creating a drone\n\n` +
     `Usage:\n` +
     `  borg server cube init [options]\n\n` +
     `Options:\n` +
@@ -93,7 +93,10 @@ export function cubeInitHelpText(): string {
     `  --cube-name <name>               Repository cube name (otherwise edit the proposed name)\n` +
     `  --template software-dev|starter  New-cube template (default: software-dev)\n` +
     `  --yes, -y                        Accept new-cube defaults; never adopt by name\n` +
-    `  --help, -h                       Show this help\n`
+    `  --help, -h                       Show this help\n\n` +
+    `An existing repository association skips all prompts. One accessible exact-name legacy\n` +
+    `cube requires explicit interactive adoption; ambiguous matches fail closed. An enrolled\n` +
+    `owner client may create a repository cube; ordinary clients require an explicit cube grant.\n`
   );
 }
 

package/src/codex-launch.ts

@@ -1,5 +1,6 @@
 import type { BorgCli } from './cubes.js';
 import { wakePathArming, type AgentKind } from './regen-format.js';
+import { OPENCODE_WAKE_PATH_GUIDANCE } from './opencode-wake-copy.js';
 
 /**
  * The claude kickoff prompt's wake-path section (gh#929) — the SAME shared
@@ -7,8 +8,8 @@ import { wakePathArming, type AgentKind } from './regen-format.js';
  * not three), plus a one-line NEVER-TaskStop safety reminder preserved from
  * the pre-gh#929 monitorClause. Built by both launch call sites
  * (claude.ts + assimilate-cmd.ts) and passed to `buildAgentKickoffPrompt` as
- * `monitorClause`. Codex wakes via the app-server (no tail-Monitor / `/loop`
- * to arm) → empty; no active cube (no inboxPath) → empty.
+ * `monitorClause`. Codex wakes via the app-server (no tail-Monitor to arm) →
+ * empty; no active cube (no inboxPath) → empty.
  */
 export function buildKickoffWakePathClause(
   agentKind: AgentKind,
@@ -19,8 +20,8 @@ export function buildKickoffWakePathClause(
     return (
       wakePathArming('claude', inboxPath, monitorStateRoot) +
       '\nKeep this Monitor armed for the whole session — NEVER TaskStop it (the generic ' +
-      '/loop "TaskStop any Monitor you armed" step does NOT apply to the cube inbox Monitor; ' +
-      'it targets throwaway loop-scratch watches only). The sole exception is a confirmed ' +
+      '"TaskStop any Monitor you armed" guidance does NOT apply to the cube inbox Monitor; ' +
+      'it targets throwaway scratch watches only). The sole exception is a confirmed ' +
       'terminal eviction (410 DRONE_EVICTED). '
     );
   }
@@ -60,15 +61,14 @@ export function buildAgentKickoffPrompt(options: {
   const codexWakePathClause =
     options.codexWakePathClause ??
     `Codex Borg wakeups use remote-control when available; if no wake arrives, run borg_regen manually when returning to the session.`;
-  const opencodeWakePathClause = `OpenCode wakes: the inbox Monitor is not available yet for OpenCode; check activity by calling borg_read-log periodically.`;
-  const loopOrEmpty = options.cli === 'claude' ? '/loop ' : '';
+  const opencodeWakePathClause = OPENCODE_WAKE_PATH_GUIDANCE;
   const wakeClause = options.cli === 'claude'
     ? options.monitorClause
     : options.cli === 'codex'
       ? codexWakePathClause
       : opencodeWakePathClause;
   return (
-    `${loopOrEmpty}Call borg_regen and follow the playbook in its response. ` +
+    `Call borg_regen and follow the playbook in its response. ` +
     codexNonceClause +
     `Note: at session start the borg MCP server is still spinning up in ` +
     `parallel — if a system reminder claims "MCP server disconnected" or ` +

package/src/first-run-server.ts

@@ -0,0 +1,178 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  buildDefaultUpdateDeps,
+  isExactSemver,
+  resolveCompatibleServerTarget,
+  type InstalledPackage,
+  type PublishedPackage,
+  type UpdateDeps,
+} from './update-cmd.js';
+
+const CLIENT_PACKAGE = 'borgmcp';
+const SERVER_PACKAGE = 'borgmcp-server';
+const SHARED_PACKAGE = 'borgmcp-shared';
+const DEFAULT_CONNECT_COMMAND = 'borg assimilate --host <host>';
+
+export type FirstRunServerInstallResult =
+  | { kind: 'present'; server: InstalledPackage }
+  | { kind: 'installed'; server: InstalledPackage }
+  | { kind: 'declined' | 'non-interactive' | 'failed' };
+
+export interface FirstRunServerInstallDeps {
+  currentServer(): Promise<InstalledPackage | null>;
+  publishedPackage(
+    name: 'borgmcp' | 'borgmcp-server',
+    version: string,
+  ): Promise<PublishedPackage>;
+  publishedVersions(name: 'borgmcp' | 'borgmcp-server'): Promise<string[]>;
+  installGlobal(
+    name: 'borgmcp' | 'borgmcp-server',
+    version: string,
+    options?: { ignoreScripts?: boolean },
+  ): Promise<void>;
+  confirm(message: string): Promise<'yes' | 'no' | 'eof' | 'interrupted'>;
+  isTTY(): boolean;
+  stdout(text: string): void;
+  stderr(text: string): void;
+  clientSharedVersion(): string;
+}
+
+function readClientSharedVersion(): string {
+  const here = fileURLToPath(import.meta.url);
+  const manifestPath = join(dirname(here), '..', 'package.json');
+  const parsed: unknown = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('installed borgmcp package manifest is invalid');
+  }
+  const dependencies = (parsed as Record<string, unknown>).dependencies;
+  if (!dependencies || typeof dependencies !== 'object' || Array.isArray(dependencies)) {
+    throw new Error('installed borgmcp dependency manifest is invalid');
+  }
+  const version = (dependencies as Record<string, unknown>)[SHARED_PACKAGE];
+  if (!isExactSemver(version)) {
+    throw new Error(`installed ${CLIENT_PACKAGE} does not declare an exact ${SHARED_PACKAGE} pin`);
+  }
+  return version;
+}
+
+function exactInstallCommand(version: string): string {
+  return `npm install --global --ignore-scripts ${SERVER_PACKAGE}@${version}`;
+}
+
+function assertInstalledServer(
+  installed: InstalledPackage | null,
+  published: PublishedPackage,
+): asserts installed is InstalledPackage {
+  if (
+    installed?.name !== SERVER_PACKAGE ||
+    installed.version !== published.version ||
+    installed.sharedVersion !== published.sharedVersion
+  ) {
+    throw new Error(
+      `installation verification expected ${SERVER_PACKAGE}@${published.version} with ` +
+      `${SHARED_PACKAGE}@${published.sharedVersion}`,
+    );
+  }
+}
+
+export function buildDefaultFirstRunServerInstallDeps(): FirstRunServerInstallDeps {
+  const update: UpdateDeps = buildDefaultUpdateDeps();
+  return {
+    currentServer: update.currentServer,
+    publishedPackage: update.publishedPackage,
+    publishedVersions: update.publishedVersions,
+    installGlobal: update.installGlobal,
+    confirm: update.confirm,
+    isTTY: update.isTTY,
+    stdout: update.stdout,
+    stderr: update.stderr,
+    clientSharedVersion: readClientSharedVersion,
+  };
+}
+
+/**
+ * Offer the exact compatible server before first-run setup mutates state.
+ * Returning anything except `present`/`installed` means no caller-owned setup
+ * or assimilation work should continue.
+ */
+export async function offerFirstRunServerInstall(
+  deps: FirstRunServerInstallDeps = buildDefaultFirstRunServerInstallDeps(),
+  connectCommand = DEFAULT_CONNECT_COMMAND,
+): Promise<FirstRunServerInstallResult> {
+  let installed: InstalledPackage | null;
+  try {
+    installed = await deps.currentServer();
+  } catch (error) {
+    deps.stderr(
+      `The local ${SERVER_PACKAGE} installation could not be verified. No installation was attempted.\n` +
+      `Run \`borg server status\` to inspect it, or repair the npm-global installation and run this command again.\n` +
+      `${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    return { kind: 'failed' };
+  }
+  if (installed) return { kind: 'present', server: installed };
+
+  if (!deps.isTTY()) {
+    deps.stderr(
+      `No local ${SERVER_PACKAGE} installation was found. No installation was attempted because this terminal is non-interactive.\n` +
+      `Run \`borg setup\` in an interactive terminal, or connect to an existing server with ` +
+      `\`${connectCommand}\`.\n`,
+    );
+    return { kind: 'non-interactive' };
+  }
+
+  let target: PublishedPackage;
+  try {
+    const sharedVersion = deps.clientSharedVersion();
+    target = await resolveCompatibleServerTarget(sharedVersion, deps);
+  } catch (error) {
+    deps.stderr(
+      `Borg could not resolve a compatible local server. No installation was attempted.\n` +
+      `${error instanceof Error ? error.message : String(error)}\n` +
+      `Run \`borg update\`, then run \`borg setup\` again. Or connect to an existing server with ` +
+      `\`${connectCommand}\`.\n`,
+    );
+    return { kind: 'failed' };
+  }
+
+  const command = exactInstallCommand(target.version);
+  const decision = await deps.confirm(
+    `No local ${SERVER_PACKAGE} installation was found. ` +
+    `Install ${SERVER_PACKAGE}@${target.version}, which uses ${SHARED_PACKAGE}@${target.sharedVersion}, now?\n` +
+    `Command: ${command}\n` +
+    `Continue? [y/N] `,
+  );
+  if (decision !== 'yes') {
+    const reason = decision === 'interrupted'
+      ? 'Installation was cancelled by SIGINT.'
+      : decision === 'eof'
+        ? 'Installation was cancelled because confirmation input ended.'
+        : 'Installation was declined.';
+    deps.stderr(
+      `${reason} No server package or server state was changed.\n` +
+      `To install it later, run \`${command}\`. Then run \`borg server setup\` and \`borg server start\`.\n`,
+    );
+    return { kind: 'declined' };
+  }
+
+  try {
+    await deps.installGlobal(SERVER_PACKAGE, target.version, { ignoreScripts: true });
+    installed = await deps.currentServer();
+    assertInstalledServer(installed, target);
+  } catch (error) {
+    deps.stderr(
+      `The ${SERVER_PACKAGE}@${target.version} installation could not be completed and verified.\n` +
+      `${error instanceof Error ? error.message : String(error)}\n` +
+      `Run \`${command}\` to retry. Then run \`borg server setup\` and \`borg server start\`.\n`,
+    );
+    return { kind: 'failed' };
+  }
+
+  deps.stdout(
+    `Installed ${SERVER_PACKAGE}@${target.version} with ${SHARED_PACKAGE}@${target.sharedVersion}.\n` +
+    `Next, run \`borg server setup\`, then run \`borg server start\` in a terminal you keep open.\n`,
+  );
+  return { kind: 'installed', server: installed };
+}