borgmcp 2.8.0 → 2.9.0

package/docs/RELEASING.md

@@ -173,8 +173,13 @@ Never move, replace, reuse, or rerun that tag or workflow. The annotated `v2.7.3
 `83fadd1b308f2b770ce0d8da6a3b61183ec94f8d`. Workflow run `30618377765`, attempt 1,
 successfully published that exact source as `borgmcp@2.7.3`; the same-run artifact report records integrity
 `sha512-Jb+Kg/+H3cPU34JX7eFV3gEO/PzdfJEruNU1mJwYlQZKG7TMfrLJzwghDzxmlMupHJHL3rzAVZ224wioM/pclg==`.
+Never move, replace, reuse, or rerun that tag or workflow. The annotated `v2.8.0` tag object
+`576e2401a83537662ef0d5f7b0d03d6101b15c54` peels to protected-main commit
+`ad40e93ee9b1ff2801119c1c763ad526974ae2a6`. Workflow run `30639790368`, attempt 1,
+successfully published that exact source as `borgmcp@2.8.0`; the same-run artifact report records integrity
+`sha512-hKNyWwVg/8WJ/qcqaNjZVylMw2UzgFEhE7sAJmWy/BjNU4lEa6ox8N7SdbEt8hhKsySMxt+YTFbNFitRtf9u3g==`.
 Never move, replace, reuse, or rerun that tag or workflow. The next candidate
-uses the unused `v2.8.0` identity from a fresh reviewed protected-main commit
+uses the unused `v2.9.0` identity from a fresh reviewed protected-main commit
 and requires the complete release gate again.
 
 ## Release Prerequisites

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",

package/src/assimilate-cmd.ts

@@ -277,7 +277,7 @@ export interface AssimilateDeps {
   detectLocalServer: () => Promise<string | null>;
   connectServer: (
     apiUrl: string,
-    enrollment?: { invitation: string },
+    enrollment?: { invitation: string; confirmReplacement?: () => Promise<boolean> },
   ) => Promise<{
     token: string;
     trustIdentity: string;
@@ -361,6 +361,11 @@ function affirmative(answer: string): boolean {
   return normalized === '' || normalized === 'y' || normalized === 'yes';
 }
 
+function strictAffirmative(answer: string): boolean {
+  const normalized = answer.trim().toLowerCase();
+  return normalized === 'y' || normalized === 'yes';
+}
+
 async function selectAssimilationAuthority(
   flags: AssimilateFlags,
   deps: AssimilateDeps,
@@ -475,6 +480,14 @@ function reportServerFailure(
     );
     return 1;
   }
+  if (error instanceof BorgServerError && error.code === 'LOCAL_CREDENTIAL_EXISTS') {
+    deps.stderr(
+      `A local enrollment for ${apiUrl} already exists and was not replaced. ` +
+        `Re-run ${localAssimilateCommand(apiUrl, true, mode)} and explicitly confirm replacement ` +
+        'only if the first enrolled client should be abandoned.\n',
+    );
+    return 1;
+  }
   if (error instanceof LegacySessionCredentialCollisionError) {
     const recovery = mode === 'cube-init'
       ? localAssimilateCommand(error.origin, true, mode)
@@ -729,8 +742,14 @@ export async function runAssimilate(
             );
             return 1;
           }
-          try {
-            serverAuth = await deps.connectServer(authority.apiUrl, { invitation });
+           try {
+             serverAuth = await deps.connectServer(authority.apiUrl, {
+               invitation,
+               confirmReplacement: async () => strictAffirmative(await deps.prompt(
+                 `A local enrollment for ${authority.apiUrl} already exists. Replacing it will orphan ` +
+                   'the first enrolled client. Replace it? [y/N]: ',
+               )),
+             });
           } finally {
             // Strings cannot be zeroized in JavaScript, but drop this command's
             // reference immediately after the exchange instead of retaining the
@@ -1492,7 +1511,7 @@ export async function runAssimilate(
       deps.stderr(
         'Borg could not enumerate this repository’s existing worktrees, so it did not risk creating a colliding sibling.\n' +
         'Run `git worktree list` from this repository and resolve the reported Git error, then rerun `borg assimilate`.\n' +
-        'A seat was reserved and remains pending; rerunning after fixing the worktree issue resumes that seat.\n',
+        'A local drone reservation was created and remains pending; rerunning after fixing the worktree issue resumes that reservation.\n',
       );
       return 1;
     }
@@ -1565,13 +1584,13 @@ export async function runAssimilate(
           ? `Git left branch ${residualBranch} without a registered worktree; Borg preserved it.\n`
           : '') +
         'Run `git worktree list` and `git status` to inspect repository state, resolve the reported Git error, then rerun `borg assimilate`.\n' +
-        'A seat was reserved and remains pending; rerunning after fixing the worktree issue resumes that seat.\n',
+        'A local drone reservation was created and remains pending; rerunning after fixing the worktree issue resumes that reservation.\n',
       );
       return 1;
     }
     deps.stderr(
       `spawned sibling worktree at ${candidate} on branch ${wtBranch} (${startRef}); ` +
-      `the original dir keeps its active seat — run \`borg reset-local-seat\` there if that binding is stale.\n`
+      `the original dir keeps its active drone binding — run \`borg reset-local-seat\` there if that binding is stale.\n`
     );
     deps.chdir(candidate);
     deps.stderr(renderWorktreeSteeringNote(candidate, wtBranch, projectRoot));

package/src/assimilate-deps.ts

@@ -241,6 +241,9 @@ export function buildDefaultAssimilateDeps(
     connectServer: async (apiUrl, enrollment) => {
       if (enrollment) {
         return enrollLocalBorgServer(apiUrl, enrollment.invitation, {
+          ...(enrollment.confirmReplacement === undefined
+            ? {}
+            : { confirmReplacement: enrollment.confirmReplacement }),
           clientName: osHostname(),
         });
       }

package/src/cli-help.ts

@@ -74,9 +74,8 @@ export function clientSubcommandHelpText(
 export function setupNextStepsText(): string {
   return (
     `◼ Next steps:\n` +
-    `1. Run \`borg server setup\` to prepare the local server.\n` +
-    `2. Run \`borg server start\` and leave that terminal open.\n` +
-    `3. In a second terminal, cd into your project and run \`borg assimilate\`.\n`
+    `1. Run \`borg server start\` and leave that terminal open.\n` +
+    `2. In a second terminal, cd into your project's Git repository and run \`borg assimilate\`.\n`
   );
 }
 

package/src/config.ts

@@ -447,6 +447,7 @@ export async function activatePendingServerEnrollment(
     credential: string;
     clientId: string;
     serverCapabilities: ServerCapability[];
+    allowReplacement?: boolean;
   },
 ): Promise<void> {
   validateServerCredentialBinding(input.origin, input.trustIdentity);
@@ -471,6 +472,9 @@ export async function activatePendingServerEnrollment(
     } catch {
       throw new Error('pending Borg server enrollment does not match the verified response');
     }
+    if (!input.allowReplacement && await backend.get(serverCredentialAccount(input.origin, input.trustIdentity))) {
+      throw new Error('local Borg server enrollment already exists');
+    }
     // Already inside the single store lock — use the UNLOCKED write body so we do
     // not re-acquire (and self-deadlock on) CREDENTIALS_LOCK (CR3b).
     await writeServerCredentialRecord(backend, {

package/src/first-run-server.ts

@@ -1,3 +1,4 @@
+import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -14,10 +15,12 @@ const CLIENT_PACKAGE = 'borgmcp';
 const SERVER_PACKAGE = 'borgmcp-server';
 const SHARED_PACKAGE = 'borgmcp-shared';
 const DEFAULT_CONNECT_COMMAND = 'borg assimilate --host <host>';
+const CLIENT_ONBOARDING_ENV = 'BORG_CLIENT_ONBOARDING';
+export const HINT_SUPPORTED_FROM = '0.8.1';
 
 export type FirstRunServerInstallResult =
-  | { kind: 'present'; server: InstalledPackage }
-  | { kind: 'installed'; server: InstalledPackage }
+  | { kind: 'present'; server: InstalledPackage; suppressClientNextSteps?: boolean }
+  | { kind: 'installed'; server: InstalledPackage; suppressClientNextSteps?: boolean }
   | { kind: 'declined' | 'non-interactive' | 'failed' };
 
 export interface FirstRunServerInstallDeps {
@@ -32,7 +35,8 @@ export interface FirstRunServerInstallDeps {
     version: string,
     options?: { ignoreScripts?: boolean },
   ): Promise<void>;
-  confirm(message: string): Promise<'yes' | 'no' | 'eof' | 'interrupted'>;
+  runServerSetup(server: InstalledPackage, options?: { onboardingHint?: boolean }): Promise<number>;
+  confirm(message: string, defaultYes?: boolean): Promise<'yes' | 'no' | 'eof' | 'interrupted'>;
   isTTY(): boolean;
   stdout(text: string): void;
   stderr(text: string): void;
@@ -84,6 +88,18 @@ export function buildDefaultFirstRunServerInstallDeps(): FirstRunServerInstallDe
     publishedPackage: update.publishedPackage,
     publishedVersions: update.publishedVersions,
     installGlobal: update.installGlobal,
+    runServerSetup: (server, options = {}) => new Promise((resolve) => {
+      const childEnv = { ...process.env };
+      delete childEnv[CLIENT_ONBOARDING_ENV];
+      if (options.onboardingHint) childEnv[CLIENT_ONBOARDING_ENV] = '1';
+      const child = spawn(server.binPath, ['setup'], {
+        stdio: 'inherit',
+        shell: false,
+        env: childEnv,
+      });
+      child.once('error', () => resolve(1));
+      child.once('exit', (code) => resolve(code ?? 1));
+    }),
     confirm: update.confirm,
     isTTY: update.isTTY,
     stdout: update.stdout,
@@ -100,6 +116,7 @@ export function buildDefaultFirstRunServerInstallDeps(): FirstRunServerInstallDe
 export async function offerFirstRunServerInstall(
   deps: FirstRunServerInstallDeps = buildDefaultFirstRunServerInstallDeps(),
   connectCommand = DEFAULT_CONNECT_COMMAND,
+  options: { initializeServer?: boolean } = {},
 ): Promise<FirstRunServerInstallResult> {
   let installed: InstalledPackage | null;
   try {
@@ -112,7 +129,15 @@ export async function offerFirstRunServerInstall(
     );
     return { kind: 'failed' };
   }
-  if (installed) return { kind: 'present', server: installed };
+  if (installed) {
+    return initializeServerIfRequested(
+      installed,
+      deps,
+      options.initializeServer,
+      'present',
+      shouldSuppressClientNextSteps(installed.version),
+    );
+  }
 
   if (!deps.isTTY()) {
     deps.stderr(
@@ -140,9 +165,11 @@ export async function offerFirstRunServerInstall(
   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` +
+      `Install ${SERVER_PACKAGE}@${target.version}, the local coordination server, ` +
+      `which uses ${SHARED_PACKAGE}@${target.sharedVersion}, now?\n` +
     `Command: ${command}\n` +
-    `Continue? [y/N] `,
+      `Install it now? [Y/n] `,
+      true,
   );
   if (decision !== 'yes') {
     const reason = decision === 'interrupted'
@@ -172,7 +199,43 @@ export async function offerFirstRunServerInstall(
 
   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`,
+    (options.initializeServer
+      ? `The local server package is ready.\n`
+      : `Next, run \`borg server setup\`, then run \`borg server start\` in a terminal you keep open.\n`),
+  );
+  return initializeServerIfRequested(installed, deps, options.initializeServer, 'installed');
+}
+
+async function initializeServerIfRequested(
+  server: InstalledPackage,
+  deps: FirstRunServerInstallDeps,
+  requested: boolean | undefined,
+  kind: 'present' | 'installed',
+  suppressClientNextSteps = false,
+): Promise<FirstRunServerInstallResult> {
+  if (!requested) return { kind, server, ...(suppressClientNextSteps ? { suppressClientNextSteps: true } : {}) };
+  try {
+    const exitCode = await deps.runServerSetup(server, { onboardingHint: !suppressClientNextSteps });
+    if (exitCode === 0) {
+      return { kind, server, ...(suppressClientNextSteps ? { suppressClientNextSteps: true } : {}) };
+    }
+  } catch (error) {
+    deps.stderr(`Local server setup could not be completed. ${error instanceof Error ? error.message : String(error)}\n`);
+  }
+  deps.stderr(
+    'Run `borg server setup` to retry local server initialization, then run `borg server start`.\n',
   );
-  return { kind: 'installed', server: installed };
+  return { kind: 'failed' };
+}
+
+function shouldSuppressClientNextSteps(version: unknown): boolean {
+  if (!isExactSemver(version)) return false;
+  const installedParts = version.split('.').slice(0, 3).map(Number);
+  const supportedParts = HINT_SUPPORTED_FROM.split('.').map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (installedParts[index] !== supportedParts[index]) {
+      return installedParts[index] < supportedParts[index];
+    }
+  }
+  return false;
 }

package/src/remote-client.ts

@@ -1041,7 +1041,7 @@ export async function regen(
   opts: {
     since?: string;
     /** Advisory self-report from the running agent; never model-routing config. */
-    reportedModel?: string;
+    reportedModel?: string | null;
     /** Positively identified running Agent CLI; null means explicitly unknown. */
     agentKind?: AgentKind | null;
     /** Current cwd-derived identity; refreshed each regen to avoid stale routing data. */
@@ -1077,7 +1077,7 @@ export async function regen(
   ) {
     const patch = buildRuntimeMetadataPatch({
       agentKind: opts.agentKind ?? null,
-      reportedModel: opts.reportedModel,
+      reportedModel: opts.reportedModel ?? null,
       workingRepo: opts.workingRepo,
     });
     try {

package/src/runtime-metadata.ts

@@ -53,13 +53,14 @@ export function buildRuntimeMetadataReport(input: {
 
 export function buildRuntimeMetadataPatch(input: {
   agentKind: AgentKind | null;
-  reportedModel?: string;
+  reportedModel?: string | null;
   workingRepo?: WorkingRepo;
 }): DroneRuntimeMetadataPatch {
   const patch: DroneRuntimeMetadataPatch = { agent_kind: input.agentKind };
   if (input.reportedModel !== undefined) {
-    const model = safeReportedModel(input.reportedModel);
-    if (model !== null) patch.reported_model = model;
+    patch.reported_model = input.reportedModel === null
+      ? null
+      : validateReportedModel(input.reportedModel);
   }
   const repository = reportableRepository(input.workingRepo);
   if (repository) Object.assign(patch, repository);

package/src/server-errors.ts

@@ -2,6 +2,7 @@ export type BorgServerErrorCode =
   | 'NOT_ENROLLED'
   | 'CREDENTIAL_REJECTED'
   | 'INVITATION_REJECTED'
+  | 'LOCAL_CREDENTIAL_EXISTS'
   | 'CREATE_CUBE_DENIED'
   | 'ATTACH_CONFLICT'
   | 'SESSION_REJECTED'

package/src/server-handshake.ts

@@ -452,6 +452,8 @@ export async function enrollBorgServer(
     prepareEnrollment?: typeof getOrCreatePendingServerEnrollment;
     activateEnrollment?: typeof activatePendingServerEnrollment;
     clearPendingEnrollment?: typeof clearPendingServerEnrollment;
+    loadCredentialRecord?: typeof getServerCredentialRecord;
+    confirmReplacement?: () => Promise<boolean>;
     clientName?: string;
   } = {},
 ): Promise<NewServerEnrollment> {
@@ -461,6 +463,24 @@ export async function enrollBorgServer(
   // persisted and before any invitation/secret-bearing request is sent.
   const protocol = await preflightBorgServerTag(origin, fetchImpl);
 
+  const existingCredential = await (deps.loadCredentialRecord ?? getServerCredentialRecord)(
+    origin,
+    trustIdentity,
+  );
+  let replacementConfirmed = false;
+  if (existingCredential) {
+    const confirmed = deps.confirmReplacement !== undefined
+      ? await deps.confirmReplacement()
+      : false;
+    if (!confirmed) {
+      throw new BorgServerError(
+        'LOCAL_CREDENTIAL_EXISTS',
+        'a local enrollment already exists for this server and was not replaced',
+      );
+    }
+    replacementConfirmed = true;
+  }
+
   const pending = await (deps.prepareEnrollment ?? getOrCreatePendingServerEnrollment)({
     origin,
     trustIdentity,
@@ -528,6 +548,7 @@ export async function enrollBorgServer(
     credential: pending.credential,
     clientId: decoded.payload.client_id,
     serverCapabilities: decoded.payload.server_capabilities,
+    ...(replacementConfirmed ? { allowReplacement: true } : {}),
   });
   return {
     token: pending.credential,
@@ -1011,6 +1032,8 @@ export async function enrollLocalBorgServer(
     prepareEnrollment?: typeof getOrCreatePendingServerEnrollment;
     activateEnrollment?: typeof activatePendingServerEnrollment;
     clearPendingEnrollment?: typeof clearPendingServerEnrollment;
+    loadCredentialRecord?: typeof getServerCredentialRecord;
+    confirmReplacement?: () => Promise<boolean>;
     clientName?: string;
   } = {},
 ): Promise<NewServerEnrollment> {
@@ -1022,6 +1045,12 @@ export async function enrollLocalBorgServer(
     ...(deps.clearPendingEnrollment === undefined
       ? {}
       : { clearPendingEnrollment: deps.clearPendingEnrollment }),
+    ...(deps.loadCredentialRecord === undefined
+      ? {}
+      : { loadCredentialRecord: deps.loadCredentialRecord }),
+    ...(deps.confirmReplacement === undefined
+      ? {}
+      : { confirmReplacement: deps.confirmReplacement }),
     ...(deps.clientName === undefined ? {} : { clientName: deps.clientName }),
   });
 }

package/src/setup.ts

@@ -73,11 +73,12 @@ async function main() {
   // configuration. Decline/non-interactive/failure paths therefore leave no
   // partial setup state behind.
   console.log(chalk.blue('◼ Local Server'));
-  const serverInstall = await offerFirstRunServerInstall();
+  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
   console.log(chalk.blue('◼ Agent CLI Integration'));
@@ -185,7 +186,9 @@ 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.gray(setupNextStepsText()));
+  if (!serverInstall.suppressClientNextSteps) {
+    console.log(chalk.gray(setupNextStepsText()));
+  }
 }
 
 // Run wizard

package/src/tool-manifest.ts

@@ -30,7 +30,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
             'Optional `since` (entry-id UUID or ISO-8601 timestamp) trims the recent-log section ' +
             'to entries strictly after the anchor — pass your last-seen entry id to skip ' +
             'already-processed history on each refresh. If you know the current session model, pass ' +
-            'optional `model` to self-report it as advisory metadata; unrecognized model strings are accepted.',
+            'optional `model` to self-report its printable identifier as advisory metadata; model names are not allowlisted.',
           inputSchema: {
             type: 'object',
             properties: {
@@ -47,9 +47,11 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
               },
               model: {
                 type: 'string',
-                maxLength: 256,
+                minLength: 1,
+                maxLength: 160,
+                pattern: '^[A-Za-z0-9][A-Za-z0-9._/@:+-]*$',
                 description:
-                  'Optional advisory self-report of the model running this agent session. Use the model identifier you know from session context; the server does not infer or validate it against an allowlist.',
+                  'Optional advisory self-report of the model running this agent session. Use a printable model identifier of 1-160 ASCII characters; model names are not allowlisted.',
               },
             },
             required: [],

package/src/update-cmd.ts

@@ -1128,7 +1128,13 @@ async function defaultPublishedVersions(
   }
 }
 
-async function defaultConfirm(message: string): Promise<'yes' | 'no' | 'eof' | 'interrupted'> {
+export function parseConfirmationAnswer(answer: string, defaultYes = false): 'yes' | 'no' {
+  const normalized = answer.trim().toLowerCase();
+  if (normalized === '') return defaultYes ? 'yes' : 'no';
+  return normalized === 'y' || normalized === 'yes' ? 'yes' : 'no';
+}
+
+async function defaultConfirm(message: string, defaultYes = false): Promise<'yes' | 'no' | 'eof' | 'interrupted'> {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   let interrupted = false;
   rl.once('SIGINT', () => {
@@ -1136,8 +1142,7 @@ async function defaultConfirm(message: string): Promise<'yes' | 'no' | 'eof' | '
     rl.close();
   });
   try {
-    const answer = (await rl.question(message)).trim().toLowerCase();
-    return answer === 'y' || answer === 'yes' ? 'yes' : 'no';
+    return parseConfirmationAnswer(await rl.question(message), defaultYes);
   } catch (error) {
     if (interrupted) return 'interrupted';
     if ((error as NodeJS.ErrnoException).code === 'ERR_USE_AFTER_CLOSE') return 'eof';