borgmcp 2.0.10 → 2.1.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,12 @@ 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,
+} 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 +54,14 @@ 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 { CreateCubeRepository, CubeTemplate } from 'borgmcp-shared/protocol';
+import {
+  initializeRepositoryCube,
+  RepositoryAssociationSaveError,
+  validRepositoryCubeName,
+  type RepositoryCubeCreation,
+} 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 +85,7 @@ export interface AssimilateFlags {
 export interface AssimilateArgs {
   role: string | undefined;
   flags: AssimilateFlags;
+  mode?: 'assimilate' | 'cube-init';
 }
 
 export interface CubeSummary {
@@ -222,6 +235,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).
@@ -254,9 +271,14 @@ export interface AssimilateDeps {
   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 +323,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 +526,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 +542,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 +596,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;
-      }
-    }
+  const projectRoot = repositoryContext.root;
 
-    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;
-    }
-
-    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 +660,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 +682,128 @@ 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(
-        auth.apiUrl,
-        auth.token,
-        existingCube.id,
-        auth.serverTrustIdentity,
+    if (!auth.serverCapabilities.includes('create_cube') && !existing) {
+      const repository = await deps.getRepositoryIdentity(repositoryContext);
+      const association = await deps.getRepositoryAssociation(auth.serverTrustIdentity, repository);
+      if (association) {
+        initialized = await initializeRepositoryCube({
+          mode, context: repositoryContext, serverOrigin: auth.apiUrl, flags: args.flags,
+        }, {
+          isTTY: deps.isTTY,
+          prompt: deps.prompt,
+          write: deps.stderr,
+          getIdentity: async () => repository,
+          getAssociation: async () => association,
+          saveAssociation: (identity, saved) =>
+            deps.saveRepositoryAssociation(auth.serverTrustIdentity, identity, saved),
+          getCube: (cubeId) => deps.getCube(auth.apiUrl, auth.token, cubeId, auth.serverTrustIdentity),
+          createCube: (params) => deps.createCube(auth.apiUrl, auth.token, params, auth.serverTrustIdentity),
+        });
+      } else {
+        const candidateName = args.flags.cubeName ?? repositoryContext.derivedName;
+        const accessible = await deps.listCubes(auth.apiUrl, auth.token, auth.serverTrustIdentity);
+        const matches = accessible.filter((cube) => cube.name === candidateName);
+        if (matches.length !== 1) {
+          deps.stderr(matches.length === 0
+            ? `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`
+            : `More than one accessible cube is named '${candidateName}'. Nothing was changed. Ask the server operator for an unambiguous repository cube grant.\n`);
+          return 1;
+        }
+        const cube = await deps.getCube(auth.apiUrl, auth.token, matches[0].id, auth.serverTrustIdentity);
+        const association = {
+          cubeId: cube.id,
+          name: cube.name,
+          workingRepoName: repositoryContext.derivedName,
+          template: 'default' as const,
+        };
+        try {
+          await deps.saveRepositoryAssociation(auth.serverTrustIdentity, repository, association);
+        } catch {
+          throw new RepositoryAssociationSaveError();
+        }
+        const response = {
+          result: 'resolved' as const,
+          cube_id: cube.id,
+          name: cube.name,
+          working_repo_name: repositoryContext.derivedName,
+          repository,
+          template: 'default' as const,
+          human_seat_role_id: cube.roles.find((role) => role.is_human_seat)?.id ?? '',
+          default_worker_role_id: cube.roles.find((role) => role.is_default)?.id ?? '',
+          access: 'manage' as const,
+        };
+        deps.stderr(
+          `Cube already initialized.\n  Name: ${cube.name}\n  Template: Default (legacy)\n` +
+          `  Repository: ${repositoryContext.root}\n  Server: ${auth.apiUrl}\n` +
+          (mode === 'cube-init'
+            ? `No drone was created.\nNext: borg assimilate --host ${shellEscape(auth.apiUrl)}\n`
+            : 'Continuing with role and seat setup...\n'),
+        );
+        initialized = { kind: 'success' as const, creation: { response, cube }, existing: true };
+      }
+    } else {
+    initialized = await initializeRepositoryCube({
+      mode,
+      context: repositoryContext,
+      serverOrigin: auth.apiUrl,
+      flags: args.flags,
+    }, {
+      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),
+      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 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',
       );
-    } 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 CubeCreationOutcomeUnknownError) {
       deps.stderr(
-        `Borg server ${authority.apiUrl} supports its default cube template only. ` +
-          `Rerun ${localAssimilateCommand(authority.apiUrl)} without \`--template\` or \`--no-template\`.\n`,
+        'Cube creation outcome is unknown.\n' +
+        'No local repository association was saved.\n' +
+        'Run the same command again; the server will resolve the original request or return a conflict.\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 CubeCreationConfirmationError) {
+      deps.stderr(
+        'Cube creation could not be confirmed.\n' +
+        `${error.message}\n` +
+        'No local repository association was saved.\n' +
+        'Resolve the conflict, then run the same command again.\n',
       );
-    } catch (error) {
-      return reportServerFailure(deps, authority.apiUrl, error);
+      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;
     }
-    isFirstDrone = true;
+    if (error instanceof BorgServerError) {
+      return reportServerFailure(deps, auth.apiUrl, error);
+    }
+    deps.stderr('Could not create cube.\nThe selected Borg server rejected the request.\nNothing was changed.\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 +1780,7 @@ export async function runAssimilate(
       serverUrl,
       directory: agentCwd,
       droneLabel: result.drone_label,
-      cubeName: cubeName ?? 'borg',
+      cubeName: cubeDetail.name,
     })
       .then(() => injectInitialKickoff(launchKickoff))
       .catch(() => {});

package/src/assimilate-deps.ts

@@ -61,8 +61,47 @@ import { prepareCodexRemoteLaunch, defaultCodexRemoteDeps } from './codex-remote
 import { findLoadedCodexThread } from './codex-app-server.js';
 import { defaultApprovalIo, resolveLaunchBorgApprovals } from './cli-tool-approval.js';
 import { ensurePrivateBorgConfigRoot } from './private-root.js';
+import {
+  getOrCreateRepositoryIdentity,
+  getRepositoryAssociation,
+  resolveGitRepositoryContext,
+  saveRepositoryAssociation,
+} from './repository-identity.js';
+import { PromptInterruptedError } from './repository-cube-init.js';
 
-export function buildDefaultAssimilateDeps(): AssimilateDeps {
+/**
+ * Wraps the readline question operation with the production interruption
+ * mapping. Tests inject the question operation; production uses readline.
+ */
+export type PromptQuestion = (message: string) => Promise<string>;
+
+async function defaultPromptQuestion(message: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return await rl.question(message);
+  } finally {
+    rl.close();
+  }
+}
+
+export function createPromptAdapter(
+  question: PromptQuestion = defaultPromptQuestion,
+): (message: string) => Promise<string> {
+  return async (message: string): Promise<string> => {
+    try {
+      return await question(message);
+    } catch (err) {
+      if (err instanceof Error && (err.message === 'SIGINT' || err.message === 'Interrupted by signal.')) {
+        throw new PromptInterruptedError();
+      }
+      throw err;
+    }
+  };
+}
+
+export function buildDefaultAssimilateDeps(
+  question: PromptQuestion = defaultPromptQuestion,
+): AssimilateDeps {
   return {
     runSync: (cmd, args, cwd) => {
       const r = spawnSync(cmd, args, { cwd, encoding: 'utf-8' });
@@ -97,14 +136,7 @@ export function buildDefaultAssimilateDeps(): AssimilateDeps {
 
     stderr: (line) => process.stderr.write(line),
     stdout: (line) => process.stdout.write(line),
-    prompt: async (message: string): Promise<string> => {
-      const rl = createInterface({ input: process.stdin, output: process.stdout });
-      try {
-        return await rl.question(message);
-      } finally {
-        rl.close();
-      }
-    },
+    prompt: createPromptAdapter(question),
     promptSecret: async (message: string): Promise<string> => {
       const result = await prompts({
         type: 'password',
@@ -178,6 +210,10 @@ export function buildDefaultAssimilateDeps(): AssimilateDeps {
         : { committed: false, reason: 'activation-failed' };
     },
     findProjectRoot: (cwd) => cubesFindProjectRoot(cwd),
+    resolveRepositoryContext: resolveGitRepositoryContext,
+    getRepositoryIdentity: getOrCreateRepositoryIdentity,
+    getRepositoryAssociation,
+    saveRepositoryAssociation,
 
     // gh#673 P2 (WI-1): project-local SessionStart hook for the launch root.
     installProjectSessionHook: (projectRoot) => {
@@ -237,14 +273,16 @@ export function buildDefaultAssimilateDeps(): AssimilateDeps {
         throw new Error('Selected Borg server authority state is missing or unreadable');
       }
       {
-        if (!params.name || !params.projectRoot) {
-          throw new Error('Local Borg server cube creation requires a repository name and root');
-        }
         const created = await createLocalBorgServerCube(
           apiUrl,
           serverTrustIdentity,
           token,
-          { projectRoot: params.projectRoot, name: params.name },
+          {
+            name: params.name,
+            workingRepoName: params.workingRepoName,
+            repository: params.repository,
+            template: params.template,
+          },
         );
         const cube = await remoteGetCube(created.cube_id, {
           apiUrl,
@@ -253,16 +291,20 @@ export function buildDefaultAssimilateDeps(): AssimilateDeps {
         });
         if (
           cube.id !== created.cube_id ||
+          cube.name !== created.name ||
           !Array.isArray(cube.roles) ||
           !cube.roles.some((role: { id?: string }) => role.id === created.default_worker_role_id)
         ) {
           throw new Error('Borg server returned cube details outside the creation result');
         }
         return {
-          id: cube.id,
-          name: cube.name,
-          roles: cube.roles,
-          drones: cube.drones ?? [],
+          response: created,
+          cube: {
+            id: cube.id,
+            name: cube.name,
+            roles: cube.roles,
+            drones: cube.drones ?? [],
+          },
         };
       }
     },

package/src/claude.ts

@@ -19,8 +19,10 @@
 
 import { spawn } from 'child_process';
 import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
 import { basename } from 'node:path';
 import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import { findProjectRoot, getActiveCube, inboxPathForDrone, setCodexWakeTarget, pruneDeadCodexWakeTargets } from './cubes.js';
 import { monitorStateRootForWorktree } from './inbox-monitor.js';
@@ -81,6 +83,23 @@ import { connectOpenCodeDrone, computeOpenCodePort, createOpenCodeLaunchKickoff,
 import { buildOpenCodeLaunchArgs, defaultApprovalIo, resolveLaunchBorgApprovals } from './cli-tool-approval.js';
 import { runEarlyServerFacade } from './server-facade.js';
 
+export type AssimilateDepsBuilder = typeof buildDefaultAssimilateDeps;
+
+export async function runAssimilateEntry(
+  args: readonly string[],
+  buildDeps: AssimilateDepsBuilder = buildDefaultAssimilateDeps,
+): Promise<number> {
+  const parsed = parseAssimilateArgs([...args]);
+  if (!parsed.ok) {
+    process.stderr.write(
+      chalk.red(`${consolePrefix()}◼ borg assimilate: ${parsed.error}\n`)
+    );
+    process.stderr.write(`Run \`borg --help\` for usage.\n`);
+    return 1;
+  }
+  return runAssimilate({ role: parsed.role, flags: parsed.flags }, buildDeps());
+}
+
 async function main() {
   const serverExitCode = await runEarlyServerFacade(process.argv);
   if (serverExitCode !== null) process.exit(serverExitCode);
@@ -128,16 +147,7 @@ async function main() {
       process.stdout.write(assimilateHelpText(getPackageVersion()));
       process.exit(0);
     }
-    const parsed = parseAssimilateArgs(process.argv.slice(3));
-    if (!parsed.ok) {
-      process.stderr.write(
-        chalk.red(`${consolePrefix()}◼ borg assimilate: ${parsed.error}\n`)
-      );
-      process.stderr.write(`Run \`borg --help\` for usage.\n`);
-      process.exit(1);
-    }
-    const deps = buildDefaultAssimilateDeps();
-    const code = await runAssimilate({ role: parsed.role, flags: parsed.flags }, deps);
+    const code = await runAssimilateEntry(process.argv.slice(3));
     process.exit(code);
   }
   if (process.argv[2] === 'reset-local-seat') {
@@ -560,7 +570,17 @@ function ensureDetectedCliConfigured(): void {
   }
 }
 
-main().catch((error) => {
-  console.error(`${consolePrefix()}${chalk.red(`\n◼ Error: ${error.message}\n`)}`);
-  process.exit(1);
-});
+function isEntryInvocation(): boolean {
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+if (isEntryInvocation()) {
+  main().catch((error) => {
+    console.error(`${consolePrefix()}${chalk.red(`\n◼ Error: ${error.message}\n`)}`);
+    process.exit(1);
+  });
+}

package/src/cli-help.ts

@@ -30,6 +30,7 @@ export function topLevelHelpText(version: string): string {
     `  borg assimilate [role]   Join or create a cube\n` +
     `  borg assimilate --host <host>   Join or create on an explicit server\n` +
     `  borg assimilate --worktree <name>   Spawn a worktree drone (in ~/.borg/worktrees/<repo>/<name>)\n` +
+    `  borg server cube init   Initialize this repository's cube without creating a drone\n` +
     `  borg reset-local-seat    Clear ONLY this worktree's saved local seat (offline; after a rejection)\n` +
     `  borg sync [--prune]      Sync this worktree's branch to origin/main\n` +
     `  borg cleanup [--prune]   Report (or --prune) worktrees orphaned by evicted drones\n` +
@@ -53,11 +54,28 @@ export function serverHelpText(): string {
     `  stop     Stop the managed local server.\n` +
     `  status   Report verified runtime evidence.\n` +
     `  update   Verify and activate a local server artifact.\n` +
-    `  invite   Create a single-use invitation in an interactive terminal.\n\n` +
+    `  invite   Create a single-use invitation in an interactive terminal.\n` +
+    `  cube init   Initialize this Git repository's cube; does not create a drone.\n\n` +
     `Run borg server <command> --help for server command options.\n`
   );
 }
 
+/** Client-owned help for repository cube initialization without a drone. */
+export function cubeInitHelpText(): string {
+  return (
+    `borg server cube init — initialize this Git repository's cube without creating a drone\n\n` +
+    `Usage:\n` +
+    `  borg server cube init [options]\n\n` +
+    `Options:\n` +
+    `  --host <host>                    Borg server host or URL (bare hosts default to HTTPS)\n` +
+    `  --enroll                         Prompt for a hidden enrollment invitation\n` +
+    `  --cube-name <name>               Repository cube name (otherwise edit the proposed name)\n` +
+    `  --template software-dev|starter  New-cube template (default: software-dev)\n` +
+    `  --yes, -y                        Skip confirmation prompts\n` +
+    `  --help, -h                       Show this help\n`
+  );
+}
+
 /**
  * Help text for `borg assimilate --help` — the home for the full assimilate flag
  * set. Model/provider configuration belongs to the selected agent CLI.
@@ -76,15 +94,17 @@ export function assimilateHelpText(version: string): string {
     `Flags:\n` +
     `  --worktree <name>          Create + launch the drone in a sibling git worktree\n` +
     `  --here                     Stay in the current worktree (no sibling spawn)\n` +
-    `  --cube-name <name>         Cube to join/create (otherwise confirm repo basename)\n` +
+    `  --cube-name <name>         Repository cube name (otherwise edit the proposed name)\n` +
     `  --host <host>              Borg server host or URL (bare hosts default to HTTPS)\n` +
     `  --enroll                   Prompt for a hidden enrollment invitation in the operator terminal\n` +
-    `  --template <name>          Bootstrap a new cube from a bundled role template\n` +
-    `  --no-template              Create the cube with no template roles\n` +
+    `  --template software-dev|starter   New-cube template (default: software-dev)\n` +
+    `  --no-template              Unsupported for repository cube creation\n` +
     `  --cli claude|codex|opencode         Agent CLI to launch (default: claude)\n` +
     `  --model claude:<model>   Legacy Claude model override (configure models in the agent CLI)\n` +
     `  --yes, -y                  Skip confirmation prompts\n\n` +
-    `An enrolled owner client may create an idempotent repository cube; ordinary clients\n` +
+    `Creation shows repository context, name, template, and one confirmation. An existing\n` +
+    `repository association skips all prompts. An enrolled owner client may create an\n` +
+    `idempotent repository cube; ordinary clients\n` +
     `require an explicit cube grant. Agent seats begin only after enrollment. Preview only.\n` +
     `See docs/LOCAL_SERVER.md for self-hosted setup and current status.\n\n` +
     `For local or provider-specific models, configure the selected agent CLI directly.\n` +