borgmcp 3.9.0 → 3.11.0

package/docs/RELEASING.md

@@ -1,8 +1,9 @@
 # Publishing `borgmcp`
 
-The GitHub Actions workflow publishes one immutable, reviewed `borgmcp` version
-from a protected annotated tag. The protected publish job uses npm Trusted
-Publishing; no long-lived npm token is stored or exposed.
+The GitHub Actions workflow submits one immutable, reviewed `borgmcp` tarball to
+npm staged publishing from a protected annotated tag. A designated operator
+later approves that stage to make the version live. The protected stage job uses
+npm Trusted Publishing; no long-lived npm token is stored or exposed.
 
 ## Release Integrity
 
@@ -22,9 +23,9 @@ Before creating the release tag, independently verify all of these conditions:
 - the exact audited registry dependency `borgmcp-shared@0.11.0` remains locked to
   its canonical tarball and integrity
   `sha512-I8mixCbSrLKyOAAyqEI/HZJ8cML2rz3r812Up8pr547OdAk9LxZevdCo7ojG42ZwrUmS5u7iKQPg7Vk1XvtX1g==`;
-- the coupled client/server release is published only after the server artifact
-  is rebuilt against `borgmcp-shared@0.11.0` and both pass the complete local
-  dogfood gate;
+- the coupled shared/server/client candidates have all been built against the
+  same exact `borgmcp-shared` version and passed the complete local dogfood gate
+  before any stage is approved;
 - 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;
@@ -54,7 +55,9 @@ Before preparing a candidate, independently verify:
    existing `borgmcp` package. It must contain no npm token.
 2. npm Trusted Publishing is configured for organization `Byte-Ventures`,
    repository `borg-mcp-client`, workflow `publish.yml`, and environment
-   `npm-publish`.
+   `npm-publish`. Its allowed actions enable `npm stage publish` and disable
+   direct `npm publish`; package publishing requires two-factor authentication
+   and disallows tokens.
 3. `refs/tags/v*.*.*` cannot be updated, deleted, or force-moved. Release tags
    are annotated, match the package version, and point to a commit on protected
    `main`.
@@ -292,40 +295,97 @@ The unprivileged `verify` job performs one sequence:
    release artifact.
 
 After `verify` succeeds, the designated Queen operator alone approves the
-`npm-publish` environment. There is no separate pre-publication exact-artifact
+`npm-publish` environment. There is no separate pre-stage exact-artifact
 Security gate: the verify job is the mechanical authority for the exact bytes
-that the publish job consumes. Environment approval authorizes publication; it
-does not permit a rerun, a rebuilt artifact, or approval by another actor.
+that the stage job consumes. Environment approval authorizes submitting those
+bytes to npm's private staged-publishing service; it does not make the version
+public, permit a rerun or rebuilt artifact, or authorize approval by another
+actor.
 
 The protected `publish` job alone receives `id-token: write`. It downloads the
 same-run artifact and rejects a report whose package name or version differs
 from the release, a version that already exists, an unclaimed package, or an
 owner set that differs from `NPM_EXPECTED_OWNER`. It requires the GitHub OIDC
-request context, rejects a legacy `NODE_AUTH_TOKEN`, and publishes the exact
-tarball path once with lifecycle scripts disabled and provenance enabled. It
+request context, rejects a legacy `NODE_AUTH_TOKEN`, and stages the exact tarball
+path once with lifecycle scripts disabled and provenance enabled. It
 does not install project dependencies, rebuild, retest, repack, or reverify the
 package.
 
-Successful completion of `npm publish` is the terminal release boundary. There
-is no post-publication registry readback job: registry metadata and install
-visibility propagate asynchronously and cannot invalidate an immutable
-publication after npm accepts it.
+Successful completion of the workflow means npm accepted the immutable staged
+tarball. It does not mean the version is public. Stage acceptance consumes the
+tagged attempt and version under the burned-version rule, but must not trigger
+release announcements, issue closure, consumer pins, site synchronization, or
+claims that the version was published. There is no workflow registry readback:
+stage inspection and approval require an interactive npm identity and cannot use
+the workflow's OIDC credential.
+
+### Coupled stage approval
+
+Before approving anything, the operator requires successful stage workflows for
+`borgmcp-shared`, `borgmcp-server`, and `borgmcp`. Use authenticated
+`npm stage list` and `npm stage view <UUID>` to record and inspect all three stage
+UUIDs and verify each package, version, and eventual `latest` tag. For every
+package, `npm stage download <UUID>` is mandatory; compute its SHA-512 SRI and
+require an exact match with that workflow run's same-run artifact report. Bind
+the source annotated tag object, commit, and workflow run separately from GitHub
+evidence, because npm stage inspection does not expose them. Exercise the exact
+downloaded coupled set before approval. Confirm that public `latest`, public
+`versions`, and client update resolution still expose the prior coherent release
+set. If a pending stage appears on any public surface, approve nothing and halt
+this mechanism before consumers can observe it.
+
+Approve the verified UUIDs in one operator session, using interactive 2FA, in
+this exact order:
+
+1. `npm stage approve <shared-stage-uuid>`
+2. `npm stage approve <server-stage-uuid>`
+3. `npm stage approve <client-stage-uuid>`
+
+The approvals are not atomic. Shared approval leaves existing client and server
+pins coherent. Server approval opens a bounded mismatch window between public
+server `latest` and client `latest`; client approval closes it. After an approval
+returns successfully, continue only while the next stage remains valid. For an
+ambiguous result, inspect authenticated stage state and canonical public package
+version/integrity before acting; never repeat an approval blindly.
+
+The terminal release boundary is successful interactive stage approval followed
+by canonical registry visibility, integrity verification, and registry
+provenance-attestation inspection. Stage inspection cannot establish provenance
+before approval; Trusted Publishing carries it to the live package, where the
+registry attestation is authoritative. Only then may the release be announced,
+issues closed, consumer pins or site data synchronized, or the version described
+as published.
+
+After all three packages cross that boundary, create their GitHub Releases in
+the same shared → server → client operator session. In each package repository,
+run:
+
+```sh
+GITHUB_TOKEN="$(gh auth token)" node scripts/create-github-release.mjs <version>
+```
+
+The script binds the annotated tag, merged release pull request, successful tag
+workflow artifact, and live npm integrity before creating the Release. It copies
+the merged release pull request body verbatim and refuses an existing Release.
 
 Separately, once the release is installable from the canonical registry, install
 it into an isolated prefix and exercise the real user update path end to end.
-This is product verification, not publication validation: failure routes a new
+This is product verification, not candidate validation: failure routes a new
 reviewed fix and never invalidates, rebuilds, retags, or reruns the immutable
-release. Do not repeat byte comparisons, integrity/SRI checks, packed-version
-checks, source-tree verification, dist-tag readback, or provenance readback that
-the exact-artifact `verify` and publish jobs already completed.
+release. Do not repeat byte comparisons, packed-version checks, source-tree
+verification, dist-tag readback, or provenance reconstruction that the
+exact-artifact `verify` and stage jobs already completed. The canonical
+live-version integrity check is required because it establishes the approval
+boundary; it is not a duplicate candidate verification.
 
 No separate checksum file is needed: the tarball verifier records canonical
 SHA-512 SRI in the artifact report. GitHub's same-run artifact transport and the
 report bind the reviewed candidate without repeated SHA512 choreography.
 
-Rely on npm Trusted Publishing. Do not perform post-publication provenance
-readback or reconstruct DSSE, in-toto, SLSA, workflow-ref, or builder statements
-locally.
+Rely on npm Trusted Publishing. Perform the one authoritative registry
+provenance-attestation inspection at the approved-live boundary; do not
+reconstruct DSSE, in-toto, SLSA, workflow-ref, or builder statements locally or
+add redundant provenance readback.
 Do not add cross-run tuple variables, cross-run artifact selection, duplicate
 builds, duplicate package verification, checksum bundles, or SBOM ceremony.
 
@@ -336,3 +396,14 @@ authorization evidence is missing or inconsistent. Never move or reuse a failed
 tag, rerun a failed release workflow, overwrite an npm version, unpublish to hide
 a failure, or substitute a local rebuild. Recovery starts from a fresh reviewed
 source change and, after any registry mutation, a separately authorized version.
+
+Before any approval, missing or inconsistent stage evidence means approve none.
+Reject all three stages only when abandoning the coupled candidate; Borg treats
+every rejected or unusable tagged stage as burned, even though npm permits some
+re-staging. Replacement versions require fresh review, tags, and stage runs.
+After shared approval but before server approval, stopping is compatibility-safe
+for the existing client/server pair, but shared is immutable and any repair uses
+fresh versions. After server approval, prioritize the already-verified client
+approval because the public pair is mismatched. If that client stage cannot be
+approved, do not reject it or rerun the tag; prepare newly reviewed matching
+server/client recovery versions and state the live mismatch window explicitly.

package/package.json

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

package/src/assimilate-cmd.ts

@@ -126,6 +126,21 @@ export interface AssimilateArgs {
   mode?: 'assimilate' | 'cube-init';
 }
 
+export interface PreparedAssimilation {
+  cubeId: string;
+  cubeName: string;
+  droneId: string;
+  droneLabel: string;
+  roleName: string;
+  worktree: string;
+}
+
+export interface RunAssimilateOptions {
+  /** Internal composition seam for quickstart; the public assimilate command always launches. */
+  launch?: boolean;
+  onPrepared?: (prepared: PreparedAssimilation) => void;
+}
+
 export interface CubeSummary {
   id: string;
   name: string;
@@ -702,7 +717,8 @@ function diagnoseSessionTermination(
 
 export async function runAssimilate(
   args: AssimilateArgs,
-  deps: AssimilateDeps
+  deps: AssimilateDeps,
+  options: RunAssimilateOptions = {},
 ): Promise<number> {
   const mode = args.mode ?? 'assimilate';
   // ----- Input validation (before any subprocess work) -----
@@ -2033,6 +2049,24 @@ export async function runAssimilate(
     /* gh#793: orphan GC is best-effort — never block or fail the assimilate */
   }
 
+  // The project hook belongs to a prepared drone, not to the terminal handoff.
+  // Quickstart suppresses only that handoff and later launches through launch-all.
+  try {
+    deps.installProjectSessionHook(agentCwd);
+  } catch {
+    deps.stderr(`warning: could not install the project-local SessionStart hook in ${agentCwd}; it will be re-attempted on the next borg launch\n`);
+  }
+
+  options.onPrepared?.({
+    cubeId: result.cube_id,
+    cubeName: cubeDetail.name,
+    droneId: result.drone_id,
+    droneLabel: result.drone_label,
+    roleName: assignedRole.name,
+    worktree: seatWorktree,
+  });
+  if (options.launch === false) return 0;
+
   // ----- Step 8: Launch selected agent CLI -----
   // Mirrors the kickoff invocation from claude.ts (no-args path): the agent
   // picks up the newly-persisted ActiveCube via the MCP stdio server on
@@ -2060,17 +2094,6 @@ export async function runAssimilate(
     ),
   );
 
-  // gh#673 P2 (WI-1): install the project-local SessionStart orientation
-  // hook into the launch root — covers BOTH the freshly-spawned sibling
-  // worktree (agentCwd = the new worktree post-chdir) and the in-place /
-  // --here path. Best-effort: a hook-install failure must never block
-  // the assimilate (the bare-`borg` launcher re-ensures it).
-  try {
-    deps.installProjectSessionHook(agentCwd);
-  } catch {
-    deps.stderr(`warning: could not install the project-local SessionStart hook in ${agentCwd}; it will be re-attempted on the next borg launch\n`);
-  }
-
   // BUG-5 / v0.9.3: probe MCP readiness before launching claude so
   // the launched session sees tools at startup. Non-blocking: probe
   // failure surfaces a stderr warning but the launch proceeds (the

package/src/claude.ts

@@ -42,8 +42,12 @@ import { runSpawn } from './spawn.js';
 import { buildClaudeLaunchArgs } from './claude-launch-args.js';
 import { parseCleanupArgs, runCleanup } from './cleanup-cmd.js';
 import { parseAssimilateArgs } from './parse-assimilate-args.js';
+import { parseQuickstartArgs } from './parse-quickstart-args.js';
+import { parseCloneArgs, safeCloneParseError } from './parse-clone-args.js';
 import { runAssimilate } from './assimilate-cmd.js';
 import { buildDefaultAssimilateDeps } from './assimilate-deps.js';
+import { buildDefaultQuickstartDeps, runQuickstart } from './quickstart-cmd.js';
+import { buildDefaultCloneDeps, runClone } from './clone-cmd.js';
 import {
   parseResetLocalSeatArgs,
   runResetLocalSeat,
@@ -251,6 +255,24 @@ async function main() {
     const code = await runAssimilateEntry(process.argv.slice(3));
     process.exit(code);
   }
+  if (process.argv[2] === 'clone') {
+    const parsed = parseCloneArgs(process.argv.slice(3));
+    if (!parsed.ok) {
+      process.stderr.write(chalk.red(`${consolePrefix()}◼ borg clone: ${safeCloneParseError(parsed)}\n`));
+      process.stderr.write(`Run \`borg clone --help\` for usage.\n`);
+      process.exit(1);
+    }
+    process.exit(await runClone(parsed.args, buildDefaultCloneDeps()));
+  }
+  if (process.argv[2] === 'quickstart') {
+    const parsed = parseQuickstartArgs(process.argv.slice(3));
+    if (!parsed.ok) {
+      process.stderr.write(chalk.red(`${consolePrefix()}◼ borg quickstart: ${parsed.error}\n`));
+      process.stderr.write(`Run \`borg quickstart --help\` for usage.\n`);
+      process.exit(1);
+    }
+    process.exit(await runQuickstart(parsed.args, buildDefaultQuickstartDeps()));
+  }
   if (process.argv[2] === 'reset-local-connection') {
     const parsed = parseResetLocalSeatArgs(process.argv.slice(3));
     if (!parsed.ok) {
@@ -301,11 +323,11 @@ async function main() {
     const code = await runCleanup({}, parsed.options);
     process.exit(code);
   }
-  if (process.argv[2] === 'seats') {
+  if (process.argv[2] === 'drones') {
     const parsed = parseSeatsArgs(process.argv.slice(3));
     if (!parsed.ok) {
-      process.stderr.write(chalk.red(`${consolePrefix()}◼ borg seats: ${parsed.error}\n`));
-      process.stderr.write(`Run \`borg seats --help\` for usage.\n`);
+      process.stderr.write(chalk.red(`${consolePrefix()}◼ borg drones: ${parsed.error}\n`));
+      process.stderr.write(`Run \`borg drones --help\` for usage.\n`);
       process.exit(1);
     }
     process.exit(await runSeats(buildDefaultSeatCommandDeps()));

package/src/cli-help.ts

@@ -51,12 +51,41 @@ export function launchAllHelpText(version: string): string {
   );
 }
 
+export function quickstartHelpText(version: string): string {
+  return (
+    `borg quickstart (borgmcp ${version}) — create, staff, and launch this repository's cube\n\n` +
+    `Usage:\n` +
+    `  borg quickstart [options]\n\n` +
+    `Options:\n` +
+    `  --template ${NEW_CUBE_TEMPLATE_OPTIONS}  Choose the new-cube template without prompting\n` +
+    `  --role <slug>[:<count>]            Fully specify the roster (repeatable)\n` +
+    `  --yes, -y                          Accept the displayed plan\n` +
+    `  --help, -h                         Show this help\n\n` +
+    `Quickstart requires a running Borg server and never starts one. Rerun the same\n` +
+    `command after a partial failure; existing drones are kept and skipped.\n`
+  );
+}
+
+export function cloneHelpText(version: string): string {
+  return (
+    `borg clone (borgmcp ${version}) — clone a repository and run quickstart\n\n` +
+    `Usage:\n` +
+    `  borg clone <repository-url> [directory] [--no-launch]\n\n` +
+    `Options:\n` +
+    `  --no-launch  Stop after the checkout is ready; do not create or launch a cube\n` +
+    `  --help, -h   Show this help\n\n` +
+    `A repeated command reuses a checkout only when its origin matches. Default\n` +
+    `destination names avoid non-repository collisions. Credential-bearing URLs are\n` +
+    `refused; use a Git credential helper or SSH configuration instead.\n`
+  );
+}
+
 export function seatsHelpText(version: string): string {
   return (
-    `borg seats (borgmcp ${version}) — list this machine's registered drones\n\n` +
+    `borg drones (borgmcp ${version}) — list this machine's registered drones\n\n` +
     `Usage:\n` +
-    `  borg seats          Show drone, cube, worktree, agent CLI, and local state\n` +
-    `  borg seats --help   Show this help\n\n` +
+    `  borg drones         Show drone, cube, worktree, agent CLI, and local state\n` +
+    `  borg drones --help  Show this help\n\n` +
     `The local registry belongs to this machine only.\n`
   );
 }
@@ -91,11 +120,13 @@ export function clientSubcommandHelpText(
   if (!args.some(isHelpFlag)) return null;
   switch (command) {
     case 'setup': return setupHelpText(version);
+    case 'clone': return cloneHelpText(version);
     case 'assimilate': return assimilateHelpText(version);
+    case 'quickstart': return quickstartHelpText(version);
     case 'reset-local-connection': return resetLocalSeatHelpText(version);
     case 'recover-enrollment': return recoverEnrollmentHelpText(version);
     case 'cleanup': return cleanupHelpText(version);
-    case 'seats': return seatsHelpText(version);
+    case 'drones': return seatsHelpText(version);
     case 'launch': return launchSeatHelpText(version);
     case 'launch-all': return launchAllHelpText(version);
     case 'doctor': return doctorHelpText(version);
@@ -107,7 +138,7 @@ export function setupNextStepsText(): string {
   return (
     `◼ Next steps:\n` +
     `1. Run \`borg server start\` and leave that terminal open.\n` +
-    `2. In a second terminal, cd into your project's Git repository and run \`borg assimilate\`.\n`
+    `2. In a second terminal, cd into your project's Git repository and run \`borg quickstart\`.\n`
   );
 }
 
@@ -129,6 +160,8 @@ export function topLevelHelpText(version: string): string {
     `  borg setup               Set up borg MCP server + agent CLI integration\n` +
     `  borg update              Update the client and installed local server together\n` +
     `  borg doctor              Check agent hook commands, versions, configs, and the OpenCode plugin\n` +
+    `  borg clone <url> [dir]   Clone a repository, then create and launch its cube\n` +
+    `  borg quickstart          Create a cube and a drone for every role, then launch them\n` +
     `  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` +
@@ -136,7 +169,7 @@ export function topLevelHelpText(version: string): string {
     `  borg reset-local-connection  Clear ONLY this worktree's saved connection to its cube (offline; after a rejection)\n` +
     `  borg recover-enrollment  Restore or clear ONLY one failed server enrollment transaction\n` +
     `  borg cleanup [--prune]   Report (or --prune) worktrees orphaned by evicted drones\n` +
-    `  borg seats               List this machine's registered drones and worktrees\n` +
+    `  borg drones              List this machine's registered drones and worktrees\n` +
     `  borg launch <drone-label-or-id-prefix>  Reopen one registered drone from its worktree\n` +
     `  borg launch-all [cube]   Launch all drone worktrees of a cube (default: active cube)\n` +
     `  borg server <command> [arguments]\n` +

package/src/clone-cmd.ts

@@ -0,0 +1,243 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { basename, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hasCloneCredentials, redactCloneSecrets } from './clone-security.js';
+import type { CloneArgs } from './parse-clone-args.js';
+import { buildDefaultQuickstartDeps, runQuickstart } from './quickstart-cmd.js';
+import { shellEscape } from './shell-escape.js';
+
+export interface GitRunResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export interface CloneDeps {
+  cwd: () => string;
+  chdir: (path: string) => void;
+  runSync: (cmd: string, args: string[], cwd?: string) => GitRunResult;
+  pathExists: (path: string) => boolean;
+  isDirectory: (path: string) => boolean;
+  readDirectory: (path: string) => string[];
+  createDirectory: (path: string) => boolean;
+  removeTree: (path: string) => void;
+  quickstart: (cwd: string) => Promise<number>;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+}
+
+const CONTROL_RE = /[\u0000-\u001f\u007f]/;
+const ALLOWED_SCHEMES = new Set(['file:', 'git:', 'git+ssh:', 'http:', 'https:', 'ssh:']);
+const SCP_REMOTE_RE = /^[^@\s/:]+@[^:\s]+:[^\s]+$/;
+
+function defaultRunSync(cmd: string, args: string[], cwd?: string): GitRunResult {
+  const result = spawnSync(cmd, args, { cwd, encoding: 'utf8' });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? (result.error instanceof Error ? result.error.message : ''),
+  };
+}
+
+export function buildDefaultCloneDeps(): CloneDeps {
+  return {
+    cwd: () => process.cwd(),
+    chdir: (path) => process.chdir(path),
+    runSync: defaultRunSync,
+    pathExists: existsSync,
+    isDirectory: (path) => {
+      try { return statSync(path).isDirectory(); } catch { return false; }
+    },
+    readDirectory: (path) => readdirSync(path),
+    createDirectory: (path) => {
+      mkdirSync(dirname(path), { recursive: true });
+      try {
+        mkdirSync(path);
+        return true;
+      } catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'EEXIST') return false;
+        throw error;
+      }
+    },
+    removeTree: (path) => rmSync(path, { recursive: true, force: true }),
+    quickstart: async (cwd) => {
+      process.chdir(cwd);
+      return runQuickstart({ roles: [], yes: false }, buildDefaultQuickstartDeps());
+    },
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+  };
+}
+
+export function validateCloneRepositoryUrl(value: string): { ok: true } | { ok: false; error: string } {
+  if (!value || value.trim() !== value || /\s/.test(value) || CONTROL_RE.test(value)) {
+    return { ok: false, error: 'repository URL contains whitespace or control characters' };
+  }
+  if (value.startsWith('-')) return { ok: false, error: 'repository URL must not start with a hyphen' };
+  if (hasCloneCredentials(value)) {
+    return { ok: false, error: 'credential-bearing repository URLs are not accepted; use a credential helper or SSH configuration instead' };
+  }
+  if (SCP_REMOTE_RE.test(value)) return { ok: true };
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1];
+  if (!scheme) return { ok: true }; // Local path.
+  if (!value.toLowerCase().startsWith(`${scheme.toLowerCase()}://`) && scheme.toLowerCase() !== 'file') {
+    return { ok: false, error: 'repository URL is not a supported hierarchical URL' };
+  }
+  try {
+    const parsed = new URL(value);
+    if (!ALLOWED_SCHEMES.has(parsed.protocol)) return { ok: false, error: `unsupported repository URL scheme ${parsed.protocol}` };
+    if (parsed.search || parsed.hash) return { ok: false, error: 'repository URLs with query strings or fragments are not accepted' };
+    if (parsed.protocol !== 'file:' && !parsed.hostname) return { ok: false, error: 'repository URL must include a host' };
+    if (!parsed.pathname || parsed.pathname === '/') return { ok: false, error: 'repository URL must include a repository path' };
+    return { ok: true };
+  } catch {
+    return { ok: false, error: 'repository URL is not valid' };
+  }
+}
+
+function sourceName(value: string): string {
+  let leaf = value;
+  try {
+    const parsed = new URL(value);
+    leaf = parsed.protocol === 'file:' ? fileURLToPath(parsed) : parsed.pathname;
+  } catch {
+    if (SCP_REMOTE_RE.test(value)) leaf = value.slice(value.indexOf(':') + 1);
+  }
+  const name = basename(leaf.replace(/\/+$/, '')).replace(/\.git$/i, '')
+    .replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  return name || 'repository';
+}
+
+function remoteKey(value: string, base: string): string {
+  if (SCP_REMOTE_RE.test(value)) {
+    const colon = value.indexOf(':');
+    const login = value.slice(0, colon);
+    const at = login.lastIndexOf('@');
+    const user = login.slice(0, at);
+    const host = login.slice(at + 1).toLowerCase();
+    return `ssh://${user}@${host}/${value.slice(colon + 1).replace(/\/+$/, '').replace(/\.git$/i, '')}`;
+  }
+  try {
+    const parsed = new URL(value);
+    if (parsed.protocol === 'file:') return `file:${resolve(fileURLToPath(parsed))}`;
+    const user = parsed.username ? `${parsed.username}@` : '';
+    const port = parsed.port ? `:${parsed.port}` : '';
+    return `${parsed.protocol}//${user}${parsed.hostname.toLowerCase()}${port}${parsed.pathname.replace(/\/+$/, '').replace(/\.git$/i, '')}`;
+  } catch {
+    return `file:${resolve(base, value)}`;
+  }
+}
+
+function readOrigin(deps: CloneDeps, directory: string): string | null {
+  const result = deps.runSync('git', ['remote', 'get-url', 'origin'], directory);
+  return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : null;
+}
+
+function repositoryAt(deps: CloneDeps, directory: string): boolean {
+  return deps.runSync('git', ['rev-parse', '--is-inside-work-tree'], directory).status === 0;
+}
+
+function validateDestination(value: string): string | null {
+  if (!value || value.trim() !== value || CONTROL_RE.test(value) || value.startsWith('-') || hasCloneCredentials(value)) {
+    return 'destination contains an unsafe path value';
+  }
+  return null;
+}
+
+function chooseDestination(deps: CloneDeps, args: CloneArgs): { path: string } | { error: string } {
+  const base = deps.cwd();
+  if (args.destination !== undefined) {
+    const error = validateDestination(args.destination);
+    return error ? { error } : { path: resolve(base, args.destination) };
+  }
+  const name = sourceName(args.repositoryUrl);
+  for (let n = 1; n < 10_000; n += 1) {
+    const candidate = resolve(base, n === 1 ? name : `${name}-${n}`);
+    if (!deps.pathExists(candidate)) return { path: candidate };
+    if (deps.isDirectory(candidate) && repositoryAt(deps, candidate)) {
+      const origin = readOrigin(deps, candidate);
+      if (origin && !hasCloneCredentials(origin) && remoteKey(origin, candidate) === remoteKey(args.repositoryUrl, base)) {
+        return { path: candidate };
+      }
+      if (n === 1) return { error: `existing checkout at ${candidate} points at another remote; choose an explicit destination` };
+    }
+  }
+  return { error: `could not find a collision-safe destination for ${name}` };
+}
+
+export async function runClone(args: CloneArgs, rawDeps: CloneDeps): Promise<number> {
+  const deps: CloneDeps = {
+    ...rawDeps,
+    stdout: (text) => rawDeps.stdout(redactCloneSecrets(text)),
+    stderr: (text) => rawDeps.stderr(redactCloneSecrets(text)),
+  };
+  const valid = validateCloneRepositoryUrl(args.repositoryUrl);
+  if (!valid.ok) {
+    deps.stderr(`borg clone: ${valid.error}.\n`);
+    return 1;
+  }
+  const selected = chooseDestination(deps, args);
+  if ('error' in selected) {
+    deps.stderr(`borg clone: ${selected.error}.\n`);
+    return 1;
+  }
+  const destination = selected.path;
+  let cloned = false;
+  const destinationExisted = deps.pathExists(destination);
+  const emptyDestination = destinationExisted && deps.isDirectory(destination) && deps.readDirectory(destination).length === 0;
+  if (destinationExisted && !emptyDestination) {
+    if (!deps.isDirectory(destination) || !repositoryAt(deps, destination)) {
+      deps.stderr(`borg clone: destination ${destination} exists and is not a Git checkout; it was left untouched.\n`);
+      return 1;
+    }
+    const origin = readOrigin(deps, destination);
+    if (!origin || hasCloneCredentials(origin)) {
+      deps.stderr(`borg clone: the existing checkout has no safe, readable origin remote; it was left untouched.\n`);
+      return 1;
+    }
+    if (remoteKey(origin, destination) !== remoteKey(args.repositoryUrl, deps.cwd())) {
+      deps.stderr(`borg clone: remote mismatch at ${destination}; existing ${origin}, requested ${args.repositoryUrl}. The checkout was left untouched.\n`);
+      return 1;
+    }
+    deps.stdout(`Reusing existing checkout at ${destination}; its origin remote matches.\n`);
+  } else {
+    const createdDestination = destinationExisted ? false : deps.createDirectory(destination);
+    if (!destinationExisted && !createdDestination) {
+      deps.stderr(`borg clone: destination ${destination} appeared while preparing the clone; it was left untouched. Retry with another directory.\n`);
+      return 1;
+    }
+    const result = deps.runSync('git', ['clone', '--', args.repositoryUrl, destination], deps.cwd());
+    if (result.status !== 0) {
+      if (createdDestination && deps.pathExists(destination)) {
+        deps.removeTree(destination);
+      }
+      deps.stderr(
+        `borg clone: clone failed${result.stderr.trim() ? `: ${result.stderr.trim()}` : ''}.\n` +
+        `Rollback: ${destinationExisted
+          ? `the pre-existing empty destination ${destination} was preserved; inspect it for partial Git files`
+          : deps.pathExists(destination) ? `partial checkout remains at ${destination}` : `the directory borg created at ${destination} was removed`}.\n`,
+      );
+      return 1;
+    }
+    cloned = true;
+    deps.stdout(`Cloned ${sourceName(args.repositoryUrl)} into ${destination}.\n`);
+  }
+
+  if (args.noLaunch) {
+    deps.stdout(
+      `Checkout ready at ${destination}. No cube or drone was created.\n` +
+      `Next: cd ${shellEscape(destination)} && borg quickstart\n`,
+    );
+    return 0;
+  }
+  deps.chdir(destination);
+  const code = await deps.quickstart(destination);
+  if (code !== 0) {
+    deps.stderr(
+      `The checkout${cloned ? '' : ' you already had'} is ready at ${destination}, but quickstart did not finish. ` +
+      `It was left untouched; cd there and run \`borg quickstart\` again.\n`,
+    );
+  }
+  return code;
+}