borgmcp 2.0.11 → 2.1.1

package/docs/EXTRACTION_PROVENANCE.md

@@ -8,7 +8,7 @@ The extraction copied the monorepo's `client/src/` production boundary and top-l
 
 ## Deliberate Transformations
 
-- Replaced the monorepo dependency on `borgmcp-shared` with the exact audited registry release `borgmcp-shared@0.6.2` and a fresh standalone lockfile.
+- Replaced the monorepo dependency on `borgmcp-shared` with the exact audited registry release `borgmcp-shared@0.6.4` and a fresh standalone lockfile.
 - Replaced local template, role-section, drone-address, and log high-water-mark implementations with `borgmcp-shared` exports.
 - Removed monorepo-only website anti-drift tests and re-anchored remaining filesystem tests to this repository.
 - Removed consumer lifecycle hooks, parent-directory deployment scripts, minification, and private integration-environment configuration.
@@ -21,8 +21,8 @@ The extraction copied the monorepo's `client/src/` production boundary and top-l
   lightweight release tag failed before packaging. The reviewed `2.0.1`
   recovery, `2.0.2`, `2.0.3`, `2.0.4`, `2.0.5`, and `2.0.6` successors were
   published and registry-verified. The immutable `2.0.7` workflow failed before
-  package creation or npm publication. The `2.0.8`, `2.0.9`, and `2.0.10` successors were
-  published, so the next candidate identity is `2.0.11`. Extraction and
+  package creation or npm publication. The `2.0.8`, `2.0.9`, `2.0.10`, `2.0.11`, and
+  `2.1.0` successors were published, so the next candidate identity is `2.1.1`. Extraction and
   versioning do not authorize publication.
 
 ## Review Holds
@@ -38,9 +38,11 @@ artifact reaches no hosted authority.
 Local enrollment now uses the reviewed client-generated credential/retry
 contract, with a pre-request `PENDING` record in the local 0600-permission seat
 store, exact-tuple ambiguous retry, and verified activation. The contract now
-resolves to the audited registry `borgmcp-shared@0.6.2`. The matching
-`borgmcp-server@0.1.17` release is published and registry-verified. Client
-`borgmcp@2.0.10` is published. The immutable `v2.0.7`
+resolves to the audited registry `borgmcp-shared@0.6.4` with integrity
+`sha512-Wm4b0uoOAw9JCz5OTHD0Q2uXKkeWYdkVksdeZvRG8l62XGMY+G8GkNEsZT9L533LbVbQ29GhgF0htjDenQThDg==`.
+The matching `borgmcp-server@0.1.21` release is published with integrity
+`sha512-g0QH4cKcsKuDyZs1MvBmvCoCLaZ4wVI04yHCGSvcAeWghWxSBH0IIF8Q5OFi1pLB7TZXOVP6D3QAabUQ2eJTFg==`
+and pins the same `borgmcp-shared@0.6.4` contract. Client `borgmcp@2.1.0` is published. The immutable `v2.0.7`
 attempt failed before publication and remains preserved. Publication of the next
-candidate remains gated by reviewed `v2.0.11` source, a fresh annotated tag, and
+candidate remains gated by reviewed `v2.1.1` source, a fresh annotated tag, and
 the exact-artifact and protected-publication gates.

package/docs/LOCAL_SERVER.md

@@ -32,10 +32,28 @@ Commands:
   status   Report verified runtime evidence.
   update   Verify and activate a local server artifact.
   invite   Create a single-use invitation in an interactive terminal.
+  cube init   Initialize this Git repository's cube; does not create a drone.
 
 Run borg server <command> --help for server command options.
 ```
 
+`borg server cube init --help` prints:
+
+```text
+borg server cube init — initialize this Git repository's cube without creating a drone
+
+Usage:
+  borg server cube init [options]
+
+Options:
+  --host <host>                    Borg server host or URL (bare hosts default to HTTPS)
+  --enroll                         Prompt for a hidden enrollment invitation
+  --cube-name <name>               Repository cube name (otherwise edit the proposed name)
+  --template software-dev|starter  New-cube template (default: software-dev)
+  --yes, -y                        Accept new-cube defaults; never adopt by name
+  --help, -h                       Show this help
+```
+
 Local server client credentials are stored in the owner-controlled
 `~/.borg/credentials` file with mode 0600. Fresh same-machine setup provisions
 the first owner record there, so bare `borg assimilate` can use it without an
@@ -73,10 +91,25 @@ exactly; the credential becomes active only after the versioned response is
 decoded and the authenticated protocol handshake succeeds. A new process
 resumes that pending enrollment before displaying another invitation prompt.
 
-`--cube-name <name>` explicitly selects the repository cube name. Without an
-explicit name, Borg uses the `origin` repository name or, when `origin` is
-absent, proposes the sanitized repository-directory basename. Confirm
-interactively or pass `--yes`; bare repositories fail closed.
+`borg assimilate` and `borg server cube init` share one repository-cube flow.
+An existing local or server repository association is resolved without prompts.
+Otherwise Borg checks accessible cubes against the exact proposed name. One
+match displays the cube, repository, and server and requires explicit interactive
+confirmation before the server atomically associates it; multiple matches fail
+closed. `--yes` never adopts a cube by name. With no match, an authorized owner
+continues to the creation guide, which shows the repository and server, proposes
+an editable name, offers the Software Development and Starter templates, and
+asks for one confirmation. `--cube-name <name>` and `--template
+software-dev|starter` supply those creation values directly; `--yes` accepts the
+repository default name and Software Development template. `borg server cube
+init` stops after authoritative cube readback and never creates a drone. Bare
+repositories fail closed.
+
+For repositories with a canonical public `origin`, that origin is the stable
+repository identity. Repositories without one receive an invisible UUID stored
+in an owner-only local file. Its lookup key is an HMAC of the canonical Git
+common directory, so linked worktrees share one identity and local paths are not
+stored in cleartext. A malformed identity secret or state file fails closed.
 
 The connection is HTTPS-only. Borg validates the server trust material, stores
 parent enrollment credentials in `~/.borg/credentials` and session credentials
@@ -89,7 +122,8 @@ The lifecycle facade invokes the separately installed `borgmcp-server`; it does
 not bundle the server into the client. The server must be running and trusted
 before assimilation. An owner enrollment carrying the persisted `create_cube`
 capability creates one idempotent cube per repository during normal
-assimilation, using the server-owned `default` role template; repeating an
+assimilation or `borg server cube init`, using Software Development or Starter;
+repeating an
 ambiguous request does not duplicate the cube, and distinct repositories can
 create distinct bounded cubes. An ordinary enrolled client is denied before a
 create request is sent. Cloud-only capabilities fail explicitly rather than
@@ -139,8 +173,9 @@ The default discovery endpoint is `https://127.0.0.1:7091`. Explicit `--host` va
 
 ## Release status
 
-This self-hosted path consumes the published `borgmcp-shared@0.6.2` v3 registry
-release. The matching server owner-enrollment, cube-create, attach, restart, log,
-and SSE implementation must also pass the full process-level local dogfood gate.
-Until that gate opens the self-hosted path remains preview-only, and the client
+This self-hosted path pins published `borgmcp-shared@0.6.4` and requires the
+matching published `borgmcp-server@0.1.21` for protocol v5 repository resolve
+and association. The server owner-enrollment, repository resolve/association,
+cube-create, attach, restart, log, and SSE implementation must also pass the full
+process-level local dogfood gate. Until that gate opens the self-hosted path remains preview-only, and the client
 publish is deferred accordingly.

package/docs/RELEASING.md

@@ -97,8 +97,22 @@ The annotated `v2.0.10` tag object
 `3f7003b65eadc74cd949857e831e1181a1aad2ff`. Workflow run `30063538271`, attempt 1,
 successfully published that exact source as `borgmcp@2.0.10`; the registry records integrity
 `sha512-BkFrq75mF7ih0/7Z7RsXsJYo43qNs4ng7tSnvcFCl3k6r+ex1FvTkah0+KQNinDSrv6a+HLWahUe8875so8zew==`.
+Never move, replace, reuse, or rerun that tag or workflow.
+
+The annotated `v2.0.11` tag object
+`fb95f4278137d1d7871d945c467eb33984abe1c4` peels to protected-main commit
+`0676d93d3e8a64ba583e95f164d122b39687b53a`. Workflow run `30073844074`, attempt 1,
+successfully published that exact source as `borgmcp@2.0.11`; the registry records integrity
+`sha512-429njJ7HVmWhpm8E71RoLzG57Qehy3RSxEzs6fQofVoOIiZXnK4QQDwbQe9MPfhKifbvVN5lGcDKtKAjuC76ww==`.
+Never move, replace, reuse, or rerun that tag or workflow.
+
+The annotated `v2.1.0` tag object
+`e0b189bb0dd1f1b12369ab81870113925e1afc41` peels to protected-main commit
+`10f18e4010c9c518c0ea2184d42ed5388642a53f`. Workflow run `30166498938`, attempt 1,
+successfully published that exact source as `borgmcp@2.1.0`; the same-run artifact report records integrity
+`sha512-Gm9n69y3C0feNDYRPEOnShLCscQJ/BoylcRMH+sDDQJmdcbjY8+U6dDTcFv3w+uH5P/IVwJydB8TGRHPXL0FQA==`.
 Never move, replace, reuse, or rerun that tag or workflow. The next candidate
-uses the unused `v2.0.11` identity from a fresh reviewed protected-main commit
+uses the unused `v2.1.1` identity from a fresh reviewed protected-main commit
 and requires the complete release gate again.
 
 ## Release Prerequisites
@@ -110,9 +124,12 @@ Before creating the release tag, independently verify all of these conditions:
 - the extraction review confirms no private backend secrets, deployment
   configuration, customer data, local state, or duplicated shared contracts
   entered the public package;
-- the exact audited registry dependency `borgmcp-shared@0.6.2` remains locked to
-  its canonical tarball and integrity;
-- the client and matching server pass the complete local dogfood gate;
+- the exact audited registry dependency `borgmcp-shared@0.6.4` remains locked to
+  its canonical tarball and integrity
+  `sha512-Wm4b0uoOAw9JCz5OTHD0Q2uXKkeWYdkVksdeZvRG8l62XGMY+G8GkNEsZT9L533LbVbQ29GhgF0htjDenQThDg==`;
+- the client and matching published `borgmcp-server@0.1.21`, integrity
+  `sha512-g0QH4cKcsKuDyZs1MvBmvCoCLaZ4wVI04yHCGSvcAeWghWxSBH0IIF8Q5OFi1pLB7TZXOVP6D3QAabUQ2eJTFg==`, which pins
+  `borgmcp-shared@0.6.4`, pass the complete local dogfood gate;
 - the selected stable client version is unused and the exact release commit is
   on protected `main`;
 - the repository and protected npm environment settings pass an operator audit;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "2.0.11",
+  "version": "2.1.1",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "borgmcp-shared": "0.6.2",
+    "borgmcp-shared": "0.6.4",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
     "which": "^4.0.0"

package/src/assimilate-cmd.ts

@@ -7,7 +7,6 @@ import {
   occupiedRoleIdsForAutoRole,
   pickDefaultRole,
 } from './role-resolver.js';
-import { deriveCubeName, parseGitRemote, sanitizeRemoteUrl } from './cube-name.js';
 import { validateName } from './name-validator.js';
 import { renderAssimilationWelcome } from './assimilate-welcome.js';
 import { shellEscape } from './shell-escape.js';
@@ -42,7 +41,15 @@ import { installBorgPlugin } from './opencode-plugin.js';
 import { computeOpenCodePort, connectOpenCodeDrone, createOpenCodeLaunchKickoff, injectInitialKickoff } from './opencode-drone.js';
 import { ensureCliMcpConfigured } from './ensure-mcp-config.js';
 import { normalizeServerEndpoint } from './server-endpoint.js';
-import { BorgServerError, LegacySessionCredentialCollisionError } from './server-errors.js';
+import {
+  BorgServerError,
+  CubeCreationConfirmationError,
+  CubeCreationOutcomeUnknownError,
+  LegacySessionCredentialCollisionError,
+  RepositoryAssociationOperationError,
+  RepositoryAssociationOutcomeUnknownError,
+  RepositoryAssociationResolutionError,
+} from './server-errors.js';
 import type { SeatStatus } from './seat-probe.js';
 import type { ServerSessionOperation } from './config.js';
 import type { ExpectedBinding, FinalizeServerSeatOutcome, PersistedLocalSeat } from './cubes.js';
@@ -50,6 +57,20 @@ import type { SeatBinding, BindPendingSeatOutcome } from './seats.js';
 import { createHash } from 'node:crypto';
 import { buildOpenCodeLaunchArgs, type LaunchApprovalDecision } from './cli-tool-approval.js';
 import { resolveWorkingRepo, type WorkingRepo } from './working-repo.js';
+import type {
+  AssociateRepositoryCubeResponse,
+  CreateCubeRepository,
+  CubeTemplate,
+} from 'borgmcp-shared/protocol';
+import {
+  initializeRepositoryCube,
+  RepositoryAssociationConfirmationError,
+  RepositoryAssociationSaveError,
+  validRepositoryCubeName,
+  type RepositoryCubeCreation,
+  type RepositoryCubeResolution,
+} from './repository-cube-init.js';
+import type { GitRepositoryContext, RepositoryAssociation } from './repository-identity.js';
 
 const PRIVATE_STATE_UNAVAILABLE_COPY = [
   'Borg could not safely prepare its private local state.',
@@ -73,6 +94,7 @@ export interface AssimilateFlags {
 export interface AssimilateArgs {
   role: string | undefined;
   flags: AssimilateFlags;
+  mode?: 'assimilate' | 'cube-init';
 }
 
 export interface CubeSummary {
@@ -222,6 +244,10 @@ export interface AssimilateDeps {
     scrubPending: () => Promise<unknown>;
   }) => Promise<FinalizeServerSeatOutcome>;
   findProjectRoot: (cwd: string) => string;
+  resolveRepositoryContext: (cwd: string) => Promise<GitRepositoryContext | null>;
+  getRepositoryIdentity: (context: GitRepositoryContext) => Promise<CreateCubeRepository>;
+  getRepositoryAssociation: (trustIdentity: string, repository: CreateCubeRepository) => Promise<RepositoryAssociation | null>;
+  saveRepositoryAssociation: (trustIdentity: string, repository: CreateCubeRepository, association: RepositoryAssociation) => Promise<void>;
 
   // gh#673 P2 (WI-1): write the borg-regen SessionStart hook into the
   // launch root's .claude/settings.local.json (project-local; idempotent).
@@ -249,14 +275,31 @@ export interface AssimilateDeps {
     serverCapabilities?: readonly string[];
   } | null>;
 
+  resolveRepositoryCube: (
+    apiUrl: string,
+    token: string,
+    input: { workingRepoName: string; repository: CreateCubeRepository },
+    serverTrustIdentity?: string,
+  ) => Promise<RepositoryCubeResolution>;
+  associateRepositoryCube: (
+    apiUrl: string,
+    token: string,
+    input: { cubeId: string; workingRepoName: string; repository: CreateCubeRepository },
+    serverTrustIdentity?: string,
+  ) => Promise<AssociateRepositoryCubeResponse>;
   listCubes: (apiUrl: string, token: string, serverTrustIdentity?: string) => Promise<CubeSummary[]>;
   getCube: (apiUrl: string, token: string, cubeId: string, serverTrustIdentity?: string) => Promise<CubeDetail>;
   createCube: (
     apiUrl: string,
     token: string,
-    params: { name?: string; template?: string; projectRoot?: string },
+    params: {
+      name: string;
+      workingRepoName: string;
+      repository: CreateCubeRepository;
+      template: Exclude<CubeTemplate, 'default'>;
+    },
     serverTrustIdentity?: string,
-  ) => Promise<CubeDetail>;
+  ) => Promise<RepositoryCubeCreation>;
   assimilate: (
     apiUrl: string,
     token: string,
@@ -301,11 +344,6 @@ function affirmative(answer: string): boolean {
   return normalized === '' || normalized === 'y' || normalized === 'yes';
 }
 
-function isLocalCubePresentationName(name: string): boolean {
-  return name.length >= 1 && name.length <= 120 &&
-    /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/.test(name);
-}
-
 async function selectAssimilationAuthority(
   flags: AssimilateFlags,
   deps: AssimilateDeps,
@@ -509,6 +547,7 @@ export async function runAssimilate(
   args: AssimilateArgs,
   deps: AssimilateDeps
 ): Promise<number> {
+  const mode = args.mode ?? 'assimilate';
   // ----- Input validation (before any subprocess work) -----
   if (args.role !== undefined) {
     const v = validateName(args.role);
@@ -524,6 +563,29 @@ export async function runAssimilate(
       return 1;
     }
   }
+  if (args.flags.cubeName !== undefined && !validRepositoryCubeName(args.flags.cubeName.trim())) {
+    deps.stderr('Invalid cube name. Use 1-120 letters, digits, spaces, dots, underscores, or hyphens, starting with a letter or digit.\n');
+    return 1;
+  }
+
+  let repositoryContext: GitRepositoryContext | null;
+  try {
+    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');
+      return 1;
+    }
+    repositoryContext = null;
+  }
+  if (!repositoryContext) {
+    deps.stderr(
+      'No Git repository was found for this directory.\n' +
+      'Nothing was changed.\n' +
+      'Run this command inside a Git repository.\n',
+    );
+    return 1;
+  }
 
   try {
     await deps.preparePrivateRoot();
@@ -555,86 +617,9 @@ export async function runAssimilate(
     return reportServerFailure(deps, authority.apiUrl, localSeatReadError);
   }
 
-  // ----- Repository + cube-name preflight -----
-  // Resolve and, where necessary, confirm local presentation data before an
-  // owner invitation can be consumed. A declined/underivable basename must
-  // not leave a successfully enrolled client behind.
-  const projectRoot = deps.findProjectRoot(deps.cwd());
-  let cubeName: string | null;
-  if (args.flags.cubeName) {
-    cubeName = args.flags.cubeName;
-  } else {
-    const remoteResult = deps.runSync('git', ['remote', 'get-url', 'origin'], projectRoot);
-    const remoteUrl = remoteResult.status === 0 ? remoteResult.stdout : null;
-    const sanitizedRemote = remoteUrl ? sanitizeRemoteUrl(remoteUrl) : null;
-    const parsedRepo = sanitizedRemote ? parseGitRemote(sanitizedRemote) : null;
-
-    if (!parsedRepo) {
-      const bareResult = deps.runSync('git', ['rev-parse', '--is-bare-repository'], projectRoot);
-      if (bareResult.status === 0 && bareResult.stdout.trim() === 'true') {
-        deps.stderr(
-          'borg assimilate requires a non-bare repository worktree. ' +
-            (authority.kind === 'server'
-              ? `Clone or check out the repository, then rerun ${localAssimilateCommand(authority.apiUrl)}.\n`
-              : 'Clone or check out the repository, then retry.\n'),
-        );
-        return 1;
-      }
-    }
-
-    cubeName = deriveCubeName(projectRoot, remoteUrl);
-    if (!cubeName) {
-      deps.stderr(
-        'Could not derive a cube name from this repository. ' +
-          (authority.kind === 'server'
-            ? `Rerun ${localAssimilateCommand(authority.apiUrl)} with \`--cube-name <name>\`.\n`
-            : 'Pass --cube-name <name> and retry.\n'),
-      );
-      return 1;
-    }
+  const projectRoot = repositoryContext.root;
 
-    if (!parsedRepo) {
-      if (sanitizedRemote) {
-        deps.stderr(
-          `Could not parse the origin remote; using directory name '${cubeName}' as the cube name.\n`,
-        );
-      }
-      if (!args.flags.yes) {
-        if (!deps.isTTY()) {
-          deps.stderr(
-            `Using directory name '${cubeName}' as the cube name requires confirmation. ` +
-              (authority.kind === 'server'
-                ? `Rerun ${localAssimilateCommand(authority.apiUrl)} with \`--cube-name <name>\` or \`--yes\`.\n`
-                : 'Re-run with --cube-name <name> or --yes.\n'),
-          );
-          return 1;
-        }
-        const confirmed = await deps.prompt(
-          `No usable origin remote was found. Use directory name '${cubeName}' as the cube name? [Y/n]: `,
-        );
-        if (!affirmative(confirmed)) {
-          deps.stderr(
-            authority.kind === 'server'
-              ? `Cube creation for ${authority.apiUrl} was cancelled. Rerun ` +
-                `${localAssimilateCommand(authority.apiUrl)} with \`--cube-name <name>\`.\n`
-              : 'Cube creation cancelled. Re-run with --cube-name <name> to choose a name.\n',
-          );
-          return 1;
-        }
-      }
-    }
-  }
-
-  if (authority.kind === 'server' && !isLocalCubePresentationName(cubeName)) {
-    deps.stderr(
-      `Invalid cube name for ${authority.apiUrl}. Use 1–120 letters, digits, spaces, dots, ` +
-        'underscores, or hyphens, starting with a letter or digit. Rerun ' +
-        `${localAssimilateCommand(authority.apiUrl)} with \`--cube-name <name>\`.\n`,
-    );
-    return 1;
-  }
-
-  let auth: { token: string; apiUrl: string; serverTrustIdentity: string };
+  let auth: { token: string; apiUrl: string; serverTrustIdentity: string; serverCapabilities: readonly string[] };
   {
     try {
       let serverAuth: {
@@ -696,6 +681,7 @@ export async function runAssimilate(
         token: serverAuth.token,
         apiUrl: authority.apiUrl,
         serverTrustIdentity: serverAuth.trustIdentity,
+        serverCapabilities: serverAuth.serverCapabilities ?? [],
       };
     } catch (error) {
       return reportServerFailure(deps, authority.apiUrl, error, args.flags.enroll === true);
@@ -717,67 +703,123 @@ export async function runAssimilate(
   // (no chdir has happened yet; this is a stable starting point).
   const originalCwd = deps.cwd();
 
-  // ----- Step 3: Cube existence check (with auto-refresh on auth failure) -----
-  // gh#653 B4: announce each network step. These calls take 2–5s and were
-  // previously silent, so a user read the wait as a hang and Ctrl-C'd mid-run.
-  deps.stderr('Checking your cubes…\n');
-  let allCubes: CubeSummary[];
+  let initialized;
   try {
-    allCubes = await deps.listCubes(auth.apiUrl, auth.token, auth.serverTrustIdentity);
-  } catch (err) {
-    return reportServerFailure(deps, authority.apiUrl, err);
-  }
-  const existingCube = allCubes.find((c) => c.name === cubeName);
-
-  // ----- Step 4: Fetch detail OR create cube -----
-  let cubeDetail: CubeDetail;
-  let isFirstDrone: boolean;
-  if (existingCube) {
-    try {
-      cubeDetail = await deps.getCube(
+    initialized = await initializeRepositoryCube({
+      mode,
+      context: repositoryContext,
+      serverOrigin: auth.apiUrl,
+      flags: args.flags,
+      canCreate: auth.serverCapabilities.includes('create_cube'),
+    }, {
+      isTTY: deps.isTTY,
+      prompt: deps.prompt,
+      write: deps.stderr,
+      getIdentity: deps.getRepositoryIdentity,
+      getAssociation: (repository) => deps.getRepositoryAssociation(auth.serverTrustIdentity, repository),
+      saveAssociation: (repository, association) =>
+        deps.saveRepositoryAssociation(auth.serverTrustIdentity, repository, association),
+      resolveAssociation: (repository, workingRepoName) => deps.resolveRepositoryCube(
+        auth.apiUrl,
+        auth.token,
+        { repository, workingRepoName },
+        auth.serverTrustIdentity,
+      ),
+      listCubes: () => deps.listCubes(auth.apiUrl, auth.token, auth.serverTrustIdentity),
+      associateCube: (params) => deps.associateRepositoryCube(
         auth.apiUrl,
         auth.token,
-        existingCube.id,
+        params,
         auth.serverTrustIdentity,
+      ),
+      getCube: (cubeId) => deps.getCube(auth.apiUrl, auth.token, cubeId, auth.serverTrustIdentity),
+      createCube: (params) => deps.createCube(auth.apiUrl, auth.token, params, auth.serverTrustIdentity),
+    });
+  } catch (error) {
+    if (error instanceof RepositoryAssociationOutcomeUnknownError) {
+      deps.stderr(
+        'Repository cube association outcome is unknown.\n' +
+        'The server may have created the repository binding; no local repository association was saved and no drone was created.\n' +
+        'Run the same command again; Borg will first resolve the authoritative server association without creating a cube.\n',
       );
-    } catch (error) {
-      return reportServerFailure(deps, authority.apiUrl, error);
+      return 1;
     }
-    isFirstDrone = (cubeDetail.drones?.length ?? 0) === 0;
-  } else {
-    // ----- Step 4a: First-drone bootstrap (template selection) -----
-    let chosenTemplate: string | undefined;
-    if (args.flags.noTemplate ||
-        (args.flags.template !== undefined && args.flags.template !== 'default')) {
+    if (error instanceof RepositoryAssociationResolutionError) {
       deps.stderr(
-        `Borg server ${authority.apiUrl} supports its default cube template only. ` +
-          `Rerun ${localAssimilateCommand(authority.apiUrl)} without \`--template\` or \`--no-template\`.\n`,
+        'Repository cube association could not be resolved.\n' +
+        'Verify that the server is reachable and the client and server versions match, then run the same command again.\n' +
+        'No cube, repository binding, or drone was created.\n',
       );
       return 1;
     }
-    chosenTemplate = 'default';
-
-    // gh#653 B4: progress for the create round-trip (silent-window stall).
-    deps.stderr(cubeName ? `Creating cube '${cubeName}'…\n` : 'Creating your cube…\n');
-    try {
-      const createParams = chosenTemplate
-        ? {
-          name: cubeName ?? undefined,
-          template: chosenTemplate,
-          projectRoot,
-        }
-        : { name: cubeName ?? undefined };
-      cubeDetail = await deps.createCube(
-        auth.apiUrl,
-        auth.token,
-        createParams,
-        auth.serverTrustIdentity,
+    if (error instanceof RepositoryAssociationOperationError) {
+      const recovery = error.failure === 'repository-already-associated'
+        ? 'This repository is already associated with another cube. Run the same command again to use the existing managed association, or ask the server operator to correct the repository binding.'
+        : error.failure === 'cube-already-associated'
+          ? 'The selected cube is already associated with another repository. Choose a different cube, or run the command from the repository already linked to that cube.'
+          : error.failure === 'access-denied'
+            ? 'This enrolled client does not have permission to manage the selected cube. Ask the server operator to grant this client management access, then run the same command again.'
+            : 'The selected cube does not have valid authoritative roles. Ask the server operator to repair its role configuration, or choose another cube.';
+      deps.stderr(
+        'Repository cube association could not be completed.\n' +
+        `${recovery}\n` +
+        'No cube, repository binding, or drone was created.\n',
       );
-    } catch (error) {
-      return reportServerFailure(deps, authority.apiUrl, error);
+      return 1;
+    }
+    if (error instanceof RepositoryAssociationConfirmationError) {
+      deps.stderr(
+        'Repository cube association could not be confirmed.\n' +
+        'The server may have created the repository binding; no local repository association was saved and no drone was created.\n' +
+        'Run the same command again; Borg will resolve authoritative server state before creating or associating a cube.\n',
+      );
+      return 1;
+    }
+    if (error instanceof RepositoryAssociationSaveError) {
+      deps.stderr(
+        'The repository cube was confirmed, but Borg could not save its local repository association.\n' +
+        'No drone was created.\n' +
+        'Run the same command again; the server will resolve the existing cube and restore the local association.\n',
+      );
+      return 1;
+    }
+    if (error instanceof CubeCreationOutcomeUnknownError) {
+      deps.stderr(
+        'Cube creation outcome is unconfirmed.\n' +
+        'The server may have created the cube and repository binding; no local repository association was saved and no drone was created.\n' +
+        'Run the same command again; Borg will resolve authoritative server state before creating a cube.\n',
+      );
+      return 1;
     }
-    isFirstDrone = true;
+    if (error instanceof CubeCreationConfirmationError) {
+      deps.stderr(
+        'Cube creation could not be confirmed.\n' +
+        'The server may have created the cube and repository binding; no local repository association was saved and no drone was created.\n' +
+        'Run the same command again; Borg will resolve authoritative server state before creating a cube.\n',
+      );
+      return 1;
+    }
+    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`,
+      );
+      return 1;
+    }
+    if (error instanceof BorgServerError) {
+      return reportServerFailure(deps, auth.apiUrl, error);
+    }
+    deps.stderr(
+      'Repository cube initialization failed.\n' +
+      'The server may have created or associated a cube; local repository state may be incomplete and no drone was created.\n' +
+      'Run the same command again; Borg will resolve authoritative server state before creating or associating a cube.\n',
+    );
+    return 1;
   }
+  if (initialized.kind === 'stop') return initialized.code;
+  const cubeDetail = initialized.creation.cube as CubeDetail;
+  const isFirstDrone = (cubeDetail.drones?.length ?? 0) === 0;
+  if (mode === 'cube-init') return 0;
 
   // Read the worktree identity before role selection. A live local seat must
   // retain its original role so the attach request reuses the exact durable
@@ -1754,7 +1796,7 @@ export async function runAssimilate(
       serverUrl,
       directory: agentCwd,
       droneLabel: result.drone_label,
-      cubeName: cubeName ?? 'borg',
+      cubeName: cubeDetail.name,
     })
       .then(() => injectInitialKickoff(launchKickoff))
       .catch(() => {});