borgmcp 2.7.2 → 2.8.0

package/src/remote-client.ts

@@ -16,6 +16,7 @@ import {
 import { randomUUID } from 'node:crypto';
 import {
   createProtocolEnvelope,
+  decodeDeleteCubeResponse,
   decodeDroneRuntimeMetadataState,
   decodeEvictDroneResult,
   decodeProtocolEnvelope,
@@ -23,6 +24,7 @@ import {
   decodeReassignDroneResult,
   decodeUpdateDroneRuntimeMetadataResponse,
   ErrorCode,
+  ProtocolContractError,
   type AgentKind,
   type EvictDroneResult,
   type ReassignDroneResult,
@@ -30,7 +32,12 @@ import {
 import { consolePrefix } from './console-prefix.js';
 import { debugLog } from './debug.js';
 import { assertUuidShape } from './evict-drone.js';
-import { DroneEvictedError, DRONE_EVICTED_CODE } from './drone-lifecycle.js';
+import {
+  CubeDeletedError,
+  CUBE_DELETED_CODE,
+  DroneEvictedError,
+  DRONE_EVICTED_CODE,
+} from './drone-lifecycle.js';
 import type { MessageTaxonomy, MessageTaxonomyClass } from 'borgmcp-shared/templates';
 import { getTemplate, type Template, type TemplateRole } from 'borgmcp-shared/templates';
 import { parseRoleSections } from 'borgmcp-shared/role-section';
@@ -41,8 +48,10 @@ import { loadBorgServerTrust, type ServerFetch } from './server-trust.js';
 import {
   BorgServerError,
   BorgServerHttpError,
+  BorgProtocolMismatchError,
   BorgServerTrustError,
   BorgServerUnreachableError,
+  CubeDeletionConfirmationError,
   LocalManageCredentialUnavailableError,
   LocalManageRequiredError,
 } from './server-errors.js';
@@ -226,6 +235,12 @@ async function decodeLocalProtocolResponse<T>(
       // CR5: a TYPED transport-timeout verdict (message kept for call-site parity).
       throw new BorgServerUnreachableError('Local Borg server request timed out');
     }
+    if (
+      error instanceof ProtocolContractError &&
+      error.code === ErrorCode.UNSUPPORTED_PROTOCOL_VERSION
+    ) {
+      throw new BorgProtocolMismatchError();
+    }
     throw error;
   } finally {
     clearTimeout(timeout);
@@ -329,6 +344,9 @@ async function localManageRequest<T>(
         }),
     }), true, decodePayload);
   } catch (error) {
+    if (error instanceof CubeDeletedError) {
+      throw new CubeDeletedError(operation.cubeName);
+    }
     if (
       error instanceof BorgServerHttpError &&
       error.status === 403 &&
@@ -704,6 +722,7 @@ async function authedFetch(
     // terminal controls. Decode only the bounded protocol error code for typed
     // branching; never surface the server-provided message or details.
     let code: ErrorCode | undefined;
+    let protocolMismatch = false;
     try {
       const body = await readBoundedResponseBody(
         response,
@@ -713,7 +732,13 @@ async function authedFetch(
       const parsed = JSON.parse(body);
       try {
         code = decodeProtocolErrorEnvelope(parsed).error.code;
-      } catch {
+      } catch (error) {
+        if (
+          error instanceof ProtocolContractError &&
+          error.code === ErrorCode.UNSUPPORTED_PROTOCOL_VERSION
+        ) {
+          protocolMismatch = true;
+        }
         if (
           parsed !== null && typeof parsed === 'object' &&
           parsed.error !== null && typeof parsed.error === 'object' &&
@@ -738,10 +763,15 @@ async function authedFetch(
       code = undefined;
     }
     debugLog(`✗ ${response.status} ${method} ${path}`);
+    if (protocolMismatch) throw new BorgProtocolMismatchError();
     if (droneSession !== undefined && response.status === 410 && code === DRONE_EVICTED_CODE) {
       if (localSessionCredentialRef !== undefined) markSeatRejected(localSessionCredentialRef);
       throw new DroneEvictedError();
     }
+    if (response.status === 410 && code === CUBE_DELETED_CODE) {
+      if (localSessionCredentialRef !== undefined) markSeatRejected(localSessionCredentialRef);
+      throw new CubeDeletedError();
+    }
     throw new BorgServerHttpError(
       response.status,
       `Borg server request failed (HTTP ${response.status})`,
@@ -1316,9 +1346,30 @@ export async function patchTaxonomyClass(
  * Delete a cube. Cascade-deletes all roles, drones, and log entries.
  * Requires a live cube-manage grant on the selected local client.
  */
-export async function deleteCube(cubeId: string): Promise<void> {
-  void cubeId;
-  localUnsupported('cube deletion');
+export async function deleteCube(cubeId: string, confirmCubeId: string): Promise<void> {
+  if (confirmCubeId !== cubeId) {
+    throw new CubeDeletionConfirmationError(cubeId, confirmCubeId);
+  }
+  assertUuidShape(cubeId, 'cube_id');
+  const active = await getActiveCube();
+  if (!active?.serverTrustIdentity) throw new Error('Selected Borg server authority state is missing or unreadable');
+  const cubeName = cubeId === active.cubeId ? active.name : cubeId;
+  const result = await localManageRequest(
+    active,
+    `/api/cubes/${cubeId}`,
+    'DELETE',
+    {
+      operation: `delete cube ${manageCopyValue(cubeName)}`,
+      cubeName,
+      noMutation: 'The cube was not deleted.',
+    },
+    {},
+    decodeDeleteCubeResponse,
+  );
+  if (!result) throw new Error('Local Borg server returned an empty cube deletion response');
+  if (result.cube_id !== cubeId) {
+    throw new Error('Local Borg server returned a deletion response for an unexpected cube');
+  }
 }
 
 /**

package/src/server-errors.ts

@@ -35,6 +35,16 @@ export class BorgServerHttpError extends Error {
   }
 }
 
+export class BorgProtocolMismatchError extends Error {
+  constructor() {
+    super(
+      'This client and the selected Borg server use different protocol versions. ' +
+      'Update `borgmcp-server` and `borgmcp` to matching releases, server first and then client.',
+    );
+    this.name = 'BorgProtocolMismatchError';
+  }
+}
+
 export class LocalManageRequiredError extends Error {
   constructor(
     public readonly operation: string,
@@ -106,6 +116,20 @@ export class CubeCreationConfirmationError extends Error {
   }
 }
 
+export class CubeDeletionConfirmationError extends Error {
+  constructor(
+    public readonly cubeId: string,
+    public readonly confirmCubeId: string | undefined,
+  ) {
+    const supplied = confirmCubeId === undefined ? '(missing)' : `"${confirmCubeId}"`;
+    super(
+      `Cube deletion is irreversible. The confirmation cube ID ${supplied} must exactly match ` +
+      `the requested cube ID "${cubeId}". No cube was deleted.`,
+    );
+    this.name = 'CubeDeletionConfirmationError';
+  }
+}
+
 export type RepositoryAssociationFailure =
   | 'repository-already-associated'
   | 'cube-already-associated'

package/src/server-facade.ts

@@ -12,6 +12,7 @@ export type ParsedServerFacadeArgs =
   | { kind: 'help' }
   | { kind: 'cube-init-help' }
   | { kind: 'cube-init'; args: string[] }
+  | { kind: 'command-help'; command: ServerLifecycleCommand }
   | { kind: 'command'; command: ServerLifecycleCommand; args: string[] }
   | { kind: 'error'; reason: 'unknown-command'; command: string };
 
@@ -33,6 +34,9 @@ export function parseServerFacadeArgs(args: readonly string[]): ParsedServerFaca
   if (!(SERVER_LIFECYCLE_COMMANDS as readonly string[]).includes(command)) {
     return { kind: 'error', reason: 'unknown-command', command };
   }
+  if (rest.some(isHelpFlag)) {
+    return { kind: 'command-help', command: command as ServerLifecycleCommand };
+  }
   return {
     kind: 'command',
     command: command as ServerLifecycleCommand,
@@ -163,6 +167,13 @@ export function unknownServerCommandText(command: string): string {
   );
 }
 
+export function serverLifecycleHelpText(command: ServerLifecycleCommand): string {
+  return (
+    `Usage: borg server ${command} [arguments]\n\n` +
+    `Command arguments are server-owned and pass to the verified borg-mcp-server executable when run.\n`
+  );
+}
+
 export function missingServerExecutableText(command: ServerLifecycleCommand): string {
   return (
     `Local server command is unavailable: borg-mcp-server was not found.\n` +
@@ -256,6 +267,10 @@ export async function runEarlyServerFacade(
     output.writeStdout(cubeInitHelpText(getPackageVersion()));
     return 0;
   }
+  if (parsed.kind === 'command-help') {
+    output.writeStdout(serverLifecycleHelpText(parsed.command));
+    return 0;
+  }
   if (parsed.kind === 'error') {
     output.writeStderr(unknownServerCommandText(parsed.command));
     return 1;

package/src/server-handshake.ts

@@ -196,7 +196,7 @@ export interface ServerAttachResult {
 }
 
 /**
- * Attach an enrolled client principal to one granted cube/role over protocol v6.
+ * Attach an enrolled client principal to one granted cube/role over protocol v7.
  * The client CSPRNG-generates the session bearer and persists it PENDING in the
  * OS keychain (keyed by the stable per-seat identity) BEFORE this request, so an
  * interrupted/lost response is recovered by re-sending the exact same bearer —

package/src/server-trust.ts

@@ -1,3 +1,4 @@
+import { Buffer } from 'node:buffer';
 import { createHash, timingSafeEqual, X509Certificate } from 'node:crypto';
 import { constants } from 'node:fs';
 import { open } from 'node:fs/promises';
@@ -157,6 +158,16 @@ export function createPinnedServerFetch(origin: string, caCertificate: string):
 
     const body = requestBody(init.body);
     const headers = new Headers(init.headers);
+    if (body !== undefined) {
+      const contentLength = String(
+        typeof body === 'string' ? Buffer.byteLength(body, 'utf8') : body.byteLength,
+      );
+      const declaredLength = headers.get('Content-Length');
+      if (declaredLength !== null && declaredLength !== contentLength) {
+        throw new Error('Borg server transport refused an inconsistent Content-Length');
+      }
+      if (declaredLength === null) headers.set('Content-Length', contentLength);
+    }
     return await new Promise<Response>((resolvePromise, rejectPromise) => {
       const request = httpsRequest({
         protocol: 'https:',

package/src/setup.ts

@@ -38,6 +38,7 @@ import { handleVersionFlag } from './version.js';
 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';
 
 /**
  * Main setup wizard
@@ -184,10 +185,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.gray('◼ Next steps:'));
-  console.log(chalk.gray('1. cd into your project, then run "borg assimilate --host <host>" to join a cube'));
-  console.log(chalk.gray('   (this connects to your local server and launches your agent)'));
-  console.log(chalk.gray('2. Use `borg assimilate --host <host> --enroll` from the operator terminal to enroll a new client\n'));
+  console.log(chalk.gray(setupNextStepsText()));
 }
 
 // Run wizard

package/src/tool-manifest.ts

@@ -58,10 +58,10 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_assimilate',
           description:
-            "RE-ATTACH this session to the drone seat already saved for this worktree (gh#780: " +
-            "this tool never creates seats). Provide the cube's name; on a match it returns the " +
-            "cube directive, your role's instructions, and recent activity for the EXISTING seat. " +
-            'To create a seat or switch cubes, run `borg assimilate` in a terminal instead.',
+            "Reconnect this session to the existing drone saved for this worktree. This tool " +
+            "never creates drones. Provide the cube's name; on a match it returns the cube " +
+            "directive, your role's instructions, and recent activity for that drone. To create " +
+            'a drone or switch cubes, run `borg assimilate` in a terminal instead.',
           inputSchema: {
             type: 'object',
             properties: {
@@ -116,7 +116,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_playbook',
           description:
-            'Load the full operating-playbook chapter — the detailed disciplines, rationale, and examples behind the rule-spine in your regen (verification discipline v1/v2/v3, concrete source-of-truth surfaces, four-surface propagation). This detail is kept OUT of the regen bootstrap to keep it light; fetch it ONCE per session when doing review/verify-class work. Static text — do NOT re-fetch on every wake.',
+            'Load the full operating-playbook chapter — the detailed disciplines, rationale, and examples behind the abbreviated session instructions (verification discipline v1/v2/v3, concrete source-of-truth surfaces, four-surface propagation). This detail is omitted from the initial context to keep it light; fetch it ONCE per session when doing review/verify-class work. Static text — do NOT re-fetch on every wake.',
           inputSchema: {
             type: 'object',
             properties: {},
@@ -153,7 +153,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
           name: 'borg_role-rationale',
           description:
             "Fetch an on-demand rationale/case-study section for a role playbook. " +
-            "Pass a role name/id and a plain-label section key to read the rationale without expanding every regen.",
+            "Pass a role name/id and a plain-label section key to read the rationale without expanding every context refresh.",
           inputSchema: {
             type: 'object',
             properties: {
@@ -249,7 +249,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_decide',
           description:
-            'Record a RATIFIED cube decision in the durable decision registry (gh#740) so drones cite it by topic instead of restating from memory. Coordinator/Queen are workflow-eligible to ratify, but their labels grant no server permission; the selected local client must have a live cube-manage grant. Recording IS the ratification act; a decision is not ratified until it is in the registry. Topic-keyed: recording a new decision on an existing topic supersedes the prior (one active per topic). Surfaces in borg_regen + borg_decisions.',
+            'Record a RATIFIED cube decision in the durable decision registry so drones cite it by topic instead of restating from memory. Coordinator and Queen roles are workflow-eligible to ratify, but role labels grant no server permission; the selected local client must have a live cube-manage grant. Recording IS the ratification act; a decision is not ratified until it is in the registry. Topic-keyed: recording a new decision on an existing topic supersedes the prior (one active per topic). The decision appears in borg_regen and borg_decisions.',
           inputSchema: {
             type: 'object',
             required: ['topic', 'decision'],
@@ -272,7 +272,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         {
           name: 'borg_decisions',
           description:
-            'List the active ratified decisions for the cube (gh#740) — the source of truth to CITE instead of restating a decision from memory. Any member may read. Pass `topic` to fetch one topic\'s active decision; omit for all active decisions.',
+            'List the active ratified decisions for the cube — the source of truth to CITE instead of restating a decision from memory. Any member may read. Pass `topic` to fetch one topic\'s active decision; omit for all active decisions.',
           inputSchema: {
             type: 'object',
             properties: {
@@ -350,7 +350,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
                 pattern: '^[a-z0-9-]+$',
                 maxLength: 64,
               },
-              cube_directive: { type: 'string', description: 'Markdown text every drone in this cube will see in regen. Anything project-specific.' },
+              cube_directive: { type: 'string', description: 'Project-specific Markdown shown to every drone when it refreshes cube context.' },
               template: {
                 type: 'string',
                 description: 'Optional template name to apply after cube creation (e.g. "software-dev"). Roles are merged by name; the default Drone role gets overwritten by the template if a same-named role is in the template.',
@@ -419,13 +419,14 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
         },
         {
           name: 'borg_delete-cube',
-          description: 'Delete a cube and all its roles, drones, and log entries. Irreversible — confirm with the user before invoking unless the cube is clearly disposable.',
+          description: 'Delete a cube and all its roles, drones, and log entries. Irreversible; requires the exact cube UUID again after explicit user confirmation.',
           inputSchema: {
             type: 'object',
             properties: {
               cube_id: { type: 'string', description: 'UUID of the cube to delete.' },
+              confirm_cube_id: { type: 'string', description: 'Explicit user confirmation: repeat the exact cube UUID to confirm this irreversible deletion.' },
             },
-            required: ['cube_id'],
+            required: ['cube_id', 'confirm_cube_id'],
           },
         },
         {
@@ -439,7 +440,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
               short_description: { type: 'string', description: 'One-line summary, shown to every drone in the cube.' },
               detailed_description: { type: 'string', description: 'Full playbook for drones in this role — workflow, conventions, log signals to post.' },
               is_default: { type: 'boolean', description: 'If true, new drones assimilating into this cube are assigned this role. Demotes the previous default.' },
-              is_mandatory: { type: 'boolean', description: 'If true, role-less assimilate fills this unoccupied non-queen role before ordinary worker roles. A mandatory human-seat role is therefore selected first until occupied.' },
+              is_mandatory: { type: 'boolean', description: 'If true, role-less assimilation prioritizes this unoccupied role before ordinary worker roles. Platform-wide management roles are never auto-assigned; a mandatory human-operator role is selected first until occupied.' },
               is_human_seat: { type: 'boolean', description: 'If true, this role represents the cube\'s human-occupied seat (where the human Queen sits directly). The class-hierarchy guard in reassign-drone allows promotion FROM a human-seat role TO the platform Queen role; promotion from non-human-seat roles is rejected.' },
               can_broadcast: { type: 'boolean', description: 'If true, drones in this role may post broadcast log entries when strict broadcast gating is enabled.' },
               receives_all_direct: { type: 'boolean', description: 'If true, drones in this role can see direct log entries as observer/audit recipients.' },
@@ -458,7 +459,7 @@ export const TOOL_MANIFEST: ToolManifestEntry[] = [
               short_description: { type: 'string', description: 'New short description (optional).' },
               detailed_description: { type: 'string', description: 'New detailed playbook (optional).' },
               is_default: { type: 'boolean', description: 'Set true to make this the cube\'s default role (optional).' },
-              is_mandatory: { type: 'boolean', description: 'Set true/false to prioritize this unoccupied non-queen role during role-less assimilate.' },
+              is_mandatory: { type: 'boolean', description: 'Set true/false to prioritize this unoccupied role during role-less assimilation. Platform-wide management roles are never auto-assigned.' },
               is_human_seat: { type: 'boolean', description: 'Set true/false to mark/unmark this as the cube\'s human-occupied seat (the elevation source for the platform Queen role).' },
               can_broadcast: { type: 'boolean', description: 'Set true/false to allow or deny broadcast log entries when strict broadcast gating is enabled.' },
               receives_all_direct: { type: 'boolean', description: 'Set true/false to grant or remove observer visibility into direct log entries.' },