borgmcp 2.7.3 → 2.8.0

package/src/index.ts

@@ -20,6 +20,7 @@ import {
 } from '@modelcontextprotocol/sdk/types.js';
 
 import { assertRoleMatches } from './role-match.js';
+import { CubeDeletionConfirmationError } from './server-errors.js';
 
 import {
   getCubeInfo,
@@ -103,7 +104,9 @@ import {
 } from './roster-render.js';
 import { resolveWorkingRepo } from './working-repo.js';
 import {
+  CubeDeletedError,
   DroneEvictedError,
+  formatCubeDeletedErrorToolResult,
   formatEvictedToolResult,
 } from './drone-lifecycle.js';
 import {
@@ -1048,7 +1051,11 @@ export async function main() {
         case 'borg_delete-cube': {
           const cubeId = args?.cube_id as string;
           if (!cubeId) throw new Error('cube_id is required');
-          await deleteCube(cubeId);
+          const confirmCubeId = args?.confirm_cube_id as string | undefined;
+          if (confirmCubeId !== cubeId) {
+            throw new CubeDeletionConfirmationError(cubeId, confirmCubeId);
+          }
+          await deleteCube(cubeId, confirmCubeId);
           return { content: [{ type: 'text', text: `Deleted cube ${cubeId} (and all its roles, drones, log entries).` }] };
         }
 
@@ -1261,6 +1268,13 @@ export async function main() {
           isError: true,
         };
       }
+      if (error instanceof CubeDeletedError) {
+        const active = await getActiveCube();
+        return {
+          content: [{ type: 'text', text: formatCubeDeletedErrorToolResult(error, active?.name) }],
+          isError: true,
+        };
+      }
 
       const localManageResult = formatLocalManageToolResult(error);
       if (localManageResult) return localManageResult;

package/src/log-stream.ts

@@ -40,6 +40,8 @@ import {
   type LocalServerCursor,
 } from './local-server-cursor.js';
 import {
+  CubeDeletedError,
+  CUBE_DELETED_CODE,
   DroneEvictedError,
   DRONE_EVICTED_CODE,
   EVICTED_RESULT_MARKER,
@@ -573,7 +575,7 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
       // loop quiesces cleanly. The agent's graceful shutdown (TaskStop Monitor,
       // no /loop reschedule) is driven separately by the EVICTED tool-result it
       // already received on the authed call that produced this verdict.
-      if (err instanceof DroneEvictedError || err instanceof BorgServerError) {
+      if (err instanceof CubeDeletedError || err instanceof DroneEvictedError || err instanceof BorgServerError) {
         if (active.localSessionCredentialRef) {
           markSeatRejected(active.localSessionCredentialRef);
         }
@@ -591,15 +593,15 @@ async function runLoop(testDeps: RunLoopTestDeps = {}): Promise<void> {
           streamState.ownership = await readOwnershipSnapshot(active.cubeId, active.droneId);
           continue;
         }
-        if (err instanceof DroneEvictedError) {
+        if (err instanceof DroneEvictedError || err instanceof CubeDeletedError) {
           if (lease) await lease.release().catch(() => {});
           lease = null;
           leaseKey = null;
           streamState.connected = false;
           streamState.ownership = await readOwnershipSnapshot(active.cubeId, active.droneId);
-          process.stderr.write(
-            `[borg-mcp log stream] drone evicted — stream terminated (no reconnect).\n`
-          );
+          process.stderr.write(err instanceof CubeDeletedError
+            ? '[borg-mcp log stream] cube deleted — stream terminated (no reconnect).\n'
+            : '[borg-mcp log stream] drone evicted — stream terminated (no reconnect).\n');
         }
         throw new TerminalStreamError();
       }
@@ -939,6 +941,10 @@ export async function streamOnce(
         if (active.localSessionCredentialRef) markSeatRejected(active.localSessionCredentialRef);
         throw new DroneEvictedError();
       }
+      if (code === CUBE_DELETED_CODE) {
+        if (active.localSessionCredentialRef) markSeatRejected(active.localSessionCredentialRef);
+        throw new CubeDeletedError();
+      }
       // client#42: an expired resume cursor is RECOVERABLE, not terminal. The
       // pointed-at entry was pruned server-side, so retrying the SAME cursor
       // 410s forever (a wedged, silently-dead wake path). Reset the stream's
@@ -1010,6 +1016,13 @@ export async function streamOnce(
         break;
       }
 
+      if (event.type === 'error') {
+        if (active.localSessionCredentialRef) markSeatRejected(active.localSessionCredentialRef);
+        if (event.code === CUBE_DELETED_CODE) throw new CubeDeletedError();
+        if (event.code === DRONE_EVICTED_CODE) throw new DroneEvictedError();
+        throw new BorgServerError('CREDENTIAL_REJECTED', 'Borg server terminated the stream');
+      }
+
       if (event.type === 'heartbeat') {
         streamState.lastHeartbeatAt = nowIso;
         // First/baseline heartbeat absorb: until this session has seen
@@ -1198,6 +1211,7 @@ export type ParsedEvent =
   | { type: 'bookmark'; as_of: string | null }
   // gh#877 Path-A: terminal eviction control frame (wake hint, zero authority).
   | { type: 'eviction'; id: string | null; cube_id: string | null; reason: string | null }
+  | { type: 'error'; code: ErrorCode }
   | { type: 'unknown'; raw: string };
 
 /**
@@ -1357,6 +1371,13 @@ function parseEventBlock(block: string): ParsedEvent | null {
     }
     return { type: 'eviction', id: id || null, cube_id, reason };
   }
+  if (eventName === 'error') {
+    try {
+      return { type: 'error', code: decodeProtocolErrorEnvelope(JSON.parse(dataStr)).error.code };
+    } catch {
+      return { type: 'unknown', raw: block };
+    }
+  }
   return { type: 'unknown', raw: block };
 }
 

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-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/tool-manifest.ts

@@ -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'],
           },
         },
         {

package/src/update-cmd.ts

@@ -7,6 +7,7 @@ import which from 'which';
 import { updateHelpText } from './cli-help.js';
 import { preflightBorgServerTag } from './server-handshake.js';
 import { loadBorgServerTrust } from './server-trust.js';
+import { shellEscape } from './shell-escape.js';
 
 const CLIENT_PACKAGE = 'borgmcp';
 const SERVER_PACKAGE = 'borgmcp-server';
@@ -81,6 +82,7 @@ interface ServerStatus {
   endpoint: string | null;
   mode: 'foreground' | 'managed' | 'legacy' | 'stopped';
   serviceAdapter: 'launchd' | 'systemd' | null;
+  serviceRecovery: { command: string[] } | null;
   dataIdentity: 'available' | 'unavailable';
   nextAction: string | null;
 }
@@ -103,6 +105,15 @@ interface ServerUpdateFailure {
 }
 
 type ServerUpdateResult = ServerUpdateSuccess | ServerUpdateFailure;
+type ServerUpdateFailureStage =
+  | 'initial server status check'
+  | 'server controller identity check'
+  | 'server runtime activation'
+  | 'post-update server status check'
+  | 'final server state verification'
+  | 'final package verification'
+  | 'managed service continuity check'
+  | 'running server protocol verification';
 
 interface NpmContext {
   commandPath: string;
@@ -119,9 +130,13 @@ function errorMessage(error: unknown, fallback: string): string {
   return error instanceof Error ? error.message : fallback;
 }
 
+function hasErrorCode(error: unknown, code: string): boolean {
+  return error instanceof Error && (error as NodeJS.ErrnoException).code === code;
+}
+
 function renderReentryPreflightFailure(error: unknown, target: UpdateTarget): string {
   return (
-    `${errorMessage(error, 'Update preflight failed')}\n` +
+    `Update preflight failed: ${errorMessage(error, 'unknown failure')}\n` +
     `Observed update state:\n` +
     `  client: ${CLIENT_PACKAGE}@${target.clientVersion} installed and verified before re-entry\n` +
     `  server controller: not changed by this continuation\n` +
@@ -346,6 +361,18 @@ function isNextAction(value: unknown): value is string | null {
   );
 }
 
+function decodeManagedServiceRecovery(value: unknown): { command: string[] } | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (record.kind !== 'run-platform-command' || !Array.isArray(record.command) ||
+      record.command.length === 0 || record.command.length > 32 ||
+      record.command.some((arg) => typeof arg !== 'string' || arg.length === 0 ||
+        Array.from(arg).length > 1024 || /\p{Cc}/u.test(arg))) {
+    return null;
+  }
+  return { command: record.command as string[] };
+}
+
 function decodeServerStatus(value: unknown): ServerStatus {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new Error('server returned invalid JSON status');
@@ -379,13 +406,19 @@ function decodeServerStatus(value: unknown): ServerStatus {
       record.running_integrity !== null ||
       record.build_identity !== null ||
       record.endpoint !== null ||
-      record.mode !== 'stopped' ||
-      record.service_adapter !== null
+      record.mode !== 'stopped'
     )) ||
     (record.status === 'running' && record.mode === 'stopped')
   ) {
     throw new Error('server returned inconsistent JSON status');
   }
+  const managedRecovery = record.status === 'stopped' && record.service_adapter !== null
+    ? decodeManagedServiceRecovery(record.service_recovery)
+    : null;
+  if (record.status === 'stopped' && record.service_adapter !== null &&
+      (record.service_state !== 'inactive' || managedRecovery === null)) {
+    throw new Error('server returned invalid managed-service recovery status');
+  }
   return {
     state: record.status,
     installedController: record.installed_controller,
@@ -397,6 +430,7 @@ function decodeServerStatus(value: unknown): ServerStatus {
     endpoint: record.endpoint,
     mode: record.mode as ServerStatus['mode'],
     serviceAdapter: record.service_adapter,
+    serviceRecovery: managedRecovery,
     dataIdentity: record.data_identity,
     nextAction: record.next_action,
   };
@@ -472,7 +506,6 @@ function verifyServerStatus(status: ServerStatus, target: PublishedPackage): 'ru
       status.buildIdentity !== null ||
       status.endpoint !== null ||
       status.mode !== 'stopped' ||
-      status.serviceAdapter !== null ||
       status.dataIdentity !== 'available'
     ) {
       throw new Error('final server verification failed: stopped server reported a running runtime');
@@ -492,6 +525,37 @@ function verifyServerStatus(status: ServerStatus, target: PublishedPackage): 'ru
   return 'running';
 }
 
+function renderServerFailureRecovery(
+  status: ServerStatus | null,
+  updateAttempted: boolean,
+  retryCommand: 'borg update --yes' | 'borg server status' | 'borg server update' | 'borg server start',
+): string {
+  let text = '';
+  if (status?.state === 'stopped') {
+    text += renderStoppedServiceRecovery(status);
+  } else if (updateAttempted && status === null) {
+    text += (
+      `Local server service state could not be verified; it may be stopped.\n` +
+      `Check it with: borg server status\n` +
+      `If it is stopped, run the recovery command reported by borg server status.\n`
+    );
+  }
+  if (retryCommand !== 'borg server start') {
+    text += status?.state === 'stopped'
+      ? `Then retry the failed stage with: ${retryCommand}\n`
+      : `Next: ${retryCommand}\n`;
+  }
+  return text;
+}
+
+function renderStoppedServiceRecovery(status: ServerStatus): string {
+  if (status.serviceRecovery !== null) {
+    const command = status.serviceRecovery.command.map(shellEscape).join(' ');
+    return `Local server service is stopped.\nRestart it with: ${command}\n`;
+  }
+  return `Local server service is stopped.\nStart it with: borg server start\n`;
+}
+
 export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promise<number> {
   if (options.help) {
     deps.stdout(updateHelpText(''));
@@ -512,7 +576,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
     deps.stderr(options.target
       ? renderReentryPreflightFailure(error, options.target)
       : (
-        `${errorMessage(error, 'Update preflight failed')}\n` +
+        `Update preflight failed: ${errorMessage(error, 'unknown failure')}\n` +
         `Observed update state:\n` +
         `  client: not inspected (registry preflight incomplete)\n` +
         `  server controller: not inspected (registry preflight incomplete)\n` +
@@ -540,7 +604,7 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
   }
 
   deps.stdout(
-    `Published update plan (npm registry):\n` +
+    `Published update plan (${CANONICAL_NPM_REGISTRY}):\n` +
     `  client: ${CLIENT_PACKAGE}@${client.version} -> ${CLIENT_PACKAGE}@${pair.client.version}\n` +
     `    target integrity: ${pair.client.integrity}\n` +
     `  server: ${discoveredServer ? `${SERVER_PACKAGE}@${discoveredServer.version}` : 'not installed'} -> ${SERVER_PACKAGE}@${pair.server.version}\n` +
@@ -624,7 +688,8 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
         : 'not installed'}\n` +
       `  prepared runtime: not inspected\n` +
       `  running runtime: not inspected\n` +
-      `Server mutation was not attempted.\n`,
+      `Server mutation was not attempted.\n` +
+      `Next: reinstall ${CLIENT_PACKAGE}@${pair.client.version} from ${CANONICAL_NPM_REGISTRY}, then rerun borg update --yes.\n`,
     );
     return interrupted ?? 1;
   }
@@ -671,19 +736,39 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
 
   let observedStatus: ServerStatus | null = null;
   let observedUpdate: ServerUpdateResult | null = null;
+  let initialServerState: ServerStatus['state'] | null = null;
+  let updateAttempted = false;
+  let recoveryStatusAttempted = false;
+  let failureStage: ServerUpdateFailureStage = 'initial server status check';
+  let retryCommand: Parameters<typeof renderServerFailureRecovery>[2] = 'borg server status';
+  const observeStatusAfterFailure = async (): Promise<void> => {
+    recoveryStatusAttempted = true;
+    try {
+      observedStatus = decodeServerStatus(await deps.serverJson(server.binPath, 'status'));
+    } catch {
+      observedStatus = null;
+    }
+  };
   try {
     let status = decodeServerStatus(await deps.serverJson(server.binPath, 'status'));
     observedStatus = status;
+    initialServerState = status.state;
     if (status.installedController !== exactServerIdentity(pair.server.version)) {
+      failureStage = 'server controller identity check';
+      retryCommand = 'borg update --yes';
       throw new Error('server status contradicted the verified controller identity');
     }
     try {
       verifyServerStatus(status, pair.server);
     } catch {
       observedStatus = null;
+      updateAttempted = true;
+      failureStage = 'server runtime activation';
+      retryCommand = 'borg server update';
       const update = decodeServerUpdate(await deps.serverJson(server.binPath, 'update'));
       observedUpdate = update;
       if (update.status === 'failed') {
+        await observeStatusAfterFailure();
         throw new Error(`server update failed: ${update.errorCode} (${update.recovery})`);
       }
       const serverIdentity = exactServerIdentity(pair.server.version);
@@ -696,10 +781,17 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
       ) {
         throw new Error('server update result did not reach the target artifact');
       }
+      failureStage = 'post-update server status check';
+      retryCommand = 'borg server status';
+      recoveryStatusAttempted = true;
       status = decodeServerStatus(await deps.serverJson(server.binPath, 'status'));
       observedStatus = status;
     }
+    failureStage = 'final server state verification';
+    retryCommand = 'borg server update';
     const state = verifyServerStatus(status, pair.server);
+    failureStage = 'final package verification';
+    retryCommand = 'borg update --yes';
     const [finalClient, finalServer] = await Promise.all([
       deps.currentClient(),
       deps.currentServer(),
@@ -707,20 +799,35 @@ export async function runUpdate(options: UpdateOptions, deps: UpdateDeps): Promi
     assertInstalled(finalClient, pair.client);
     if (!finalServer) throw new Error('server controller disappeared during final verification');
     assertInstalled(finalServer, pair.server);
-    if (state === 'running') await deps.verifyRunningProtocol(status.endpoint!);
+    if (initialServerState === 'running' && state === 'stopped') {
+      failureStage = 'managed service continuity check';
+      retryCommand = 'borg server start';
+      throw new Error('a previously running local server is now stopped');
+    }
+    if (state === 'running') {
+      failureStage = 'running server protocol verification';
+      retryCommand = 'borg server status';
+      await deps.verifyRunningProtocol(status.endpoint!);
+    }
     deps.stdout(
       state === 'stopped'
-        ? `Updated ${CLIENT_PACKAGE}@${pair.client.version} and ${SERVER_PACKAGE}@${pair.server.version}: prepared; still stopped.\n`
+        ? (
+          `Updated ${CLIENT_PACKAGE}@${pair.client.version} and ${SERVER_PACKAGE}@${pair.server.version}: prepared.\n` +
+          renderStoppedServiceRecovery(status)
+        )
         : `Updated ${CLIENT_PACKAGE}@${pair.client.version} and ${SERVER_PACKAGE}@${pair.server.version}; running identities and protocol verified.\n`,
     );
     deps.stdout('Restart active agent sessions to load the updated client.\n');
     return 0;
   } catch (error) {
     const interrupted = signalExitCode(error);
+    if (updateAttempted && !recoveryStatusAttempted && observedStatus === null) {
+      await observeStatusAfterFailure();
+    }
     deps.stderr(
-      `Server update or final verification failed: ${errorMessage(error, 'unknown failure')}.\n` +
+      `Server update failed during ${failureStage}: ${errorMessage(error, 'unknown failure')}.\n` +
       renderServerState(client, server, observedStatus, observedUpdate) +
-      `Retry with: borg update --yes\n`,
+      renderServerFailureRecovery(observedStatus, updateAttempted, retryCommand),
     );
     return interrupted ?? 1;
   }
@@ -735,8 +842,8 @@ interface CommandResult {
 class CommandSignalError extends Error {
   readonly exitCode: number;
 
-  constructor(signal: NodeJS.Signals) {
-    super(`command stopped by ${signal}`);
+  constructor(signal: NodeJS.Signals, stderr = '') {
+    super(`command stopped by ${signal}${serverCommandStderr(stderr)}`);
     this.name = 'CommandSignalError';
     this.exitCode = 128 + (constants.signals[signal] ?? 1);
   }
@@ -775,7 +882,7 @@ function runCommand(
     child.once('exit', (code, signal) => {
       if (settled) return;
       if (signal) {
-        fail(new CommandSignalError(signal));
+        fail(new CommandSignalError(signal, stderr));
         return;
       }
       settled = true;
@@ -800,6 +907,14 @@ function singleLine(text: string, label: string): string {
   return value;
 }
 
+function serverCommandStderr(stderr: string): string {
+  const detail = stderr.trim();
+  if (detail === '') return '';
+  const bounded = Array.from(detail).slice(-4096).join('')
+    .replace(/\p{Cc}/gu, (character) => character === '\n' || character === '\t' ? character : '?');
+  return `\nServer command stderr:\n${bounded}`;
+}
+
 async function npmText(commandPath: string, args: readonly string[], label: string): Promise<string> {
   const result = await runCommand(commandPath, args);
   if (result.code !== 0) throw new Error(`npm ${label} lookup failed`);
@@ -925,6 +1040,18 @@ async function inspectNpmPackage(
     if (!required) return null;
     throw new Error(`${binName} is not available on PATH`);
   }
+  try {
+    await realpath(join(context.root, name));
+  } catch (error) {
+    if (hasErrorCode(error, 'ENOENT')) {
+      throw new Error(
+        `${binName} is on PATH from a different npm global prefix. ` +
+        `borg update only manages packages under the active npm prefix. ` +
+        `Run npm prefix --global to inspect it, then update the other installation with its package manager.`,
+      );
+    }
+    throw error;
+  }
   return inspectNpmPackageAt({
     name,
     binName,
@@ -1065,10 +1192,12 @@ export function buildDefaultUpdateDeps(): UpdateDeps {
       try {
         parsed = JSON.parse(result.stdout);
       } catch {
-        throw new Error(`server ${command} returned invalid JSON`);
+        throw new Error(`server ${command} returned invalid JSON${serverCommandStderr(result.stderr)}`);
       }
       if (result.code !== 0 && command !== 'update') {
-        throw new Error(`server ${command} exited ${result.code}`);
+        throw new Error(
+          `server ${command} exited ${result.code}${serverCommandStderr(result.stderr)}`,
+        );
       }
       return parsed;
     },